tool-design

Structure the description to answer four questions: what the tool does, when to use it, what inputs it accepts with types and examples, and what it returns including error conditions. Avoid vague language like "helps with" and include concrete format examples such as CUST-000001.

Merge tools that represent sequential steps of one workflow into a single comprehensive tool, such as replacing list_users, list_events, and create_event with one schedule_event tool. Keep tools separate when they have fundamentally different behaviors or must be callable independently.

Wrong selection usually comes from overlapping tool descriptions that create ambiguity during routing. Reduce the catalog until each tool has one unambiguous purpose, use namespacing like db_* or web_* prefixes, and clarify distinctions between similar tools in their descriptions.

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 expose similarly named tools.

A recoverable error message states what went wrong, the expected format with a concrete example, and what the agent should change before retrying. Generic messages like "failed" or "invalid input" give the agent no signal to self-correct.

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.