Designing Tool Schemas That Models Use Well

A tool schema is the interface between your code and the model's decision-making. It tells the model what a function does, when to use it, and what arguments it expects. A poorly written schema causes the model to call the wrong tool, pass incorrect arguments, or skip a tool it should have used. Investing time in schema design pays off far more than switching to a larger model.

The anatomy of a well-written tool schema

Every tool schema has three parts that each require deliberate care: the function name, which the model uses as a mnemonic clue; the description, which the model reads to decide whether to invoke the tool; and the parameter schema, which shapes the arguments the model will emit. Vagueness in any of these three places is a source of selection errors or malformed calls.

# Poor schema — vague description, unclear parameter intent
poor_tool = {
    "name": "get_info",
    "description": "Gets information.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
    },
}

# Strong schema — precise description, explicit parameter guidance
strong_tool = {
    "name": "search_knowledge_base",
    "description": "Search the internal product knowledge base for documentation, FAQs, and release notes. Use this when the user asks about product features, pricing, or known issues. Do NOT use for general web searches.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "A specific search query. Be precise — include product names, version numbers, or error codes when relevant.",
            },
            "category": {
                "type": "string",
                "enum": ["feature", "pricing", "troubleshooting", "release-notes"],
                "description": "Optional: narrow the search to a specific documentation category.",
            },
        },
        "required": ["query"],
    },
}

Parameter design principles

• Use enums for parameters with a fixed set of valid values — this eliminates hallucinated values entirely
• Mark only genuinely required parameters as required; optional parameters with defaults reduce call failures
• Provide descriptions for every parameter, not just the function — models read parameter descriptions when choosing argument values
• Keep parameter names self-explanatory; avoid abbreviations or internal naming conventions the model has never seen
• Decompose compound parameters: a single 'options' object is harder for the model to populate correctly than two explicit parameters

Handling return values in the schema

The schema does not formally define what the tool returns, but the function description should indicate the return format so the model knows what to expect. If the tool returns JSON, say so. If it returns a list of results, describe the fields. The model's reasoning about what to do next depends on its mental model of what the tool will produce — make that mental model accurate.

Testing schemas in isolation

Write unit tests for tool selection by giving the model a fixed set of tools and a representative set of user messages, then checking that it chose the expected tool and emitted well-formed arguments. This lets you iterate on schema descriptions without running the full agent loop and exposes selection failures on edge cases before they appear in production.