Writing Tool Instructions for AI Agents

Tool Descriptions Are Prompts When an agent decides which tool to call and what arguments to pass, it relies almost entirely on text you wrote: each tool's name, its description, the descriptions of its parameters, and the tool guidance in the agent's instructions. Tool descriptions are therefore prompts, and they deserve the same care.

Lesson 78 introduced tool definitions and showed how vague descriptions cause wrong tool choices. This lesson goes deeper into writing tool instructions for agents that use many tools over many steps, where small ambiguities compound:

How to describe a tool completely How to design parameters the model fills correctly How to design results and errors the agent can act on How to describe relationships between tools How to check tool definitions automatically The Anatomy of a Complete Tool Description A strong tool description answers six questions:

Question Example for get_enrollment What does it do? Looks up the current student's enrollment What does it return? Course name, days since purchase, progress percentage When should it be used? Before answering questions about the student's own course, progress, or refund eligibility When should it not be used? Not for general course information (use search_catalog) or for other students What are its limits? Only finds enrollments for the email the student provided Does it change anything? No; it is read-only Example Look up the current student's enrollment by email. Returns the course name, days since purchase, and progress percentage. Use this before answering questions about the student's own course, progress, or refund eligibility. Do not use it for general course information (use search_catalog) or to look up other students. Read-only: it does not change any data. Why Each Part Matters What it returns lets the agent know whether calling the tool will give it what it needs, before calling it. When to use it and when not to are the main inputs to tool selection. "When not" is especially important when tools overlap. Read-only vs side effects tells the agent how careful to be. Tools that change data need explicit confirmation rules. Naming Tools Guideline Good Weak Use verb_object get_enrollment, issue_refund enrollment, refund Make the effect clear from the verb get_, search_, create_, update_, send_ handle_, process_ Keep names consistent across tools get_course, get_enrollment get_course, fetch_enrollment_info Avoid near-duplicates One search_docs search_docs and find_documents Verbs carry meaning: get_ suggests a read, issue_ and send_ suggest actions with consequences. A model reading process_refund cannot tell whether it checks eligibility or sends money.

Designing Parameters Describe Every Parameter, With a Format and an Example "email": { "type": "string", "description": "The email address the student gave in this conversation, e.g. 'asha@example.com'. " "Never guess or construct an email.", } The instruction "never guess or construct" addresses a common failure: agents inventing plausible argument values, such as asha@gmail.com, when the real value is unknown.

Use Enums for Fixed Sets "doc_type": { "type": "string", "enum": ["policy", "faq", "course_page"], "description": "The type of document to search.", } Enums prevent invalid values such as "policies" or "FAQ page" (Lesson 99).

Use Units in Names or Descriptions amount_rupees or "Amount in rupees, as an integer" prevents confusion between rupees and paise, or between amounts with and without tax.

Keep Parameters Few and Necessary Each extra parameter is another value the model must get right. Prefer tools with two or three clear parameters over one tool with ten optional ones.

Make Missing Values Explicit In strict schemas, every parameter is required (Lesson 99). For values that can be unknown, use a nullable type and explain when to use null:

"course_name": { "type": ["string", "null"], "description": "The course name if the student mentioned one; null if they did not.", } Designing Tool Results and Errors What a tool returns is the agent's observation (Lesson 111). Results should be easy for the model to interpret and act on.

Return Structured, Labeled Results {"course": "Django REST APIs", "days_since_purchase": 4, "progress_percent": 12} Field names with units, such as progress_percent, prevent misreading.

Return Errors That Explain What to Do Weak Error Helpful Error "Error 404" {"error": "No enrollment found for this email. Ask the student to confirm the email they used to register."} "Invalid input" {"error": "amount_rupees must be a positive integer, e.g. 4999."} "Failed" {"error": "Payment service is temporarily unavailable. Do not retry more than once; offer a handover."} A helpful error says what went wrong and what to do next. Agents recover much better from errors that suggest an action (Lesson 113).

Keep Results Short Return only what the agent needs. Large results, such as full database records or long documents, increase cost and can distract the agent. Summarize or filter in the tool, not in the prompt.

Describing Relationships Between Tools Individual descriptions cannot explain how tools work together. Put that in the agent's instructions:

Tool order:

• Before discussing a student's refund, call get_enrollment, then search_docs for the refund policy, and compare them.
• Call issue_refund only after both checks show eligibility and the student has confirmed.
• If get_enrollment finds no enrollment, do not call issue_refund; ask the student to check their email, or hand over. Why This Belongs in the Agent Prompt Each tool description describes one tool. Rules about sequence and prerequisites, such as "check before acting", involve several tools and the agent's overall goal. Placing them in the agent's instructions keeps tool descriptions focused and the workflow rules in one place.

How Many Tools? As the number of tools grows, choosing the right one becomes harder, especially when descriptions overlap.

Situation Approach A few distinct tools Provide them all Many tools for different tasks Provide only the tools relevant to the current task or conversation stage Tools with overlapping purposes Merge them, or make the differences explicit in both descriptions Rarely used, risky tools Exclude them unless the task requires them Providing fewer, well-described tools usually produces better tool selection than providing many similar ones.

Checking Tool Definitions Automatically A simple linter, a program that checks for common problems, can review tool definitions before they reach the agent.

import re

def lint_tool(tool: dict) -> list[str]: """Return a list of problems in a tool definition.""" problems = [] name, description = tool.get("name", ""), tool.get("description", "") if not re.fullmatch(r"[a-z]+(_[a-z]+)+", name): problems.append("name should be verb_object in snake_case, e.g. get_course") if len(description) < 60: problems.append("description is too short to explain purpose and usage") if not re.search(r"\buse (this|it) (when|for|whenever)\b", description, re.IGNORECASE): problems.append("description should say when to use the tool") if tool.get("side_effects") and not re.search(r"confirm", description, re.IGNORECASE): problems.append("tool has side effects but does not mention confirmation") for parameter, spec in tool.get("parameters", {}).get("properties", {}).items(): if not spec.get("description"): problems.append(f"parameter '{parameter}' has no description") return problems

tools = [ {"name": "get_course", "description": "Look up a course in the catalog and return its fee and seats left. " "Use this when the user asks about price or availability.", "parameters": {"properties": { "course_name": {"type": "string", "description": "Course name as the user wrote it."}}}}, {"name": "refund", "description": "Refund a payment.", "side_effects": True, "parameters": {"properties": { "payment_id": {"type": "string"}, "amount": {"type": "integer", "description": "Amount in rupees."}}}}, ]

for tool in tools: print(tool["name"], lint_tool(tool)) Output:

get_course [] refund ['name should be verb_object in snake_case, e.g. get_course', 'description is too short to explain purpose and usage', 'description should say when to use the tool', 'tool has side effects but does not mention confirmation', "parameter 'payment_id' has no description"] Code Explanation Name check: requires lowercase words joined by underscores, with at least two words, which encourages the verb_object pattern. refund fails. Description length: a very short description cannot explain purpose, results, and usage. Usage guidance: the description should contain a phrase such as "Use this when". Side effects: side_effects is a field you add to your own tool records (it is not sent to the API). Tools that change data must mention confirmation. Parameters: every parameter needs a description. payment_id has none. Using the Linter Run it in your test suite, so every new or changed tool definition is checked automatically. The checks are simple heuristics: passing them does not guarantee a good description, but failing them reliably identifies weak ones.

Testing Tool Instructions Tool instructions should be tested with realistic requests, measuring:

Measure Question Selection accuracy Did the agent choose the expected tool, or correctly choose none? Argument accuracy Were the arguments correct, with no invented values? Order Were prerequisites checked before actions? Error recovery After a tool error, did the agent follow the error's guidance? Build a test set of requests with expected tools and arguments (Lesson 78), and re-run it whenever tool descriptions change. Treat tool descriptions like prompts: version them (Lesson 67) and evaluate changes (Lesson 66).

Common Mistakes Mistake 1: Describing Only What the Tool Does What it is: "Searches documents."

Why it happens: The function's purpose seems sufficient.

What it causes: The agent does not know what it will get back or when to use the tool instead of another.

How to fix it: Describe results, when to use, when not to use, limits, and side effects.

Mistake 2: Parameters Without Guidance What it is: Parameters with only a type, such as email: string.

Why it happens: The meaning seems obvious.

What it causes: Wrong formats and invented values.

How to fix it: Describe each parameter with format, example, and what to do if it is unknown.

Mistake 3: Unhelpful Errors What it is: Tools that return "Error" or raise exceptions.

Why it happens: Errors are designed for developers, not agents.

What it causes: Agents that retry blindly or give up.

How to fix it: Return structured errors that explain what went wrong and what to do next.

Mistake 4: Overlapping Tools What it is: Several tools that could answer the same request.

Why it happens: Tools are added for different features over time.

What it causes: Inconsistent tool selection.

How to fix it: Merge overlapping tools, or state the difference clearly in each description.

Mistake 5: Workflow Rules Hidden in Tool Descriptions What it is: Sequence rules spread across several tool descriptions.

Why it happens: Each tool is written separately.

What it causes: Incomplete or contradictory rules.

How to fix it: Put rules about order and prerequisites in the agent's instructions.

Best Practices Treat tool descriptions as prompts. Write, test, version, and review them.

Answer the six questions in every description. What, returns, when, when not, limits, side effects.

Name tools with clear verbs. Consistent verb_object names.

Design parameters carefully. Descriptions, formats, examples, enums, units, and nullable values.

Return helpful results and errors. Short, labeled, and actionable.

Describe tool relationships in the agent prompt. Order, prerequisites, and confirmation rules.

Lint and test tool definitions. Automatically, and with realistic requests.

Try It Yourself Exercise 1: Rewrite Weak Tools Rewrite the refund tool from the linter example as issue_refund, with a complete description, described parameters, and a confirmation rule. Run lint_tool() until it reports no problems.

Exercise 2: Design Error Messages For the tools get_enrollment, search_docs, and issue_refund, write three realistic error cases each, with helpful error messages that explain what to do next. Test one error with the agent from Lesson 108 and check whether it follows the guidance.

Exercise 3: Tool Selection Test Write 15 requests for an agent with four tools: search_docs, get_enrollment, search_catalog, and issue_refund. Include requests that need no tool, one tool, and several tools in order. Run them, record the tools and arguments chosen, and improve the descriptions where selection was wrong.