LLM Tool Definition Template

Template, every field annotated with what makes it work:

{
  "name": "[verb_noun, e.g. search_orders: the action it performs, not the system it wraps]",
  "description": "[3-5 sentences. This is the single highest-leverage string in your agent. Cover, in order: (1) what the tool does and what it returns, (2) WHEN to use it, (3) when NOT to use it and what to use instead, (4) any critical constraint. The model chooses tools by these descriptions alone.]",
  "input_schema": {
    "type": "object",
    "properties": {
      "[param]": {
        "type": "string",
        "description": "[What it is + exact format + a concrete example. 'Customer email address, e.g. jane@acme.com', never just 'the email'.]"
      },
      "[constrained_param]": {
        "type": "string",
        "enum": ["option_a", "option_b"],
        "description": "[Use enums wherever values are closed: models guess invalid strings for open fields.]"
      },
      "[optional_param]": {
        "type": "integer",
        "description": "[Say what happens when omitted: 'Max results to return. Defaults to 10; use 50 only when the user asks for an exhaustive list.']"
      }
    },
    "required": ["[param]"]
  }
}

Worked example:

{
  "name": "search_orders",
  "description": "Searches the store's order database and returns matching orders with id, status, items, and total. Use when the user asks about an order's status, history, or contents and you don't already have the order ID in context. Do not use for refunds or modifications. Use process_refund for those. Returns at most 50 results; results are read-only.",
  "input_schema": {
    "type": "object",
    "properties": {
      "customer_email": {
        "type": "string",
        "description": "Email on the order, e.g. jane@acme.com. Required unless order_id is given."
      },
      "status": {
        "type": "string",
        "enum": ["pending", "shipped", "delivered", "refunded"],
        "description": "Filter to one status. Omit to search all statuses."
      },
      "limit": {
        "type": "integer",
        "description": "Max results. Defaults to 10."
      }
    },
    "required": ["customer_email"]
  }
}

Design rules:
- Return errors as data the model can act on ("No orders found for that email: verify the address"), not thrown exceptions; agents recover from informative failures and loop on opaque ones.
- One tool = one decision. If the description needs "and/or", split the tool.
- Name overlapping tools so the boundary is in the names (search_orders vs get_order_details), and state the boundary in both descriptions.
- Keep response payloads lean: return the fields the agent needs, not the whole database row; bloated tool results crowd out the context the agent is reasoning over.