# Tool & Function Calling Cheat Sheet
_Writing tool schemas a model actually uses correctly_
A tool definition is a prompt. Its name, its description and its parameter names are the only things the model has to decide whether to call it.
> Difficulty: intermediate  
> Version: 1.0  
> Updated: 2025-05-20  
> Categories: AI Agents  
> Tags: Anthropic, Function Calling, Json Mode, Openai

Source: https://invitationbuddy.com/cheat-sheet/tool-calling-cheat-sheet

---

## Schema rules
- [ ] Name the tool for the action, in a verb form — search_orders beats orders_api
- [ ] Describe WHEN to use it, not only what it does — The description is a routing instruction
- [ ] Say explicitly when NOT to use it — The single most effective line against wrong-tool calls
- [ ] Mark every genuinely required parameter required — Optional-by-default means it will be omitted
- [ ] Use enums wherever the set is closed — A free-string status will be invented eventually
- [ ] Describe each parameter, including its units and format — "date (YYYY-MM-DD)" prevents a whole class of retries
- [ ] Keep the toolset under about ten — Accuracy degrades well before the context does

## The round trip
| Step | Who | Contains |
| --- | --- | --- |
| 1. Request | You  messages + tool definitions |
| 2. Tool call | Model  A tool_use block with an id and arguments |
| 3. Execution | Your code  Validate the arguments before running anything |
| 4. Result | You  A tool_result referencing the same id |
| 5. Answer | Model  Prose, or another tool call |

## Never trust the arguments
Tool arguments are model output, which makes them untrusted input in the security sense. Validate them against your schema server-side, apply the same authorisation you would to a user request, and never interpolate them into a query, a shell command or a file path. A prompt injected into retrieved content can reach your tools this way.

## Code examples
### A tool schema that routes correctly
The description is a routing instruction, not documentation. Saying when NOT to use it is the single most effective line.
```json
{
  "name": "search_orders",
  "description": "Find a customer's orders by email or order number. Use this whenever the user asks about an order's status, contents or delivery date. Do NOT use it for refunds or cancellations — those go to manage_order.",
  "input_schema": {
    "type": "object",
    "properties": {
      "email":   { "type": "string", "description": "Customer email. Provide this OR order_number." },
      "order_number": { "type": "string", "description": "Order reference, format ORD-000000." },
      "since":   { "type": "string", "description": "Only orders on or after this date (YYYY-MM-DD)." },
      "status":  { "type": "string", "enum": ["pending", "shipped", "delivered", "cancelled"] }
    },
    "required": ["status"]
  }
}
```

## FAQs
**How many tools can a model handle?**
Accuracy starts degrading well before the context does — around ten is a practical ceiling. Beyond that, route to a smaller toolset first rather than expanding the list.

**Do I need to validate the arguments?**
Always. Tool arguments are model output, which makes them untrusted input. Content retrieved from elsewhere can carry an injected instruction that reaches your tools this way.

---
_Generated from https://invitationbuddy.com/cheat-sheet/tool-calling-cheat-sheet_