Tool Calling — How the Model Decides

Tools are part of the prompt

Exposing a tool is a kind of instruction: it tells the model 'here is something you can do.' The model decides whether to call the tool, with what arguments, and how to integrate the result into its response. Most tool-calling bugs are prompt bugs — the tool's name, description, and input schema are doing the work.

What the model reads

Tool name — should be a verb or verb-noun (search_documents, create_ticket).
Description — short, says what the tool does and when to use it. The most under-written field; treat it like a small prompt.
Input schema — JSON Schema. Field descriptions are visible to the model.
Examples — some providers support example tool calls. Use them for non-obvious tools.

Common mistakes

One-line descriptions that don't say when to use the tool.
Overlapping tools that compete (two ways to do the same thing).
Generic field names without descriptions (id, data).
No guidance on what to do when the tool returns an error.

Code

Tool with rich description·json

{
  "name": "search_orders",
  "description": "Find a customer's orders by customer_id, date range, or status. Use this when the user mentions an order, a delivery, a refund, or a tracking number. Do not use it for general account questions.",
  "input_schema": {
    "type": "object",
    "properties": {
      "customer_id": {"type": "string", "description": "Internal customer ID, format CUST-NNNNNN."},
      "status": {"type": "string", "enum": ["pending", "shipped", "delivered", "returned"]},
      "date_from": {"type": "string", "format": "date"}
    },
    "required": ["customer_id"]
  }
}

Tool Calling — How the Model Decides

Tools are part of the prompt

What the model reads

Common mistakes

Code

External links

Exercise

Progress

Comments 0