> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-b-sync-npm-packages-docs-bf03420.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Design Quick Reference

> Quick reference checklist for WebMCP tool design. For detailed guidance with code examples, see Best Practices.

<Note>
  This is a quick reference checklist. For comprehensive guidance with code examples, see [Best Practices for Creating Tools](/best-practices).
</Note>

## Design Checklist

| Aspect          | Guideline                                 | Details                                                             |
| --------------- | ----------------------------------------- | ------------------------------------------------------------------- |
| **Name**        | `domain_verb_noun` pattern                | `products_search`, `cart_add_item`, `user_get_profile`              |
| **Description** | Detailed, includes when to use            | What it does, return format, prerequisites, if it changes tool list |
| **Parameters**  | Minimal required, clear names             | Use `.describe()` on every parameter, use enums for fixed choices   |
| **Response**    | Markdown format                           | Easier for AI to parse and present than JSON                        |
| **Errors**      | Structured with error codes               | `**Error (CODE):** message` format with `isError: true`             |
| **Annotations** | Mark behavior hints                       | `destructiveHint`, `idempotentHint`, `readOnlyHint`                 |
| **Scope**       | User workflows, not internal architecture | Balance granularity - not too fine, not too coarse                  |

## Naming Examples

| ✅ Good               | ❌ Avoid       |
| -------------------- | ------------- |
| `products_search`    | `doStuff`     |
| `cart_add_item`      | `action1`     |
| `user_get_profile`   | `helper`      |
| `orders_list_recent` | `processData` |

## Tool Scope Guide

| Level        | Example                                     | Assessment          |
| ------------ | ------------------------------------------- | ------------------- |
| Too granular | `user_set_first_name`, `user_set_last_name` | Too many tools      |
| Just right   | `user_update_profile`                       | Reasonable grouping |
| Too coarse   | `manage_everything`                         | Does too much       |

## Annotations Reference

| Annotation              | Use When                                     |
| ----------------------- | -------------------------------------------- |
| `destructiveHint: true` | Irreversible actions (delete, purchase)      |
| `idempotentHint: true`  | Safe to call multiple times with same result |
| `readOnlyHint: true`    | Only reads data, no modifications            |

## Related Topics

<CardGroup cols={2}>
  <Card title="Best Practices" icon="star" href="/best-practices">
    Complete guide with detailed code examples
  </Card>

  <Card title="Tool Schemas" icon="file-contract" href="/concepts/schemas">
    Input validation and schema design
  </Card>

  <Card title="Tool Registration" icon="screwdriver-wrench" href="/concepts/tool-registration">
    How to register tools
  </Card>

  <Card title="Security Guide" icon="shield" href="/security">
    Security best practices
  </Card>
</CardGroup>