Writing Good Tool Descriptions and Schemas for LLM Agents

The model chooses tools based only on their names, descriptions and schemas. A vague description is the most common reason an agent picks the wrong tool or invents arguments.

Write descriptions like documentation for a new teammate

{
  "name": "create_refund",
  "description": "Issue a refund for a paid order. Use only after confirming the order id and amount with the user. Partial refunds are allowed. Fails if the order is older than 90 days or already fully refunded. Returns the refund id.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "description": "Order id like ORD-1042" },
      "amount": { "type": "number", "description": "Amount in INR. Omit for a full refund." },
      "reason": { "type": "string", "enum": ["damaged", "late", "wrong_item", "other"] }
    },
    "required": ["order_id", "reason"],
    "additionalProperties": false
  }
}

Checklist

• When to use it and when not to.
• What it returns, so the model knows what it will learn.
• Limits and failure cases ("max 100 rows", "fails if...").
• Formats with examples for ids, dates and units.
• Enums for any argument with a fixed set of values.

Design tools around tasks, not endpoints

Wrapping every REST endpoint one-to-one gives the agent many small tools and many round trips. A single get_customer_overview tool that returns profile, plan and recent orders is often better than three separate tools.

Return useful, compact results

• Return only the fields the model needs. Huge JSON blobs waste context.
• Use readable names and values ("status": "shipped", not "st": 3).
• Make errors actionable: "No order ORD-9 found. Order ids look like ORD-1042." helps the model recover.

Keep the tool set small and distinct

Two tools with overlapping descriptions confuse the model. If you have dozens of tools, group related ones or load them on demand rather than sending all of them on every request.