tool-design

Structure every tool description to answer four questions: what the tool does, when to use it, what inputs it accepts, and what it returns. Include concrete format examples like 'CUST-######' for IDs, specify defaults, and document error conditions with recovery guidance.

Limit tool collections to 10-20 tools for most applications, since description overlap causes model confusion during selection. When more tools are needed, use namespacing prefixes like db_* or web_* to create logical groupings that help agents route correctly.

Consolidate when tools represent sequential steps in one workflow or when a human engineer cannot definitively say which tool applies. Keep tools separate when they have fundamentally different behaviors, serve different contexts, or when consolidation would require more than 8-10 parameters.

MCP tool lookups fail when tool names lack the server prefix and multiple servers expose similar names. Always use fully qualified names in the format ServerName:tool_name, such as BigQuery:bigquery_schema, and audit for namespace collisions when adding providers.

Make every error message actionable by stating what went wrong, the expected format, and how to correct it. Include the invalid value received, a concrete valid example, retry guidance for transient failures, and a retryable flag in structured error responses.

Avoid architectural reduction when the data layer is messy or undocumented, the domain requires specialized knowledge the model lacks, safety constraints must limit agent actions, or workflows genuinely benefit from structured orchestration across multiple steps.