Amey-Thakur MCP tool design
An agent picks a tool from its name, description, and schema alone. Most tool-calling failures are not reasoning failures but description failures: two tools that sound alike, a parameter whose meaning is implied, or a name that does not say what it does.
Method
- Name by the action, specifically. create_invoice rather than invoice or handle_billing. The name is the strongest selection signal and vague names cause misselection.
- Write the description for the moment of choice. What it does, when to use it, and when not to. Naming the alternative in the description is what separates two similar tools.
- Make the schema carry the meaning. Enums instead of free strings, required fields marked, formats stated, and every parameter described. An agent cannot infer that a date must be ISO from a string type.
- Keep each tool to one job. A tool with a mode parameter that changes its behaviour entirely is several tools sharing a name, and agents choose modes badly.
- Return structured, compact results. The response enters the agent's context, so return what is needed for the next step rather than everything available (see mcp-context-budgeting).
- Make destructive tools obvious and separate. Deletion and irreversible actions get explicit names and confirmation parameters rather than being a flag on a general tool (see mcp-security-boundaries).
- Test selection with realistic prompts. Give a model the tool list and real requests, then check which it picks. Selection accuracy is the property that matters (see mcp-server-testing).
Boundaries
Tool design shapes selection; it cannot make an agent competent at a task it does not understand. Too many tools degrades selection regardless of quality, so a large surface needs grouping or filtering. Schemas constrain shape rather than semantics, so validation remains the server's job.