WebMCP Documentation

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

Best Practices

Complete guide with detailed code examples

Tool Schemas

Input validation and schema design

Tool Registration

How to register tools

Security Guide

Security best practices