Designing Effective Tool Descriptions

~22 min · tool-descriptions, prompting

Level 0Tokenizer

0 XP0/54 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

The model reads your tool descriptions to decide when and how to use each tool. Well-crafted descriptions dramatically improve tool selection accuracy.

Best Practices

Be specific: "Get current weather conditions including temperature, humidity, and forecast for a given city" is better than "Get weather".
Include examples: Add examples in the description — "e.g., 'London, UK' or 'New York, US'".
State constraints: "Only works for US cities" or "Returns data for the last 30 days only".
Describe parameters: Each parameter should have a clear description field.
Use enums: Constrain values where possible — "enum": ["celsius", "fahrenheit"].

Code

Bad description vs good description·python

# Good tool description
{
    "type": "function",
    "name": "search_products",
    "description": "Search the product catalog by name, category, or price range. "
                   "Returns up to 10 matching products with name, price, and description. "
                   "Use this when the user asks about available products or wants to compare options.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Search query — product name or keywords (e.g., 'wireless headphones')"
            },
            "category": {
                "type": ["string", "null"],
                "enum": ["electronics", "clothing", "books", "home", null],
                "description": "Filter by product category"
            },
            "max_price": {
                "type": ["number", "null"],
                "description": "Maximum price in USD (e.g., 50.00)"
            }
        },
        "required": ["query", "category", "max_price"],
        "additionalProperties": False,
    },
    "strict": True,
}

External links

Tool description tips

Exercise

Take one of your tools. Run 5 ambiguous prompts and note which calls succeeded vs misrouted. Rewrite the description with explicit boundaries and run the same 5 prompts. Measure the delta.