tool-design

Tool descriptions should answer four questions: what the tool does, when to use it, what inputs it accepts, and what it returns. Include concrete examples with exact formats like "CUST-000001" and avoid vague language such as "helps with" or "search the database".

A reasonable guideline is 10-20 tools for most applications, since overlapping descriptions cause model confusion. If more tools are needed, use namespacing to group related tools under common prefixes so agents can route to the right namespace.

Consolidate tools that represent sequential steps of a single workflow, such as combining list_users, list_events, and create_event into one schedule_event tool. Keep tools separate when they have fundamentally different behaviors or are used in different contexts.

Always use fully qualified names in the format ServerName:tool_name, such as BigQuery:bigquery_schema or GitHub:create_issue. Without the server prefix, agents may fail to locate tools when multiple MCP servers are available.

Generic error messages give agents no recovery path. Design errors that state what went wrong, the expected format with an example, resolution guidance, and whether the call is retryable, so agents can correct inputs and retry.

Present representative agent requests and evaluate the resulting tool calls for correctness, then identify common failure modes. You can also use an agent to analyze observed failures and propose improved descriptions, a pattern shown to reduce task completion time.