|
1 | | -Published: May 18, 2026 |
2 | | - |
3 | | -<br /> |
4 | | - |
5 | | -| Explainer | Web | Extensions | Chrome Status | Intent | |
6 | | -|---|---|---|---|---| |
7 | | -| [GitHub](https://github.com/webmachinelearning/webmcp) | [ Origin trial](https://developer.chrome.com/origintrials/#/register_trial/4163014905550602241) | | [View](https://chromestatus.com/feature/5117755740913664) | [Intent to Experiment](https://groups.google.com/a/chromium.org/g/blink-dev/c/gmYffo5WOE8/m/OJxuQRP3AAAJ) | |
8 | | - |
9 | | -[WebMCP](https://developer.chrome.com/docs/ai/webmcp) tool declaration should be clear, without a need for |
10 | | -developers or agents to look at outputs and retry. Whether you use the |
11 | | -Imperative API or Declarative API, follow these best practices: |
12 | | - |
13 | | -- Before building, create a tool strategy. |
14 | | -- Use clear language and semantic HTML. |
15 | | -- Design your schemas and handle input. |
16 | | -- Build reliable tools. |
17 | | -- Test and debug. |
18 | | - |
19 | | -We've written separately about [creating security-minded tools](https://developer.chrome.com/docs/ai/webmcp/secure-tools). |
20 | | - |
21 | | -> [!NOTE] |
22 | | -> **Note:** For those building agents, read our [security considerations for WebMCP](https://developer.chrome.com/docs/agents/security). |
23 | | -
|
24 | | -## Create a tool strategy |
25 | | - |
26 | | -Just as you'd do for any software application, your first step should be to plan |
27 | | -your tool strategy: |
28 | | - |
29 | | -- **Each tool should consist of a single function**. For example, one tool could be to direct the user to a specific form type, where another tool should match input fields with user information. Be careful not to create overlapping tools, as the agent may be confused as to what to use. Ask yourself: can I cover multiple tasks with the same function? |
30 | | -- **Manage tool registration** . Register tools when they're useful in a certain page state, then unregister when the tool is no longer usable. |
31 | | - - [**Imperative API**](https://developer.chrome.com/docs/ai/webmcp/imperative-api): You can dynamically manage registration with `registerTool`. |
32 | | - - [**Declarative API**](https://developer.chrome.com/docs/ai/webmcp/declarative-api): You can dynamically manage registration by adding or removing the tool attributes on a form, with `toolname` and `tooldescription`. |
33 | | -- **Reduce complexity:** For most applications, static registration should be the default approach. |
34 | | -- **Trust the agent to complete the task**. Instead of writing rigid or negative instructions, assume the agent is able to understand what is required to complete the task, rather than expecting the agent to manage an exact flow of steps. |
35 | | - |
36 | | -While there isn't a maximum number of tools allowed, each tool takes up part of |
37 | | -the context window and adds to the time for completion. The more tools you |
38 | | -provide and the more the tools have overlap, the harder it is for the agent to |
39 | | -pick correctly. Experiment to determine what's right for your application. |
40 | | - |
41 | | -This helps you build individual tools, without overlapping purpose, and manage |
42 | | -when these tools are available. |
43 | | - |
44 | | -## Use clear language and semantic code |
45 | | - |
46 | | -Use clear and precise language to name tools and describe their use. This helps |
47 | | -agents find what they need, understand what they find, and use that information |
48 | | -as the developer expects. |
49 | | - |
50 | | -When writing tool names, distinguish execution from initiation, and use verbs |
51 | | -that describe exactly what happens. For example, `create-event` is a tool for |
52 | | -immediate event creation, but `start-event-creation-process` is a tool that |
53 | | -redirects the user to a form to create the event. |
54 | | - |
55 | | -A clear description should describe what the tool does and when to use it. Rely |
56 | | -on positive language and preferences instead of negative language, such as |
57 | | -limitations. |
58 | | -Don't "Don't use this tool for weather." |
59 | | - |
60 | | - |
61 | | -Limitations should be implicit in a well-written description. |
62 | | -Do |
63 | | - |
64 | | -<br /> |
65 | | - |
66 | | -> "This tool can create a calendar event, scheduled for a specific date and time." |
67 | | -
|
68 | | -<br /> |
69 | | - |
70 | | -<br /> |
71 | | - |
72 | | -Instead telling the model *what* to do, this |
73 | | -language describes the actions the tool can take. |
74 | | - |
75 | | -<br /> |
76 | | - |
77 | | -<br /> |
78 | | - |
79 | | -<br /> |
80 | | - |
81 | | -## Minimize cognitive computing |
82 | | - |
83 | | -Just as you should minimize cognitive load for humans completing complex tasks, you should also minimize cognitive computing for the model: |
84 | | - |
85 | | -- **Accept raw user input**. Avoid asking the agent to perform math or transform the input strings. For example, if a user says, "11:00 to 15:00," the tool should accept this as a string. Avoid asking the model to calculate the minutes between these times. |
86 | | -- **Declare specific types for parameters**, such as string, number, or enum. |
87 | | -- **Explain why you've made certain choices** . What choice you've made should be self-explanatory. The why helps agents make better choices. For example, if you run an ecommerce shop, declare shipping type with natural language instead of using an ambiguous ID: `shipping="Express"` instead of `shipping_id=1`. |
88 | | - |
89 | | -## Prioritize reliability |
90 | | - |
91 | | -Agents and humans benefit from tools that behave as-expected: |
92 | | - |
93 | | -- **Set a graceful failure for rate limits**. Tools should allow for reasonable repetition, such as for price comparison. If a tool is rate limited, return a meaningful error or advise the user to manually take on the task. |
94 | | -- **Update the interface state after functions are completed**. Agents may rely on the interface to plan next steps, while functions may take longer to complete than the interface load. The agent should confirm the function is complete once the interface has updated, or request an update again. |
95 | | -- **Validate strictly in code, loosely in schema**. Constraints and testing should be used for functions and code that have binary logic. While schema constraints can be helpful, they're not guaranteed. Add descriptive errors to your function code to allow the model to self-correct and retry with new, valid parameters. |
96 | | - |
97 | | -## Eval testing and debugging |
98 | | - |
99 | | -Create evaluation tests and make your tools available for debugging. Unlike deterministic unit tests, evaluations cannot be hard-coded, as outputs can take unanticipated forms. |
100 | | - |
101 | | -> [!IMPORTANT] |
102 | | -> **Key Term:** [*Evaluation-driven development*](https://web.dev/learn/ai/evaluation-driven-development) offers a repeatable, testable process for improving outputs in small steps, catching regressions and aligning mode behavior with user and product expectations. |
103 | | -
|
104 | | -- **Define the problem**. You can frame your problem like an API contract, including the input type, the output format, and any additional constraints. |
105 | | -- **Define a baseline and an ideal result**. Especially with text input, it's important to understand what types of results can get you the output you expect. |
106 | | -- **Determine how the output will be evaluated** . You're likely identifying and measuring subjective, qualitative results based on input quality, usefulness, and ability to accomplish the next task. There are a number of techniques you can use to evaluate output, including code-based checks for rule-based outputs (character limits) and [LLM-as-a-judge](https://web.dev/articles/test-llm-capabilities). |
107 | | - |
108 | | -Avoid adding narrow rules to patch issues with a particular model. For example, |
109 | | -if you include a select field for [honorifics](https://wikipedia.org/wiki/English_honorifics), the model may make the wrong choice. Instead of adding |
110 | | -narrow rules to patch this issue, abstract and adjust your tool. |
111 | | -You may do best by setting this field as optional. Then, ask the agent to ask |
112 | | -the user which choice makes sense, to ensure the user is happy with the outcome. |
113 | | - |
114 | | -## Engage and share feedback |
115 | | - |
116 | | -WebMCP is under active discussion and subject to change in the future. If you |
117 | | -try these APIs and have feedback, we'd love to hear it. |
118 | | - |
119 | | -- [Read the WebMCP explainer](https://github.com/webmachinelearning/webmcp), raise questions and participate in discussion. |
120 | | -- Review the implementation for Chrome on [Chrome Status](https://chromestatus.com/feature/5117755740913664). |
121 | | -- [Join the early preview program](http://goo.gle/chrome-ai-dev-preview-join) for an early look at new APIs and access to our mailing list. |
122 | | -- If you have feedback on Chrome's implementation, file a [Chromium bug](https://crbug.com/new?component=2021259).![Alexandra Klepper] Alexandra Klepper [GitHub](https://github.com/alexandrascript) [Bluesky](https://bsky.app/profile/alexandrascript.com) |
123 | | - |
124 | | -<br /> |
125 | | - |
| 1 | +--- |
| 2 | +name: webmcp-best-practices |
| 3 | +description: >- |
| 4 | + Chrome WebMCP tool declaration best practices: strategy, schemas, |
| 5 | + reliability, and eval testing. Use when designing or reviewing WebMCP tools. |
| 6 | +--- |
126 | 7 |
|
127 | 8 | Published: May 18, 2026 |
128 | 9 |
|
@@ -245,4 +126,4 @@ try these APIs and have feedback, we'd love to hear it. |
245 | 126 | - [Read the WebMCP explainer](https://github.com/webmachinelearning/webmcp), raise questions and participate in discussion. |
246 | 127 | - Review the implementation for Chrome on [Chrome Status](https://chromestatus.com/feature/5117755740913664). |
247 | 128 | - [Join the early preview program](http://goo.gle/chrome-ai-dev-preview-join) for an early look at new APIs and access to our mailing list. |
248 | | -- If you have feedback on Chrome's implementation, file a [Chromium bug](https://crbug.com/new?component=2021259). |
| 129 | +- If you have feedback on Chrome's implementation, file a [Chromium bug](https://crbug.com/new?component=2021259). |
0 commit comments