Skip to content

Grokem · https://www.grokem.com/ai-and-machine-learning/ai-agents/tool-calling/how-to-write-ai-agent-tool-descriptions-and-schemas-that-get-called-correctly

Tool CallingHow-to guideIntermediate level

How to write AI agent tool descriptions and schemas that get called correctly

Write each tool definition as if the agent were a new colleague who can only read the description and the parameter list. Six steps take you from a vague tool name to a definition you have tested against realistic requests.

Pankaj Nigam

Technical Writer

Published
  • 30 min to complete
  • 0 sec

Tested with
  • LangChain (structured tools)
Your progress
  1. How to write AI agent tool descriptions and schemas that get called correctly5 min(finished)
    0%

Before you start

4
  • An agent framework that lets you register tools with a name, a description and typed parameters (for example LangChain structured tools)
  • One tool you already have, or want to expose, such as a lookup or search function
  • A short list of five to ten real user requests you can use for testing
  • Access to your framework's own tool documentation, because field names differ between frameworks

An agent chooses a tool by reading text. It does not see your code, your team's habits or the ticket that led to the tool. The name, the description and the parameter schema are the whole interface.

That makes a tool definition a piece of documentation, and the same rules apply as for any technical writing: use simple, direct language, avoid jargon where you can, and show working examples instead of only describing behaviour. Prompt engineering practice applies too: clear structure, and zero-shot, one-shot or few-shot examples where they help.

This guide takes one tool and rewrites its definition in six steps. The JSON in step 4 is an illustration of the content you need. The exact field names (name, description and the way parameters are declared) depend on your framework, so check its tool documentation and map the content onto it. Frameworks that support structured tools with several inputs, such as the LangChain structured chat agent type STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION, read the same kind of text.

Keep one rule in mind throughout: every sentence must help the agent decide whether to call the tool, or how to fill in a parameter. Cut everything else.

Step 1 of 6: Name the tool after the action it performs

Rename the tool so the name states a verb and an object, for example search_orders instead of orders_v2 or helper.

The name is the first thing the agent reads, and a plain name lets it rule the tool in or out before it reads anything else. Avoid internal codenames and abbreviations that only your team knows.

If two tools have similar names, rename one now. Near-duplicate names are a common reason an agent picks the wrong tool.

Step 2 of 6: Open the description with what the tool does and when to use it

Write the first sentence as a direct statement of the action, then a second sentence that begins with the situation in which the agent should call it, such as "Use this when the user asks about the status of an existing order."

The agent matches the user's request against these sentences. Stating the trigger situation gives it something concrete to match, which a bare summary does not.

Use simple words. If you must use a domain term, define it in the same sentence.

Step 3 of 6: State what the tool must not be used for and what it returns

Add one sentence that names the nearest wrong use, for example "Do not use it to create or cancel orders." Then add one sentence that describes the return value, including the empty case.

The boundary stops the agent from stretching the tool to cover a neighbouring task. The return description tells the agent what it will have in hand afterwards, so it can plan the next step instead of guessing.

Keep the description short. A long description competes with the user's request and with every other tool for the agent's attention.

Step 4 of 6: Describe every parameter in the schema, not only its type

Give each parameter a name that says what it holds, a type, and a description with the expected format and a sample value. Mark which parameters are required, using whatever mechanism your framework provides.

A type alone, such as a string, leaves the agent to guess whether you want an email address, an order number or free text. The description removes that guess, and the sample value shows the exact shape.

The JSON below is an illustration of the content to supply. Replace the field names with the ones your framework uses, and replace the sample values with your own.

json
{
  "name": "search_orders",
  "description": "Look up a customer's orders by email address. Use this when the user asks about the status, date or contents of an existing order. Do not use it to create or cancel orders. Returns a list of orders, newest first, or an empty list when none match.",
  "parameters": {
    "email": {
      "type": "string",
      "description": "The customer's email address, for example anna@example.com. Required."
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of orders to return, for example 1 for the most recent order. Optional."
    }
  }
}

Step 5 of 6: Add one worked example to the description

Append a single request-to-call example to the description, such as: "Example: for 'where is my last order for anna@example.com', call with email set to anna@example.com and limit set to 1."

Showing beats telling. An example is the few-shot technique from prompt engineering applied at the tool level, and it demonstrates a common use more reliably than another paragraph of rules.

Add a second example only if the tool has a genuinely different usage, such as a call without the optional parameter. Too many examples make the agent copy them too closely.

Step 6 of 6: Test the definition against realistic requests and revise one thing at a time

Run your five to ten real user requests through the agent and record which tool it picked and which arguments it passed. Include requests that should not trigger the tool.

The test shows where the text misleads the agent, and it is the only way to know. Change one element per run, either the name, a sentence or a parameter description, so you know which edit fixed or broke the behaviour.

When the agent passes a wrong value, fix the parameter description first. When it picks the wrong tool, fix the opening sentences and the boundary sentence.


Expected result

A tool definition with an action-based name, a short description that says when to use the tool, when not to, and what it returns, a described and typed parameter list, and one worked example. In your test run, the agent calls the tool for the requests that match, skips it for the ones that do not, and passes arguments in the format shown by your sample values.

Frequently asked questions

How long should a tool description be?

Short enough that every sentence helps the agent decide whether to call the tool or how to fill in a parameter. A trigger situation, a boundary, a return value and one example is usually enough.

Should I use technical terms in descriptions?

Prefer simple, direct language and avoid jargon where you can. If a domain term is unavoidable, define it in the same sentence.

Do examples in a tool description help?

Yes. Working examples that show a common use are a standard documentation practice, and few-shot examples are a standard prompt engineering technique. Use one, or two for clearly different usages.

Do these steps depend on a specific framework?

No. The content (name, description, parameter descriptions, example) is the same everywhere, but the field names differ, so check your framework's documentation, for example for LangChain structured tools.

How do I know a description is good?

Test it with realistic requests, including ones that should not trigger the tool, and check which tool the agent picks and which arguments it passes.

From Grokem: https://www.grokem.com/ai-and-machine-learning/ai-agents/tool-calling/how-to-write-ai-agent-tool-descriptions-and-schemas-that-get-called-correctly

Finished this article?

How did this strike you?

Be the first to react – it is anonymous.

Community

Questions about this?

Ask in Questions and help and get help from other readers.

Ask a questionBrowse Questions and help

Comments

No comments yet. Share what worked for you, or ask a question.

Keep learning

Picked for this article

Related reading, discussions and learning paths on the same subject.

All in Tool Calling

From the community

Learning paths

Learning pathBeginner

Infrastructure basics for data work

The ground a data project stands on: the command line, how a name finds a server, packaging an app in a container, where files and databases live, keeping secrets out of code, backups you have tested and a cloud bill you control.

7 lessonsabout 15 minStart

Choose what we may use. You can change this at any time with “Privacy choices” at the foot of every page. Details are in the Cookie policy and the Privacy policy.

Strictly necessary

Remembers your theme, the lessons you marked as done and this choice. It stays on your device, tracks nothing and cannot be switched off.

Always on
What exactly is collected, and why

Google Analytics

Collects
The pages you view, your device and browser type, your language, how you reached the site and your approximate location (country and city, worked out from your IP address).
Why
To understand which pages and lessons are used, so we can improve them.
Stored
Two cookies, _ga and _ga_<id>, for up to 2 years. Google acts for us; the data is processed by Google, including outside your country.

Grokem’s own counts

Collects
The pages you open and how long you stay, how far you scroll, where you came from, your device type, browser, screen size, language and time zone. Your IP address is turned into a code that changes every day; it is never stored as it is.
Why
To see how long lessons are read and where readers leave. Not shared with anyone.
Stored
A random visitor ID, a visit ID and the time of your last page view in your browser’s storage (gr_vid, gr_sid, gr_last). No name or email is attached.