tool-design

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

Apply the consolidation principle: merge tools with overlapping activation scenarios until each has one unambiguous purpose, and namespace the rest by domain (e.g., db_*, web_*). If a human engineer cannot say which tool applies, the agent cannot either.

Consolidate tools that are sequential steps of one workflow into a single comprehensive tool. Keep tools separate when they have fundamentally different behaviors, serve different contexts, or must be callable independently; over-consolidation past 8-10 parameters hurts parameterization accuracy.

Always use fully qualified names in the format ServerName:tool_name, such as BigQuery:bigquery_schema. Without the server prefix, agents may fail to locate tools when multiple MCP servers expose similarly named tools.

A recoverable error states what went wrong, the expected format with a concrete example, and what to change before retrying, plus whether the error is retryable. Messages like "failed" or "invalid input" give the agent no recovery signal.

Reduction works when the data layer is well-documented, the model has sufficient reasoning capability, and specialized tools constrain rather than enable the model. Avoid it when data is messy, domain expertise is required, or safety constraints demand restricted actions.