Designing Tool Schemas for LLM Function Calling That Models Use Correctly

Quick answer: models choose and fill in tools based on the names, descriptions, and parameter schemas you provide, so treat those as the interface design. Use specific names, write descriptions that say when to use and not use each tool, keep parameters few and well-typed, use enums for fixed choices, return concise results with actionable errors, and always validate arguments on the server.

Why Does Schema Design Matter So Much?

A model has no access to your code. It sees only the tool definitions you send: a name, a description, and a schema for the arguments. From that text alone, it decides whether to call a tool and what to pass. If the definition is vague, overlapping, or misleading, the model will guess, and wrong guesses become wrong actions.

Many tool-use failures that look like model mistakes are really interface problems. Two tools with similar descriptions confuse selection, an ambiguous parameter name gets filled with the wrong kind of value, and a missing description of the output leaves the model unable to use the result. Improving the definition is usually cheaper than changing the model or the prompt.

Think of the schema as documentation written for a reader who is capable but literal, has no context beyond what you provide, and cannot ask follow-up questions. Clarity beats cleverness.

What Makes a Good Tool Definition?

Strong definitions share a few traits. They make the purpose obvious, limit the choices, and reduce room for error:

• Use specific names that describe the action and object, such as search_orders, instead of generic names such as query or lookup.
• Write a description that explains what the tool does, when to use it, and when not to, especially if a similar tool exists.
• Keep the number of parameters small, mark required ones clearly, and give each a description with an example value.
• Use enums or constrained types for fixed sets such as status or sort order, instead of free text.
• Split large multipurpose tools into focused ones, and avoid exposing many near-duplicate tools at once.

{
  "name": "search_orders",
  "description": "Find a customer's orders by status or date range. Use for questions about existing orders. Do not use to create or change orders.",
  "parameters": {
    "type": "object",
    "properties": {
      "status": {"type": "string", "enum": ["pending", "shipped", "delivered", "cancelled"]},
      "since": {"type": "string", "description": "ISO date, for example 2025-01-31"}
    },
    "required": ["status"]
  }
}

The number of tools affects reliability. A model choosing among a handful of distinct tools performs better than one facing dozens of overlapping ones. If you have many tools, group them, load only those relevant to the current task, or use a routing step.

How Should Tools Respond and Fail?

The result is part of the interface too. Return concise, structured data containing only what the model needs, since large outputs consume context and distract. Include identifiers the model may need for follow-up calls, and state clearly when a result is empty, so the model does not invent data.

Make errors useful. A message like invalid request gives the model nothing to act on, while a message that names the bad parameter and the allowed values lets it correct itself on the next call. Distinguish errors the model can fix, such as a malformed date, from ones it cannot, such as a permission failure, and say so.

Never trust arguments. Validate every call against the schema and your business rules on the server, check authorization using the real user context, and make state-changing tools idempotent. The schema guides the model, but it does not enforce anything by itself. Finally, test tool selection and argument accuracy with an evaluation set, and refine definitions based on the failures you see.

Frequently Asked Questions

How many tools can I give a model?

There is no fixed limit, but accuracy tends to drop as tools multiply and overlap. Keep sets small and distinct, and load tools by task.

Should I use enums for parameters?

Yes, whenever the values form a closed set. They reduce invalid values and make the choices explicit to the model.

What should a tool return when it finds nothing?

An explicit empty result with a clear message. This prevents the model from filling the gap with invented information.

Is server-side validation still needed?

Yes. Schemas guide generation but do not guarantee valid or authorized arguments, so validate and authorize every call.

Summary

Design tool definitions like an API for a literal reader: specific names, clear descriptions, few typed parameters, and useful results and errors. Validate on the server and evaluate tool use with real tests. Check your provider documentation for supported schema features.