Tool Calling for AI Agents: Design Schemas That Work
When an AI agent behaves unreliably—calling the wrong function, hallucinating parameters, or ignoring a perfectly good tool—the root cause is rarely the model. More often, it's the tool schema. The function definitions you expose are the primary interface between your application and the model's reasoning. Get them right, and even mid-tier models pick and call tools with impressive accuracy. Get them wrong, and no amount of prompting will save you.
This guide covers how to design function schemas and descriptions that make AI agent tool calling dependable, whether you're using OpenAI's function calling, Anthropic's tool use, or an open framework like LangGraph or the Model Context Protocol.
How the model actually reads your tools
Before writing schemas, understand what the model sees. Your tool definitions—names, descriptions, and JSON Schema parameters—are injected into the model's context as structured instructions. The model doesn't run your code; it reads these definitions and decides, token by token, which tool to invoke and what arguments to generate.
This has two practical consequences. First, every word in a description is a prompt. Vague or overlapping descriptions confuse tool selection. Second, tokens cost money and attention. Bloated schemas with 30 optional parameters dilute the signal and increase latency. Treat your tool definitions like API documentation written for a very literal, very fast reader.
Name tools by intent, not implementation
Tool names are the first signal the model uses. Name them after what the user wants to accomplish, not your internal service layout.
Prefer get_customer_orders over db_query_v2. Prefer send_slack_message over notify. Use consistent verb-noun patterns (get_, create_, update_, search_) so the model can generalize across your toolset. Avoid names that only make sense with insider context—run_pipeline_x tells the model nothing.
When two tools overlap, the model will guess. If you have both search_products and get_product_by_id, make the boundary explicit in each description so it knows which to reach for.
Write descriptions that disambiguate
The description field does the heavy lifting for tool selection. A good description answers three questions: what the tool does, when to use it, and when not to use it.
Compare a weak description like "Gets weather data" with a strong one: "Returns the current weather and 3-day forecast for a specific city. Use when the user asks about temperature, rain, or conditions for a named location. Do not use for historical weather—use get_weather_history instead."
That explicit boundary ("Do not use for...") is one of the highest-leverage additions you can make. Models frequently pick the closest-sounding tool; negative guidance redirects them.
Keep descriptions concrete
Include units, formats, and defaults directly in the text. "Distance in kilometers," "Date in ISO 8601 (YYYY-MM-DD)," "Returns up to 20 results by default" all reduce ambiguity. If a tool has side effects—sending an email, charging a card, deleting data—say so loudly. Agents should treat destructive tools with more caution, and the description is where that caution begins.
Design parameters for minimum ambiguity
Your parameter schema is standard JSON Schema, and the model respects it closely. A few rules pay off consistently:
Use enums whenever the value space is finite. Instead of a free-text "status" string, define "enum": ["open", "pending", "closed"]. This eliminates an entire category of hallucinated values and makes validation trivial.
Mark only what's truly required. Over-marking required fields forces the model to invent values when the user hasn't supplied them. If a field has a sensible default, make it optional and document the default in its description.
Describe every parameter individually. Each property should have its own description. "user_id: The numeric ID of the customer, obtained from search_customers" tells the model where to source the value—critical for multi-step tool chains.
Prefer flat structures. Deeply nested objects raise the error rate. If you can flatten three levels into named parameters, do it. Reserve nesting for genuinely structured data like line items.
Handle multi-tool chains explicitly
Real agents rarely call one tool. They search, then fetch, then act. To make chaining reliable, encode the dependencies in your descriptions. If create_invoice needs a customer_id that only find_customer can produce, say so in both tools. This helps the model sequence calls correctly instead of fabricating an ID.
Consider returning structured, machine-readable outputs from each tool—include the IDs and fields a subsequent call will need. A tool that returns "Found 3 customers" as prose forces the model to re-parse text; one that returns a clean JSON array of objects with IDs feeds directly into the next call.
Control the toolset size
Accuracy degrades as the number of exposed tools grows. Beyond roughly 15–20 tools, selection errors climb noticeably. If your agent needs dozens of capabilities, use tool filtering: dynamically expose only the tools relevant to the current task or conversation phase, or group tools behind a router that first classifies intent.
Namespacing helps too. Prefixing tools by domain (billing_create_invoice, support_open_ticket) gives the model a coarse grouping signal and keeps related tools visually clustered in context.
Validate, don't trust
Even with perfect schemas, models occasionally emit malformed arguments. Always validate tool arguments against your JSON Schema before execution. When validation fails, return a clear error message back to the model rather than crashing—"Error: 'quantity' must be a positive integer, received -1"—so it can self-correct on the next turn. This feedback loop is one of the most effective reliability patterns in production agents.
Set sensible timeouts and make destructive operations require confirmation, either through a human-in-the-loop step or a two-phase pattern where the agent proposes an action and a separate check approves it.
Test tool selection like you test code
Build a small evaluation set of realistic user requests paired with the tool you expect the agent to call. Run it against every schema change. This catches regressions when you add a new tool that accidentally shadows an existing one—a surprisingly common failure as toolsets grow.
Track two metrics: selection accuracy (did it pick the right tool?) and argument accuracy (were the parameters correct and complete?). Most teams discover their argument errors trace back to underspecified parameter descriptions, which points directly to the fix.
A quick checklist
Before shipping any tool, confirm: the name reflects intent, the description states when and when not to use it, every parameter is described with units and formats, finite values use enums, required fields are genuinely required, outputs are structured for chaining, and you validate arguments before execution.
Well-designed schemas are the difference between an agent that demos well and one that works reliably at scale. The model is doing its best with the interface you hand it—so make that interface unambiguous, concrete, and disciplined.
Ready to build real AI skills? Join the September 2026 cohort at Class For Jobs. Explore Advanced AI — a hands-on, live program to build and ship production AI applications, live and instructor-led with career support, resume help, and job-placement assistance.
Related reading
