Tool Design Checklist for Agents and MCP

How to name, describe, and shape tools so models call them correctly and safely.

Checklist

1. Few, purposeful tools: prefer search_customers(query) over exposing raw CRUD on every table.
2. Clear names: verb_noun, namespaced if many (github_create_issue).
3. Descriptions say when to use it and when not to, plus important constraints.
4. Strict schemas: enums for fixed choices, required fields, formats (date, email), sensible defaults.
5. Concise, high-signal results: return IDs and human-readable fields; paginate or truncate large outputs and say so.
6. Actionable errors: "Invalid date '2024-13-01'; use YYYY-MM-DD" beats a stack trace.
7. Idempotency for writes (accept a client-generated key) so retries do not duplicate.
8. Annotate risk: MCP tool annotations like readOnlyHint and destructiveHint let clients ask for confirmation.

Example definition

{
  "name": "calendar_find_free_slots",
  "description": "Find open meeting slots for the given attendees. Use before proposing times. Does not create events.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "attendees": {"type": "array", "items": {"type": "string", "format": "email"}, "minItems": 1},
      "duration_minutes": {"type": "integer", "enum": [15, 30, 45, 60], "default": 30},
      "window_start": {"type": "string", "format": "date-time"},
      "window_end": {"type": "string", "format": "date-time"}
    },
    "required": ["attendees", "window_start", "window_end"]
  },
  "annotations": {"readOnlyHint": true}
}

Failure modes

• Overlapping tools confuse the model about which to call.
• Free-text parameters where enums fit lead to invalid arguments.
• Errors returned without guidance prevent the model from recovering.

Markdown version: /blueprints/mcp-tool-design-checklist.md

Related blueprints