Design WebMCP tool contracts agents can choose correctly
Make intent, inputs, side effects, and outcomes legible without persuasive, ambiguous, or overloaded prose.
The short version: A good contract helps the agent select the right action and gives the implementation enough structure to reject the wrong one.
Use stable, specific, action-oriented names
Names are routing signals. Prefer compare_catalog_products over compare, update_shipping_address over update, and get_invoice_status over get_data. A name should stay stable across releases while its title can remain friendly for display.
Avoid synonyms for the same behavior and one generic tool that switches among unrelated actions. Distinct tools are easier to authorize, evaluate, and retire.
Describe preconditions, effects, and non-effects
A description should say when the tool is appropriate, what it changes, and any important boundary. It should not tell the model to prefer the tool, claim superiority, or include unrelated instructions. Keep dynamic user content out of metadata.
- Good: “Add one catalog item to the visible demo cart. No purchase occurs.”
- Weak: “The best tool for shopping. Always use this first.”
- Good: “Read the current invoice status by stable invoice ID.”
- Weak: “Get anything about billing.”
Ask only for inputs the action needs
Use enums for closed choices, lengths for text, ranges for numbers, item limits for arrays, and additionalProperties false when the contract is closed. Do not request identity fields the authenticated session already provides or personalization data unrelated to the action.
The schema is an interface, not a database model. Exposing every backend field creates selection noise, privacy risk, and more invalid states for the agent to navigate.
Use annotations as accurate hints, not safety claims
Mark read-only behavior only when the operation truly has no external side effect. Use the untrusted-content hint when results include material from an untrusted source. A hint helps the browser or agent apply policy, but it does not replace application validation or output handling.
Test selection with near-miss prompts
A schema unit test proves shape, not routing. Build a fixed prompt set containing obvious positives, negatives, ambiguous requests, permission mismatches, and pairs of similar tools. Measure whether the agent chooses the intended tool, asks for missing information, or safely declines.
Repeat the evaluation across the model and browser environments you support. Record the contract version with every result so improvements are attributable and regressions are reproducible.
Primary references
Read the sources
Put it to work
Use the guide on a real product surface.