Tool Definitions and JSON Schema Discipline

Three required fields per tool

A tool definition has three required fields: name (snake_case identifier), description (what the tool does, when to use it), and input_schema (JSON Schema for arguments). The model picks tools by reading description; it shapes arguments by reading input_schema. Both matter; one is not enough.

Description is a prompt, not a label

Treat the description as a tiny prompt fragment that helps the model decide when to call the tool. 'Get the weather' is too thin; 'Get current weather and 24h forecast for a city. Use this when the user asks about temperature, rain, or what to wear today.' is what reliable selection looks like.

Schemas with required, types, and enums

Use full JSON Schema features: required arrays, enum for fixed sets, type with constraints. The richer the schema, the more reliably the model produces valid input. The trade-off: every byte of schema costs input tokens, so do not over-spec.

Principle: Tool name + description selects; schema constrains. Both deserve craft.

Code

Detailed tool definition·python

TOOLS = [
    {
        "name": "search_orders",
        "description": (
            "Search the orders database by customer email and optional status. "
            "Use when the user asks about their order history, refund status, "
            "or shipping. Do NOT use to create or modify orders."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "customer_email": {
                    "type": "string",
                    "format": "email",
                    "description": "Customer email exactly as registered.",
                },
                "status": {
                    "type": "string",
                    "enum": ["pending", "shipped", "delivered", "refunded"],
                    "description": "Optional status filter.",
                },
                "limit": {"type": "integer", "minimum": 1, "maximum": 50},
            },
            "required": ["customer_email"],
        },
    }
]

Validating model arguments before invoking·python

from jsonschema import Draft202012Validator

validator = Draft202012Validator(TOOLS[0]["input_schema"])

def invoke_tool(name: str, arguments: dict):
    spec = next(t for t in TOOLS if t["name"] == name)
    errors = list(Draft202012Validator(spec["input_schema"]).iter_errors(arguments))
    if errors:
        return {"error": "invalid arguments", "details": [e.message for e in errors]}
    return HANDLERS[name](**arguments)

Exercise

Take one tool definition you have shipped and audit the description for selection guidance + the schema for missing constraints. Add at least one enum, one numeric bound, and one rich description sentence.

Hint

If the description does not mention when NOT to use the tool, add it. Negative guidance reduces wrong calls.

Tool Definitions and JSON Schema Discipline

Three required fields per tool

Description is a prompt, not a label

Schemas with required, types, and enums

Code

External links

Exercise

Progress

Comments 0