MCP tool design

One tool, one responsibility

A tool that does two things forces the LLM to reason about which mode to invoke and increases the chance of a wrong call. A manage_users tool with a action: 'create' | 'update' | 'delete' parameter is harder for the LLM to use correctly than three separate tools: create_user, update_user, delete_user. The LLM selects from the tool list — many small tools with clear names are easier to select correctly than a few large tools with complex inputs.

Exception: tools with a very small related set of operations (read-only list + get) can sometimes be combined when the fields are disjoint and the description is clear. Use judgement — the test is whether the description string can state the tool's purpose in one unambiguous sentence.

Idempotency for safe retries

LLMs retry tool calls when they receive no result, a network timeout, or an ambiguous error. A non-idempotent write tool (one that performs the operation again on retry) produces duplicate records, duplicate charges, or duplicate emails. Design write tools to be idempotent when possible.

// Idempotent create with client-generated key
const CreateUserSchema = z.object({
  idempotencyKey: z.string().uuid().describe(
    'Client-generated UUID for deduplication. Generate a new UUID for each intended creation. ' +
    'Re-sending the same key returns the previously created user.'
  ),
  name:  z.string().min(1).describe('Full name of the user'),
  email: z.string().email().describe('Email address — must be unique'),
});

// In the handler:
const existing = await db.getByIdempotencyKey(parsed.data.idempotencyKey);
if (existing) return { content: [{ type: 'text', text: JSON.stringify(existing) }] };

const user = await db.createUser(parsed.data);
await db.setIdempotencyKey(parsed.data.idempotencyKey, user.id);
return { content: [{ type: 'text', text: JSON.stringify(user) }] };

Naming conventions

Tool names are the first thing the LLM reads when selecting a tool. Clear, consistent names reduce the chance of the wrong tool being called.

Writing tool descriptions as LLM instructions

The tool description is not a human-readable doc comment — it is the instruction the LLM uses to decide whether to call this tool and in what context. Write it as a directive: state the purpose, the primary use case, and when not to use it (especially if there's a similar tool that might be confused).

// Weak description — tells the LLM nothing useful
{
  name: 'search_users',
  description: 'Search for users.',
}

// Strong description — LLM instructions
{
  name: 'search_users',
  description:
    'Search for users by name, email, or partial match. Returns a paginated list of matching users. ' +
    'Use this to find a user ID before calling get_user or update_user. ' +
    'Do not use this to check if a specific user exists — use get_user with the known ID instead.',
}

// Destructive tool — explicit warning
{
  name: 'delete_user',
  description:
    'Permanently delete a user account and all associated data. This operation is irreversible. ' +
    'Always confirm the userId with the user before calling this tool. ' +
    'Requires confirm: true to prevent accidental deletion.',
}

"Do not use this for…" instructions are especially valuable when two tools have overlapping capabilities. The LLM reads all tool descriptions before selecting — explicit disambiguation prevents wrong-tool calls.

Field descriptions as LLM guidance

The description in each inputSchema property is displayed by MCP Inspector and read by LLM clients when choosing argument values. Write each as an instruction that tells the LLM exactly what value to provide.

const SearchUsersSchema = z.object({
  query: z.string().min(1).describe(
    'Search term to match against user name and email. Supports partial matches. ' +
    'Example: "alice" matches "Alice Smith" and "alice@example.com".'
  ),
  page: z.number().int().positive().default(1).describe(
    '1-based page number. First page is 1, not 0.'
  ),
  pageSize: z.number().int().min(1).max(100).default(20).describe(
    'Number of results per page. Default 20. Maximum 100.'
  ),
  status: z.enum(['active', 'suspended', 'deleted']).optional().describe(
    'Filter by account status. Omit to return all statuses.'
  ),
});

Callouts worth including in descriptions: 1-based vs 0-based pagination (LLMs often guess 0), enum values with brief explanations, expected format for dates or IDs, and what happens if a field is omitted.

Minimal required parameters

Every required parameter is a decision the LLM must make correctly or the tool call fails. Prefer optional parameters with sensible defaults over required parameters with obvious defaults.

Required parameters should be things the LLM cannot reasonably guess or default: the search query, the resource ID to act on, the content to create. Configuration (pagination, sorting, filtering) should have defaults that cover the most common case.

Output structure for downstream tool calls

Tool results feed directly into subsequent tool calls in an agent loop. If a tool returns an unstructured prose string, the LLM must parse it to extract the IDs or values needed for the next call. Return structured data that the LLM can reference directly.

// Unstructured — LLM must parse to find the user ID for the next call
return {
  content: [{
    type: 'text',
    text: 'Found 3 users: Alice Smith (alice@example.com), Bob Jones...',
  }],
};

// Structured — user IDs are immediately accessible for downstream calls
return {
  content: [{
    type: 'text',
    text: JSON.stringify({
      users: [
        { id: 'usr_abc123', name: 'Alice Smith', email: 'alice@example.com' },
        { id: 'usr_def456', name: 'Bob Jones',   email: 'bob@example.com' },
      ],
      total: 3,
      page: 1,
      pageSize: 20,
    }),
  }],
};

The LLM can reference users[0].id in the next tool call (update_user, delete_user) without re-querying. Include pagination metadata so the LLM knows whether to request subsequent pages.

Confirmation for irreversible operations

Destructive operations (delete, archive, send, publish) should require explicit confirmation from the LLM to prevent accidental invocation. A confirm: true required field forces the LLM to reason about whether it wants to proceed before committing.

const DeleteUserSchema = z.object({
  userId:  z.string().uuid().describe('UUID of the user to delete'),
  confirm: z.literal(true).describe(
    'Must be exactly true to confirm permanent deletion. ' +
    'Verify with the user before setting this field.'
  ),
});

// In the handler: the schema validation already ensures confirm === true
// The LLM cannot call this tool without explicitly passing confirm: true

Requiring z.literal(true) (not z.boolean()) means the field must be true, not just any boolean. The description instructs the LLM to verify with the user first — a prompt-injection safeguard for tools that could be destructively triggered by malicious external content.

Tool granularity decisions

The right number of tools is not always "one per database operation." Overly fine-grained tools increase the number of round trips an agent needs; overly coarse tools are confusing and error-prone.

Backward-compatible tool evolution

LLM clients cache tool lists and system prompts. Renaming or removing a tool breaks existing agent prompts that reference the old name. Changing a required parameter to optional is safe; changing an optional to required is not.

• Safe: Add an optional parameter with a default. Existing calls continue to work.
• Safe: Expand an enum with new values. Existing values remain valid.
• Breaking: Rename a tool. Add the new name alongside the old; deprecate the old name in its description.
• Breaking: Remove a required parameter. Add a transition period where the parameter is optional.
• Breaking: Change an output field name. Existing agent prompts that reference the old field name will fail.

See MCP server versioning for strategies when breaking changes are necessary.

Tool design checklist

What tool design cannot guarantee

Even a perfectly designed tool can fail to run reliably in production. Network outages, database connection exhaustion, deployment failures, and infrastructure misconfiguration are invisible to the tool's design. An LLM that calls a well-designed tool and receives no response — because the server is down — has no way to distinguish "tool design problem" from "server unavailable." AliveMCP probes your live MCP server's initialize and tools/list endpoints every 60 seconds, so tool availability failures are detected before LLM clients encounter them.

Related questions

Further reading

• MCP server input validation — defending tool handlers from invalid LLM arguments
• MCP server Zod validation — type-safe inputSchema from a single schema definition
• MCP server type safety — exhaustive dispatch and typed tool registries
• MCP server error handling — structuring errors so LLMs can recover
• MCP server error codes — JSON-RPC protocol errors vs isError responses
• MCP server versioning — backward-compatible tool evolution
• MCP server SDK — official SDK patterns for tool registration
• MCP server testing — verify tool behavior with automated tests
• AliveMCP — monitor that your tools are reachable and responsive in production