Tool use is the mechanism by which a large language model requests execution of a function defined by the developer. Instead of generating a text answer, the model generates a structured tool call: a function name and a set of arguments. The runtime executes the function, returns the result, and the model continues reasoning with that result in context. This is how agents interact with APIs, databases, search engines, and any external system.
Getting tool use right is primarily a design problem, not a capability problem. The model can use tools reliably when the tools are well-designed. Most tool use failures come from bad tool design, not model limitations.
The Two Main Syntaxes
Anthropic tool use defines tools as JSON schemas passed to the API alongside the messages:
import anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "search_web",
"description": "Search the web for current information. Use this when the user asks about recent events, current prices, or anything that requires up-to-date information.",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "The search query"},
"num_results": {"type": "integer", "description": "Number of results to return (1-10)", "default": 5}
},
"required": ["query"]
}
}
]
response = client.messages.create(
model="claude-opus-4-5",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "What is the current price of Bitcoin?"}]
)
OpenAI function calling uses a similar structure under the tools parameter with type: "function" wrappers. The core schema format is the same JSON Schema standard.
Both produce a structured tool call object that the developer must execute and return as a tool result message.
Design Pattern 1: Clear, Specific Tool Names
Tool names are part of the model's decision-making signal. A model seeing search has to guess from context what it searches. A model seeing search_web_for_current_info knows exactly when to use it.
Good names:
search_web(notsearch)get_customer_by_email(notlookup)create_calendar_event(notevent)send_slack_message(notnotify)
The name should encode the action AND the target. When you have multiple search tools (web search, database search, file search), the name is the primary disambiguation signal.
Design Pattern 2: Descriptions That Include When NOT to Use the Tool
Most tool descriptions explain what the tool does. The most reliable descriptions also explain when NOT to use it.
Bad description: "Search the web for information."
Good description: "Search the web for current information about events, prices, news, or any topic where the training cutoff makes the answer potentially outdated. Do NOT use this for general knowledge questions, math problems, or anything that does not require current data."
The negative constraint reduces false positives dramatically. Models are good at following explicit exclusions.
Design Pattern 3: Output Format Specification in the Description
Specify the output format the tool returns so the model knows how to interpret the result.
"Returns a JSON array of objects, each with fields: title (string), url (string), snippet (string, up to 200 chars). Returns an empty array if no results are found."
When the model knows the output format in advance, it handles edge cases (empty results, partial results) correctly rather than hallucinating structure.
Design Pattern 4: An Explicit Error Reporting Tool
Include a tool for reporting failures. Without it, when a tool returns an error, the model has no structured way to communicate that failure and will often retry blindly or hallucinate a result.
{
"name": "report_failure",
"description": "Call this when a tool call fails or returns an unexpected error, and you cannot complete the task. Provide a clear description of what failed and why.",
"input_schema": {
"type": "object",
"properties": {
"failed_tool": {"type": "string"},
"error_description": {"type": "string"},
"suggested_alternative": {"type": "string"}
},
"required": ["failed_tool", "error_description"]
}
}
This gives the agent a structured exit path when things go wrong, which is much better than letting it loop.
Design Pattern 5: Tool Result Validation Before Acting
Do not let the model act on a tool result without validating it first. A search tool that returns an empty array should not cause the agent to report "no information found" without attempting a reformulated query. A database query that returns zero rows should trigger a retry with broader parameters, not a final answer.
Validation logic belongs in the runtime layer, not in the model's reasoning. The runtime checks: did the tool return a result? Is the result in the expected format? Is the result non-empty? If any check fails, the runtime can either retry automatically or inject a message prompting the model to try a different approach.
Anti-Pattern 1: Too Many Tools
Models reliably use up to roughly 10 tools. Above that, tool selection accuracy degrades. The model starts picking the wrong tool or combining tools in ways that do not make sense.
If your agent requires more than 10 tools, use tool routing: a lightweight first-pass model that selects the relevant subset of tools for a given task, then passes only those to the main model.
Anti-Pattern 2: Overlapping Tool Purposes
Two tools that do similar things confuse the model about which to use. If you have both search_web and find_information, the model has to guess which one is more appropriate. Eliminate the overlap by merging them or by making the distinction explicit and non-overlapping in both the names and descriptions.
Anti-Pattern 3: Side-Effect Tools Without Clear Labeling
Tools that have irreversible side effects (sending an email, deleting a record, posting to social media) must be labeled clearly. Include "WARNING: this action is irreversible" or "CAUTION: this will send a real email to a real user" in the description.
Models are appropriately cautious when they know an action has real-world consequences. Without that signal, they will call a delete_record tool with the same confidence as a read_record tool.
Parallel Tool Use
Both Anthropic and OpenAI support parallel tool calls: the model can request multiple tool calls in a single response, which the runtime executes concurrently. Use this for independent data fetches (getting weather AND getting calendar events AND getting news simultaneously rather than sequentially). Parallel tool use reduces latency significantly for agents that need multiple sources of information.
Keep Reading
- How to Build an AI Agent — how the tool use loop fits into the full agent architecture
- Running AI Agents in Production — tool call loops and hallucinated parameters in production
- AutoGen: Microsoft's Multi-Agent Framework Explained — how tool use works inside a multi-agent system
Pristren builds AI-powered software for teams. Zlyqor is our all-in-one workspace — chat, projects, time tracking, AI meeting summaries, and invoicing — in one tool. Try it free.
