Designing Good MCP Tools (This Is Where Most Systems Fail)

ehicle", description: "Sends a navigation command to a vehicle to route it to a new destination. Use this when the user requests to send a vehicle somewhere or change its route.", inputSchema: { type: "object", properties: { vehicle_id: { type: "string", description: "The unique VIN or fleet ID of the vehicle to dispatch." }, destination: { type: "string", description: "The target address or GPS coordinates for the new route." }, priority: { type: "string", enum: ["standard", "urgent"], description: "Dispatch priority level. Defaults to 'standard' if omitted." } }, required: ["vehicle_id", "destination"] } };

// Tool 3: State Update Action const update_driver_assignment = { name: "update_driver_assignment", description: "Assigns or reassigns a driver to a specific vehicle. Use this when the user mentions changing drivers or linking a driver to a vehicle.", inputSchema: { type: "object", properties: { driver_id: { type: "string", description: "The ID of the driver." }, vehicle_id: { type: "string", description: "The ID of the vehicle to assign." }, effective_time: { type: "string", format: "date-time", description: "ISO 8601 timestamp for when the assignment takes effect. Use 'now' for immediate effect." } }, required: ["driver_id", "vehicle_id"] } };

**Architecture Rationale:**
*   **Separation of Concerns:** `retrieve_vehicle_telemetry` is read-only, while `dispatch_vehicle` has side effects. This distinction helps the model understand risk and intent.
*   **Explicit Constraints:** The `dispatch_vehicle` schema includes a `priority` enum with a default behavior description. This reduces the model's burden to invent values and ensures consistent usage.
*   **Descriptive Precision:** Each description includes usage triggers ("Use this when..."). This acts as a heuristic for the model, improving selection accuracy in complex prompts.

### Pitfall Guide

Production MCP systems encounter recurring design failures. Recognizing and mitigating these pitfalls is essential for reliable deployments.

1.  **The "God Tool" Anti-Pattern**
    *   *Explanation:* Creating a single tool that handles multiple distinct actions via an `action` or `command` parameter. This forces the model to perform multi-step reasoning: select the tool, then select the action, then generate arguments for that action.
    *   *Fix:* Decompose into atomic tools. Each tool should map to one distinct capability.

2.  **Schema Ambiguity**
    *   *Explanation:* Using generic fields like `data`, `payload`, or `options` without structure. The model cannot infer the expected shape of the data, leading to hallucinated arguments or validation errors.
    *   *Fix:* Define every field explicitly. Use specific types, descriptions, and enums. Never use `any` or generic objects.

3.  **Description Implementation Leakage**
    *   *Explanation:* Descriptions that mention internal details, such as "Calls the `/api/v2` endpoint" or "Uses the Redis cache." The model does not care about implementation; it cares about capability.
    *   *Fix:* Write descriptions from the user's perspective. Focus on the outcome and the conditions for use.

4.  **Verb Inconsistency**
    *   *Explanation:* Mixing naming conventions, such as `get_user`, `fetch_user`, and `retrieve_user`. This creates semantic noise and can confuse the model about whether these are distinct tools or duplicates.
    *   *Fix:* Standardize a verb lexicon. For example, use `get` for retrieval, `create` for creation, `update` for modification, and `delete` for removal. Enforce this across the toolset.

5.  **Tool Sprawl**
    *   *Explanation:* Exposing too many tools in a single context. As the number of tools increases, the model's selection accuracy decreases due to the "needle in a haystack" effect.
    *   *Fix:* Group related tools or use a routing tool. If a domain has >20 tools, consider an orchestrator tool that delegates to sub-tools, or partition tools by context/session.

6.  **Optional Overload**
    *   *Explanation:* Marking all schema fields as optional. This gives the model too much freedom, often resulting in incomplete arguments or inconsistent behavior.
    *   *Fix:* Mark fields as `required` unless there is a valid default or the field is truly optional. Use descriptions to clarify defaults.

7.  **Return Schema Neglect**
    *   *Explanation:* Focusing only on input schemas while ignoring the structure of the tool's output. The model relies on return values to inform subsequent steps. Poorly structured outputs can break agentic chains.
    *   *Fix:* While MCP focuses on input, ensure your tool implementation returns structured, predictable data. Document expected return formats in your internal design to ensure consistency.

### Production Bundle

#### Action Checklist

- [ ] **Audit Tool Names:** Verify all tools follow a `verb_noun` structure with standardized verbs.
- [ ] **Eliminate Generic Schemas:** Remove all `data`, `payload`, or `params` fields; replace with explicit properties.
- [ ] **Refine Descriptions:** Ensure descriptions describe the outcome and usage conditions, not implementation details.
- [ ] **Enforce Atomicity:** Split any tool that accepts an action type or command parameter into separate tools.
- [ ] **Review Tool Count:** Assess the total number of tools per context; apply grouping if the count exceeds 20.
- [ ] **Validate Constraints:** Check that all required fields are marked and enums are used where appropriate.
- [ ] **Perform Blind Testing:** Test tool selection with edge-case prompts to verify accuracy and argument generation.

#### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
| :--- | :--- | :--- | :--- |
| **High-Volume CRUD Operations** | Atomic Tools | Maximizes selection accuracy and argument precision for frequent actions. | Higher token cost due to more tool definitions, but lower error rate. |
| **Low-Frequency Admin Tasks** | Grouped Tools | Reduces context window usage for rarely used capabilities. | Lower token cost, but slightly higher risk of selection error. |
| **Complex Multi-Step Workflows** | Orchestrator Tool | Delegates complexity to a sub-agent or routing logic, keeping the main interface clean. | Adds latency for routing, but improves scalability and maintainability. |
| **Domain with >20 Tools** | Context Partitioning | Limits the toolset visible to the model, improving selection accuracy. | Requires architectural changes to manage tool visibility. |

#### Configuration Template

Use this template to define a production-ready MCP tool. This structure enforces semantic clarity and strict schema validation.

```json
{
  "name": "retrieve_vehicle_telemetry",
  "description": "Fetches real-time location, speed, and fuel levels for a specific vehicle. Use this when the user asks for current status or location of a vehicle.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "vehicle_id": {
        "type": "string",
        "description": "The unique VIN or fleet ID of the vehicle."
      }
    },
    "required": ["vehicle_id"],
    "additionalProperties": false
  }
}

Key Elements:

• additionalProperties: false: Prevents the model from adding unexpected fields.
• Explicit description for each property.
• Clear required array.

Quick Start Guide

1. List Capabilities: Identify all distinct actions your system supports. Group them by domain.
2. Draft Atomic Names: Assign a verb_noun name to each capability. Standardize verbs across the set.
3. Define Schemas: Create explicit JSON schemas for each tool. Avoid generic fields; use specific types and constraints.
4. Write Descriptions: Draft descriptions that focus on the outcome and usage conditions. Include "Use this when..." triggers.
5. Validate: Run a blind test with sample prompts to verify tool selection and argument generation. Iterate based on failures.