Tool Schema Design: The Model Reads Your API

~30 min · tool-schema, json-schema, descriptions

Level 0Observer

0 XP0/40 lessons0/12 achievements

0/100 XP to next level100 XP to go0% complete

A tool schema is a prompt with teeth

Tool descriptions are not decorative comments. They are the interface the model reads when deciding whether to act. A bad description makes tool choice random; a precise description turns the model's latent knowledge into a bounded action.

Name the intent, not the implementation

Prefer search_customer_orders over db_query. The model should choose tools based on task intent, not internal storage details.

Each parameter should explain what value belongs there, the expected format, and common traps. If a field accepts an id, say which id. If a date expects ISO format, say so.

Keep tools narrow

One broad do_anything tool makes permissioning impossible and gives the model too much ambiguity. Several narrow tools are easier to validate, log, test, and approve.

Code

Good tool schema·json

{
  "name": "search_customer_orders",
  "description": "Search customer orders by public customer id or email. Use when a user asks about past purchases, delivery status, refunds, or order history. Does not modify orders. Returns at most 10 summarized orders.",
  "input_schema": {
    "type": "object",
    "properties": {
      "customer": {
        "type": "string",
        "description": "Public customer id or verified email address."
      },
      "status": {
        "type": "string",
        "enum": ["any", "paid", "shipped", "refunded"],
        "description": "Optional status filter. Use 'any' unless the user asks for a specific status."
      }
    },
    "required": ["customer"]
  }
}

External links

Exercise

Take one vague tool name like search or update and rewrite it into three narrow tools with clear descriptions.

Hint

A useful split is read, propose, apply. The apply tool should need stronger permission.

Progress

Progress is local-only — sign in to sync across devices.

← 🔄 Single AgentQuiz · 4 questions Next →Tool Results: Small, Structured, Actionable

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.