This is a quick reference checklist. For comprehensive guidance with code examples, see Best Practices for Creating Tools.
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 |