Design an MCP Tool with Narrow Inputs and Clear Errors

A practical approach

Step 1

Design each tool around one task, such as search_courses or get_learner_progress, rather than a general run_query tool.

Step 2

Define a strict input schema: required fields, enumerations for fixed choices, formats for dates and identifiers, and limits on sizes.

Step 3

Write the description for a model that has never seen your system: what the tool does, when to use it and what it returns.

Step 4

Return errors that explain how to recover, such as 'course_id must be a numeric ID; use search_courses to find it', rather than stack traces.

Step 5

Enforce permissions on the server for every call. Never rely on the model to respect limits written only in the description.

Worked example

A team exposes its learning database through one MCP tool that accepts SQL. The model sometimes writes queries against tables it should not read, and errors show raw database messages. Replacing it with three tools, search_courses with a query and limit, get_course with a course_id and list_enrolments scoped to the signed-in user, makes calls accurate and keeps data access inside rules enforced by the server.

A mistake to avoid

Do not expose destructive actions, such as deleting or paying, as tools without a confirmation step in the host application. Tool descriptions and annotations are hints, not security controls.

Try it yourself

Write the name, description and input schema for two tools that would let an assistant answer questions about your course catalogue. Ask a colleague to read only those definitions and explain when they would call each tool.

Your implementation checklist

• Each tool performs one clearly named task
• Input schemas are strict and limited
• Descriptions explain when and how to use the tool
• Errors tell the model how to recover
• Permissions are enforced by the server on every call