# Tool Design Checklist for Agents and MCP

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

Category: MCP & Tool Use  
Tags: tool-design, mcp, schemas, best-practices  
Setup time (estimate): 30 minutes per tool  
Estimated cost: Free.  
Last verified: not yet independently verified

## 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

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