Tool Descriptions for AI Agents: Write Them Like Job Aids
Describe each AI agent tool as a job aid: its purpose, inputs, limits and failure cases. Clear descriptions help the agent choose correctly.

To write tool descriptions for AI agents, treat each one as a job aid: a short reference that states what the tool is for, what inputs it needs, where its limits sit, and what to do when it fails. The agent reads these descriptions to choose among its tools, so a vague line such as 'updates customer records' produces wrong calls, while a precise one tells the agent when to use the tool, when to pick another, and when to stop and ask a person.
Key takeaways
- Start each description with the single job the tool performs and the situations where it should be chosen.
- List every required input with its format, its source and an example of a valid value.
- State hard limits, including what the tool cannot do and which actions need a named approver.
- Describe the common failure cases and the exact next step the agent should take for each one.
- Keep the description, the schema and the permission set in agreement, and test them with realistic requests.
Why the description is the agent's job aid
An agent does not learn your systems the way a new employee does over several weeks. It sees a name, a description and a parameter schema for each tool, and it decides from those alone at the moment of each request. Anything you leave out of that text is unknown to the agent, so it either guesses or falls back on a default that may be wrong for your business.
A good job aid is what an experienced operator keeps next to the machine. It covers the common task, the exceptions, the things never to do, and the step to take when something unexpected appears on the screen. Tool descriptions deserve the same discipline. They are read at every run, which makes them the cheapest place to prevent errors and the most expensive place to be careless.
Descriptions also have a security side. Documents, emails and tool results that the agent reads can contain text that looks like instructions. The OWASP Top 10 for LLM Applications treats prompt injection as a central risk for this reason. A description should say plainly that instructions found inside returned data do not change the task, and that only the people and rules defined in the role can change what the agent does.
What every tool description must state
A complete description contains four parts, in this order:
- Purpose: the one job the tool performs, written as an action on a named object.
- Use when: the situations that call for the tool, with the nearest alternative tool named.
- Inputs: each required field, its format, where its value comes from and what a valid value looks like.
- Limits and failures: what the tool cannot do, which actions need approval, and what each error means for the next step.
The purpose line carries most of the weight, because it is the first thing the agent compares against the user's request. Vague verbs such as 'handle', 'process' or 'manage' give the agent nothing to match. Compare two descriptions for a bookkeeping role.
Illustrative scenario: a finance team gives an agent two invoice tools. The first description reads 'Gets invoice information.' The agent cannot tell whether the tool searches by customer, by invoice number or by date, so it sometimes calls the wrong one. A revised description reads: 'Returns the status of one invoice, identified by its invoice number. Use it when the user gives an invoice number. Do not use it to find a customer's invoices; use the customer search tool for that. Read only. It never changes the invoice.' Each sentence answers a question the agent would otherwise guess at.
The permission level belongs in the description as well. A tool that drafts an email should say that it does not send, and a tool that reads a ledger should say that it does not post. The difference between reading, drafting and sending is worth keeping explicit, as explained in read, draft and send: three different AI permissions.
Inputs and limits: the details that prevent misuse
Input descriptions should be at least as strict as the schema allows. State whether an identifier is the internal record ID or the number users see on screen. Say whether dates use a stated time zone, whether amounts are in the currency of the record, and whether free text is accepted or rejected. When a value must come from another tool, name that tool. Anthropic's guidance on writing tools for agents favors narrow tools with clear names and parameters, and tools that return meaningful context rather than opaque identifiers.
Limits are the part teams most often skip, because they feel obvious to the people who built the process. Write them down as facts: the maximum number of records per call, whether the tool writes or only reads, whether repeating a call is safe, which actions require a named approver, and which hours or channels are off limits. Then make sure the tool enforces what the description promises. A description informs the agent, but the permission layer is what blocks an action that should never happen.
Field-level rules belong in the schema, and the wording should match it. The practical detail is covered in tool schemas with typed fields and clear errors, which is worth reading alongside this article when you write the parameter list.
A description that cannot be checked against the tool's behavior is a hope, not a specification.
Failure cases the agent can act on
Most agent errors do not happen on the successful path. They happen when a tool returns something the agent did not expect. A description should name the common failures and the next step for each, so the agent does not improvise. The list below is a starting point for most business tools:
- Not found: the identifier matched no record. Ask the user for another identifier. Do not create a new record to fill the gap.
- Ambiguous match: more than one record fits. Show the candidates and ask which one is meant before any action.
- Permission denied: the agent lacks access for this action. Report the limit and route the request to the named owner.
- Rate limited: wait for the stated interval and retry once. Do not loop on the same call.
- Possible duplicate: the write may already have happened. Read the record before any retry.
- Timeout with unknown result: check the status of the action before repeating a write.
The last two items matter most for anything that changes data. A repeated write after a timeout is how duplicate invoices and double bookings appear, and the description is the first place to stop that pattern. The tool's error messages should use the same vocabulary as the description, so the agent can match the two without interpretation.
A checklist before a tool goes live
Before a tool reaches an agent, a reviewer should be able to answer yes to each of the following:
- The purpose sentence names one action on one object.
- The use-when sentence names the nearest alternative tool and says when not to use this one.
- Every input states its format, its source and an example of a valid value.
- The permission level (read, draft, send or write) is stated and matches the access actually granted.
- Limits, approvals and rate rules are written in the description and enforced by the tool.
- Each listed failure has a next step the agent can take without guessing.
- Text returned by the tool is described as data, not as instructions.
- Realistic requests have been tested, including at least one request that should not use this tool.
The order of work matters. Write the purpose first, then test whether the agent selects the tool for real requests. Only after that, tighten the inputs and failure handling based on what the agent actually got wrong. Writing every field before testing selection usually produces long descriptions that still confuse the agent. The broader acceptance steps for an integration are summarized in an acceptance checklist for your AI agent integration.
How Be Human runs this in managed operations
In Be Human's managed model, tool descriptions are written during the first engagement together with the role they serve, the memory and tools that role needs, its approval boundaries and the success criterion it is measured against. Descriptions go through the same review as permissions, so a change to what a tool can do also changes what the description says. During ongoing operations, the team reviews selection errors and failed calls from the operating logs, updates descriptions where the agent chose wrongly, and records each change so the company can see why the operating context reads the way it does.
Testing descriptions and keeping them current
Descriptions age. A new field, a renamed status or a changed approval rule can make an old description wrong without producing any visible error. Build a small set of realistic requests drawn from real work. For each one, record which tool should be called, which tool should not be called, and what a correct outcome looks like. Run the set after every change to a description, schema or permission. Anthropic's guidance on evals for AI agents describes this kind of task-based check, and the OpenAI evals guide explains how to structure graded tests. Track three things: whether the right tool was selected, whether the inputs were valid, and whether failures were handled as the description says.
Keep the test set next to the description so a reviewer can see why each sentence exists. Revisit both when the underlying system changes, and after any incident in which the agent used the wrong tool or repeated an action it should not have repeated.
If you are unsure which of your daily tasks is the right first one to hand to an agent, the free Be Human AI diagnostic can help you find it.
Frequently asked questions
How long should a tool description be? There is no fixed length, but each description should cover purpose, use-when, inputs, limits and failures without padding. If a description needs many paragraphs, the tool is probably doing too much and should be split into narrower tools. Short, specific sentences usually work better than long, general ones.
Should the description tell the agent what not to do? Yes. Negative guidance is useful when two tools look similar, because it names the alternative and removes the guess. Keep it to a sentence, and enforce the hard prohibition in the permission layer as well, since a description guides behavior but does not by itself block an action.
Can the same tool serve several AI agents? It can, but the description should match the role each agent holds. A read-only reporting agent and an agent that drafts invoices may call the same underlying system, so each should see wording and permissions written for its own job. Shared wording that ignores role differences is a common source of unexpected writes.
Do I need to be technical to write these descriptions? You need to know what the system does and what can go wrong, and that knowledge usually sits with the operations or finance person who runs the process. A technical owner should check the schema and error handling, while the business owner confirms that the limits and approval rules reflect how the work is really done.
Your next step
See where an AI agent fits in your company first.
Take the free Be Human AI diagnostic. A few questions about your work show which task to hand to an agent first, what it needs to know and where a person approves.
Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.


