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

or manage.

3. Intent-Driven Descriptions

Descriptions must articulate the outcome and conditions for use, not the implementation mechanism. The model uses descriptions to decide when to invoke a tool. Descriptions should answer: "What does this tool achieve, and under what circumstances should it be used?"

4. Strict Schema Enforcement

Input schemas must be explicit. Generic fields like data, payload, or params are prohibited. Every parameter must have a specific type, a clear description, and appropriate constraints. This guides the model in generating valid arguments and reduces validation failures.

Implementation Example: Fleet Management System

Consider a logistics platform. A backend-centric design might expose a generic vehicle management endpoint. A semantic-optimized design decomposes this into atomic tools.

❌ Backend-Centric Design (Anti-Pattern)

// BAD: Overloaded tool with generic schema
const fleetTool = {
  name: "manage_vehicle",
  description: "Handles vehicle operations including tracking, routing, and status updates.",
  inputSchema: {
    type: "object",
    properties: {
      vehicle_id: { type: "string" },
      operation: { type: "string", enum: ["track", "route", "status"] },
      payload: { type: "object" } // Ambiguous structure
    },
    required: ["vehicle_id", "operation"]
  }
};

✅ Semantic-Optimized Design

// GOOD: Atomic tools with explicit schemas

// Tool 1: Retrieval Action
const retrieve_vehicle_telemetry = {
  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"]
  }
};

// Tool 2: Command Action
const dispatch_vehicle = {
  name: "dispatch_vehicle",
  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.

{
  "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.