Skip to content

Commit d617b73

Browse files
bryankthompsonOrKoN
bryankthompson
authored and
OrKoN
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 ddeacfe commit d617b73

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)