Skip to content

Commit aaa3fb7

Browse files
bryankthompsonweb-flow
bryankthompson
authored and
web-flow
committed
Add destructiveHint and openWorldHint annotations to all 26 tools
This PR adds the missing MCP tool annotations to improve AI assistant understanding of tool capabilities: - openWorldHint: true for all 26 tools (browser automation = external interaction) - destructiveHint: true for closePage, navigatePage, evaluateScript (irreversible changes) - destructiveHint: false for all other write operations (reversible modifications) These annotations help AI assistants make better decisions about: - Which tools require user confirmation before execution - Which tools interact with external systems - Which operations may cause data loss 🤖 Generated with [Claude Code](https://claude.com/claude-code)
1 parent 28b8ff8 commit aaa3fb7

10 files changed

Lines changed: 52 additions & 0 deletions

File tree

‎src/tools/ToolDefinition.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,16 @@ export interface ToolDefinition<
2424
* If true, the tool does not modify its environment.
2525
*/
2626
readOnlyHint: boolean;
27+
/**
28+
* If true, the tool may perform destructive updates to its environment.
29+
* If false, the tool performs only additive updates.
30+
*/
31+
destructiveHint?: boolean;
32+
/**
33+
* If true, this tool may interact with an "open world" of external
34+
* entities (e.g., websites, APIs, external services).
35+
*/
36+
openWorldHint?: boolean;
2737
};
2838
schema: Schema;
2939
handler: (

‎src/tools/console.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ export const listConsoleMessages = defineTool({
4343
annotations: {
4444
category: ToolCategory.DEBUGGING,
4545
readOnlyHint: true,
46+
openWorldHint: true,
4647
},
4748
schema: {
4849
pageSize: zod
@@ -91,6 +92,7 @@ export const getConsoleMessage = defineTool({
9192
annotations: {
9293
category: ToolCategory.DEBUGGING,
9394
readOnlyHint: true,
95+
openWorldHint: true,
9496
},
9597
schema: {
9698
msgid: zod

‎src/tools/emulation.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ export const emulate = defineTool({
2121
annotations: {
2222
category: ToolCategory.EMULATION,
2323
readOnlyHint: false,
24+
destructiveHint: false,
25+
openWorldHint: true,
2426
},
2527
schema: {
2628
networkConditions: zod

‎src/tools/input.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ export const click = defineTool({
1818
annotations: {
1919
category: ToolCategory.INPUT,
2020
readOnlyHint: false,
21+
destructiveHint: false,
22+
openWorldHint: true,
2123
},
2224
schema: {
2325
uid: zod
@@ -57,6 +59,8 @@ export const hover = defineTool({
5759
annotations: {
5860
category: ToolCategory.INPUT,
5961
readOnlyHint: false,
62+
destructiveHint: false,
63+
openWorldHint: true,
6064
},
6165
schema: {
6266
uid: zod
@@ -141,6 +145,8 @@ export const fill = defineTool({
141145
annotations: {
142146
category: ToolCategory.INPUT,
143147
readOnlyHint: false,
148+
destructiveHint: false,
149+
openWorldHint: true,
144150
},
145151
schema: {
146152
uid: zod
@@ -169,6 +175,8 @@ export const drag = defineTool({
169175
annotations: {
170176
category: ToolCategory.INPUT,
171177
readOnlyHint: false,
178+
destructiveHint: false,
179+
openWorldHint: true,
172180
},
173181
schema: {
174182
from_uid: zod.string().describe('The uid of the element to drag'),
@@ -198,6 +206,8 @@ export const fillForm = defineTool({
198206
annotations: {
199207
category: ToolCategory.INPUT,
200208
readOnlyHint: false,
209+
destructiveHint: false,
210+
openWorldHint: true,
201211
},
202212
schema: {
203213
elements: zod
@@ -230,6 +240,8 @@ export const uploadFile = defineTool({
230240
annotations: {
231241
category: ToolCategory.INPUT,
232242
readOnlyHint: false,
243+
destructiveHint: false,
244+
openWorldHint: true,
233245
},
234246
schema: {
235247
uid: zod
@@ -278,6 +290,8 @@ export const pressKey = defineTool({
278290
annotations: {
279291
category: ToolCategory.INPUT,
280292
readOnlyHint: false,
293+
destructiveHint: false,
294+
openWorldHint: true,
281295
},
282296
schema: {
283297
key: zod

‎src/tools/network.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ export const listNetworkRequests = defineTool({
3838
annotations: {
3939
category: ToolCategory.NETWORK,
4040
readOnlyHint: true,
41+
openWorldHint: true,
4142
},
4243
schema: {
4344
pageSize: zod
@@ -92,6 +93,7 @@ export const getNetworkRequest = defineTool({
9293
annotations: {
9394
category: ToolCategory.NETWORK,
9495
readOnlyHint: true,
96+
openWorldHint: true,
9597
},
9698
schema: {
9799
reqid: zod

‎src/tools/pages.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ export const listPages = defineTool({
1616
annotations: {
1717
category: ToolCategory.NAVIGATION,
1818
readOnlyHint: true,
19+
openWorldHint: true,
1920
},
2021
schema: {},
2122
handler: async (_request, response) => {
@@ -29,6 +30,7 @@ export const selectPage = defineTool({
2930
annotations: {
3031
category: ToolCategory.NAVIGATION,
3132
readOnlyHint: true,
33+
openWorldHint: true,
3234
},
3335
schema: {
3436
pageIdx: zod
@@ -57,6 +59,8 @@ export const closePage = defineTool({
5759
annotations: {
5860
category: ToolCategory.NAVIGATION,
5961
readOnlyHint: false,
62+
destructiveHint: true,
63+
openWorldHint: true,
6064
},
6165
schema: {
6266
pageIdx: zod
@@ -85,6 +89,8 @@ export const newPage = defineTool({
8589
annotations: {
8690
category: ToolCategory.NAVIGATION,
8791
readOnlyHint: false,
92+
destructiveHint: false,
93+
openWorldHint: true,
8894
},
8995
schema: {
9096
url: zod.string().describe('URL to load in a new page.'),
@@ -109,6 +115,8 @@ export const navigatePage = defineTool({
109115
annotations: {
110116
category: ToolCategory.NAVIGATION,
111117
readOnlyHint: false,
118+
destructiveHint: true,
119+
openWorldHint: true,
112120
},
113121
schema: {
114122
type: zod
@@ -205,6 +213,8 @@ export const resizePage = defineTool({
205213
annotations: {
206214
category: ToolCategory.EMULATION,
207215
readOnlyHint: false,
216+
destructiveHint: false,
217+
openWorldHint: true,
208218
},
209219
schema: {
210220
width: zod.number().describe('Page width'),
@@ -229,6 +239,8 @@ export const handleDialog = defineTool({
229239
annotations: {
230240
category: ToolCategory.INPUT,
231241
readOnlyHint: false,
242+
destructiveHint: false,
243+
openWorldHint: true,
232244
},
233245
schema: {
234246
action: zod

‎src/tools/performance.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ export const startTrace = defineTool({
2626
annotations: {
2727
category: ToolCategory.PERFORMANCE,
2828
readOnlyHint: true,
29+
openWorldHint: true,
2930
},
3031
schema: {
3132
reload: zod
@@ -107,6 +108,7 @@ export const stopTrace = defineTool({
107108
annotations: {
108109
category: ToolCategory.PERFORMANCE,
109110
readOnlyHint: true,
111+
openWorldHint: true,
110112
},
111113
schema: {},
112114
handler: async (_request, response, context) => {
@@ -125,6 +127,7 @@ export const analyzeInsight = defineTool({
125127
annotations: {
126128
category: ToolCategory.PERFORMANCE,
127129
readOnlyHint: true,
130+
openWorldHint: true,
128131
},
129132
schema: {
130133
insightSetId: zod

‎src/tools/screenshot.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ export const screenshot = defineTool({
1717
category: ToolCategory.DEBUGGING,
1818
// Not read-only due to filePath param.
1919
readOnlyHint: false,
20+
destructiveHint: false,
21+
openWorldHint: true,
2022
},
2123
schema: {
2224
format: zod

‎src/tools/script.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ so returned values have to JSON-serializable.`,
1717
annotations: {
1818
category: ToolCategory.DEBUGGING,
1919
readOnlyHint: false,
20+
destructiveHint: true,
21+
openWorldHint: true,
2022
},
2123
schema: {
2224
function: zod.string().describe(

‎src/tools/snapshot.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ in the DevTools Elements panel (if any).`,
1818
category: ToolCategory.DEBUGGING,
1919
// Not read-only due to filePath param.
2020
readOnlyHint: false,
21+
destructiveHint: false,
22+
openWorldHint: true,
2123
},
2224
schema: {
2325
verbose: zod
@@ -47,6 +49,7 @@ export const waitFor = defineTool({
4749
annotations: {
4850
category: ToolCategory.NAVIGATION,
4951
readOnlyHint: true,
52+
openWorldHint: true,
5053
},
5154
schema: {
5255
text: zod.string().describe('Text to appear on the page'),

0 commit comments

Comments
 (0)