Tool Schema Design

Tool-calling reliability lives in three places: the description the model reads to pick the tool, the JSON Schema it fills to call it, and the error response it uses to recover. Get those three right and a well-tuned model picks the right function, supplies valid arguments, and recovers gracefully.

The description writes the router

Descriptions — of tools and of parameters — are the primary lever for selection accuracy. The model disambiguates between similar tools by reading descriptions, not names.

• Tool description: cover what it does, when to use it, and when NOT to use it (name the sibling tool the model should pick instead).
• Parameter description: include expected format, valid range, and a concrete example. "The ISO 8601 start date, e.g. '2026-03-15'" beats "The start date".
• Write in a neutral, third-person voice. No marketing.

Example: