Tool Definition in Agent Architecture: How to Write a Good Tool Schema

Tool definition in agent architecture is the design work of deciding, for the tools (functions) an AI agent can use, the name, description, and parameters you present to the model. Because the agent decides whether to call a tool based solely on this schema, a good tool definition is the most decisive factor in the agent behaving correctly.

An agent's "intelligence" often comes not from the model but from the quality of the tool schema presented to it. Even a strong model, given a schema that vaguely explains what a tool does, leads to wrong tool selection and faulty arguments. This guide covers, with a consultant's rigor, why an agent picks the wrong tool, how to write naming and parameter descriptions, how many tools are too many, how to design error messages, and how to test a tool definition; we also point to the comprehensive guide covering the protocol that connects tools to the model.

Definition

Tool Definition (Tool Schema Writing)

The design work of deciding, for every tool (function) an AI agent can use, the name, description, and parameters you present to the model. Because the agent decides whether to call a tool based solely on this tool schema, the quality of the tool definition directly determines agent tool-selection accuracy.

Also known as: tool definition, tool schema, function schema

An agent carries out a given task not by producing text alone but by calling external tools; the name of this tool-calling mechanism is function calling. The only thing the model sees is the tool schema made of each tool's name, description, and parameter list — it does not see the tool's code, what it does, or its side effects. So agent tool selection depends entirely on how clear the text in this schema is. We cover how the agent decides in what is an AI agent and what is agentic AI.

There are three typical causes of wrong tool selection. First, two tools have similar descriptions: the model hesitates between "get user info" and "get user account." Second, the description says only what the tool does, not when it should be used; the model knows what it does but not in which case to call it. Third, an unclear parameter description makes the model pick the right tool but call it with the wrong argument. You can find the details of function calling in what is function calling and how the model processes text in what is an LLM.

A good tool definition starts with the name. The tool name should convey its function at a glance, contain a verb, and follow a consistent pattern: get_user_orders, send_invoice_email. Abbreviations, in-code jargon, and vague names (do_it, process2) mislead the model and make the choice between similar tools harder.

The description is the tool's most critical field. A good description answers three questions: what this tool does, when it should be used, and when it should not. Instead of "gets orders," saying "gets a customer's past orders; use only when the order number or customer ID is known, do not use for product search" markedly improves agent tool selection. The table below summarizes the difference between a good and a bad tool schema:

Comparison of a good and a bad tool definition (tool schema)

Dimension	Bad definition	Good definition
Name	do_it, handle, process2	get_user_orders (verb + object)
Description	Processes orders	Gets the customer's orders; says when to use it
When to use	Not stated	Written explicitly; also when not to use
Parameter description	id: string	order_id: order number, e.g. ORD-1024
Error message	Error 400	order_id not found; enter a valid number

The point to note is this: these fields are written for the model, not the user. So fixing the tool's role and limits at the system-prompt level also raises quality; we cover the distinction in what is a system prompt.

Even an agent that picks the right tool fails if it fills the parameters wrongly; so defining each field clearly is as important as picking the right tool. Every parameter should have a type, a parameter description, and where possible an example value. The parameter description states what the field expects, its format, and its limits: not "date" but "a date in ISO 8601 format, e.g. 2026-08-17."

Required and optional fields should be clearly separated; where a fixed option set (enum) can be used instead of free text, it must be, because the model makes far fewer mistakes choosing from a closed list. Enumerated values, defaults, and units should also be stated in the parameter description; the model should not guess whether a "quantity" field expects units or kilograms, but read it from the schema. A well-written field lets the model both produce the right argument and ask the user when information is missing.

Another frequently skipped detail is dependencies between fields. If a parameter is meaningful only when another holds a specific value, that relationship must be written explicitly in the parameter description; otherwise the model may fill the two fields inconsistently. In short, the schema should be thought of as a contract that answers in advance every ambiguity that might cross the model's mind: the less it leaves to interpretation, the more consistent agent tool selection and argument generation become.

Counterintuitively, the more tools you give an agent, the worse it often works — usually the opposite of "more is better." Every extra tool raises the number of options the model must scan on each decision, and similar tools amplify selection errors. Also, since all tool schemas are loaded into the model's context (context window), many tools both raise cost and dilute attention. We cover this role at the edge of context and cost in what is a token.

There is no exact threshold, but experience shows: instead of giving an agent dozens of tools at once, offering small task-scoped tool sets is more reliable. As the tool count grows, a multi-agent architecture should be considered: specialist agents each with a narrow tool set work more accurately than a single giant agent. We detail this pattern in what is a multi-agent system.

The error message a tool returns is an instruction written for the model, not the user. When the agent calls a tool with the wrong argument, the returned error should be explanatory enough for the model to correct itself. "Error 400" traps the model; a message like "order_id 'ABC' is invalid; the order number must start with ORD-" tells the model what to do next time. Well-designed error messages enable the agent's self-correction and prevent needless failures.

The error message should also suggest an action: which parameter is wrong, the expected format, and a valid example if available. For security, error messages must not leak internal system details and must be protected against malicious inputs; we cover the role of protective layers in what is a guardrail.

A tool definition is finished not when it is written but after it is tested. The most practical way to test a tool schema is to prepare a small set of scenarios made of real user questions and observe which tool the agent calls, with which arguments. The goal is to answer not just "does it work" but "does it pick the right tool in ambiguous cases."

How to

Steps to test a tool schema

The basic steps to measure a tool schema's agent tool-selection accuracy and robustness with real scenarios.

1. 1

   Prepare a scenario set

   Collect a list of realistic user requests where the tool should and should not be used.

2. 2

   Measure tool selection

   Observe whether the agent picks the right tool in each scenario or drifts to a similar tool.

3. 3

   Check the arguments

   Verify whether the parameters of the selected tool are filled correctly and completely.

4. 4

   Try the error paths

   Call the tool with missing or wrong inputs and test whether the model recovers from the error message.

5. 5

   Improve the schema

   Clarify the names and descriptions of confused tools, sharpen the parameter descriptions, and measure again.

This loop — prepare a scenario, measure selection, check the argument, try the error, improve — should be repeated regularly for a tool definition; because as new tools are added, older tools' descriptions may clash again.

How do you write a tool schema?

A tool schema has three parts: name, description, and parameters. The name should be a consistent, verb-containing label that conveys the function at a glance. The description should say what the tool does, when to use it, and when not to. For each parameter, write a clear parameter description with its type, format, and an example value; use a closed option set instead of free text where possible. Finally, the schema must be tested with real scenarios.

Why does the agent pick the wrong tool?

Because the agent sees not the tool's code but only the tool schema, a wrong pick almost always stems from ambiguity in the schema. There are three typical causes: two tools have similar descriptions; the description does not say when to use the tool; or an unclear parameter description makes the model pick the right tool but call it with the wrong argument. The fix is to separate similar tools clearly, add a usage condition to every description, and sharpen parameters with examples.

How many tools are too many?

There is no exact number, but the principle is clear: the more tools you give an agent, the harder selection becomes. Every tool schema is loaded into the model's context, raises cost, and dilutes attention; similar tools amplify selection errors. Instead of piling dozens of tools onto a single agent, offering small task-scoped tool sets is more reliable; as the tool count grows, a multi-agent architecture should be considered.

What is the relationship between function calling and tool definition?

Function calling is the mechanism by which a language model triggers an external tool by producing a structured call instead of text. Tool definition is the work of writing the schema — the name, description, and parameters — the model reads to produce that call. So function calling is the mechanism and tool definition is the interface design that feeds it; the model can only make the right function-calling decision thanks to a well-written tool definition.

Why is the parameter description so important?

Because even an agent that picks the right tool fails if it fills a parameter wrongly. The parameter description states the field's type, format, unit, and limits: not "date" but "a date in ISO 8601 format, e.g. 2026-08-17." A good parameter description lets the model both produce the right argument and ask the user when information is missing. When given a closed option set instead of free text, the model makes far fewer mistakes.

In short, tool definition in agent architecture is presenting a tool to the model with a clear name, a description that says when to use it, a parameter description that states its format, and error messages that enable self-correction. Agent tool-selection accuracy comes not from the most expensive model but from this schema discipline; separating similar tools, pruning unnecessary ones, and testing every tool definition with scenarios is the foundation of a reliable agent.

To not miss this kind of practical agent-engineering content and new guides, you can subscribe to the newsletter, and to deepen all topics end to end you can explore the learning center. A well-built tool schema is the most practical way to get a far more reliable agent from the very same model.