Advanced10 min

Tool Design Patterns

How tool names, descriptions, and error surfaces affect model selection accuracy. Designing composable, token-efficient tools that help the model choose correctly and chain reliably.

Quick Reference

→Tool naming: short, verb-first names (search_docs, create_ticket) outperform vague names (handle_request). The model selects tools primarily by name.
→Description engineering: describe what the tool does, when to use it, and what it returns. Include examples of when NOT to use it to reduce misselection.
→Error surfaces: return structured error messages the model can act on, not stack traces. 'No results for query X — try broadening the search' beats 'IndexError: list index out of range'.
→Minimal tool sets: fewer tools = better selection accuracy. 5 well-designed tools outperform 20 overlapping ones. Merge related tools when possible.
→Token efficiency: every tool description consumes input tokens on every call. A 200-token description across 10 tools costs 2K tokens per turn — optimize ruthlessly.

Tool Naming: The First Selection Signal

The model's tool selection process starts with the name. Before reading the description, the model forms an initial hypothesis about what each tool does based on its name alone. Clear, verb-first names like search_documents, create_ticket, and get_weather dramatically outperform vague names like process, handle, or utility. The name should tell the model exactly what action the tool performs.

Bad Name	Good Name	Why It Matters
handle_data	search_knowledge_base	Specific action + target makes selection unambiguous
process_request	create_support_ticket	Model knows exactly when to use this tool
do_stuff	calculate_shipping_cost	Descriptive names reduce hallucinated tool calls
api_call	get_current_weather	Generic names force the model to rely entirely on description
helper	format_date_range	Utility-style names cause confusion when multiple tools exist

Verb-noun naming convention

Use the pattern verb_noun or verb_adjective_noun: search_documents, get_user_profile, create_draft_email, delete_expired_sessions. This convention makes tool purpose immediately clear and helps the model distinguish between tools that operate on the same entity (get_user vs update_user vs delete_user).

Description Engineering

Descriptions are prompts for tool selection

The tool description is a prompt that tells the model when and how to use the tool. It should answer three questions: what does this tool do, when should the model use it, and what does it return. The most common mistake is writing descriptions that are too short — 'Searches documents' tells the model almost nothing about when to prefer this tool over others.

Error Surfaces: Helping the Model Recover

When a tool fails, the error message goes back to the model as a tool result. If you return a Python stack trace, the model has no idea how to recover. If you return a structured message that explains what went wrong and suggests a fix, the model can retry with corrected arguments. Designing good error surfaces is as important as designing the happy path.

Sign in to read this article

This is a premium article. Sign in with your Google account to continue.