You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/docs/concepts/tools.mdx
+163Lines changed: 163 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,6 +30,13 @@ Each tool is defined with the following structure:
30
30
inputSchema: { // JSON Schema for the tool's parameters
31
31
type: "object",
32
32
properties: { ... } // Tool-specific parameters
33
+
},
34
+
annotations?: { // Optional hints about tool behavior
35
+
title?: string; // Human-readable title for the tool
36
+
readOnlyHint?:boolean; // If true, the tool does not modify its environment
37
+
destructiveHint?:boolean; // If true, the tool may perform destructive updates
38
+
idempotentHint?:boolean; // If true, repeated calls with same args have no additional effect
39
+
openWorldHint?:boolean; // If true, tool interacts with external entities
33
40
}
34
41
}
35
42
```
@@ -302,6 +309,162 @@ Here's an example of proper error handling for tools:
302
309
303
310
This approach allows the LLM to see that an error occurred and potentially take corrective action or request human intervention.
304
311
312
+
## Tool annotations
313
+
314
+
Tool annotations provide additional metadata about a tool's behavior, helping clients understand how to present and manage tools. These annotations are hints that describe the nature and impact of a tool, but should not be relied upon for security decisions.
315
+
316
+
### Purpose of tool annotations
317
+
318
+
Tool annotations serve several key purposes:
319
+
320
+
1. Provide UX-specific information without affecting model context
321
+
2. Help clients categorize and present tools appropriately
322
+
3. Convey information about a tool's potential side effects
323
+
4. Assist in developing intuitive interfaces for tool approval
324
+
325
+
### Available tool annotations
326
+
327
+
The MCP specification defines the following annotations for tools:
328
+
329
+
| Annotation | Type | Default | Description |
330
+
|------------|------|---------|-------------|
331
+
|`title`| string | - | A human-readable title for the tool, useful for UI display |
332
+
|`readOnlyHint`| boolean | false | If true, indicates the tool does not modify its environment |
333
+
|`destructiveHint`| boolean | true | If true, the tool may perform destructive updates (only meaningful when `readOnlyHint` is false) |
334
+
|`idempotentHint`| boolean | false | If true, calling the tool repeatedly with the same arguments has no additional effect (only meaningful when `readOnlyHint` is false) |
335
+
|`openWorldHint`| boolean | true | If true, the tool may interact with an "open world" of external entities |
336
+
337
+
### Example usage
338
+
339
+
Here's how to define tools with annotations for different scenarios:
340
+
341
+
```typescript
342
+
// A read-only search tool
343
+
{
344
+
name: "web_search",
345
+
description: "Search the web for information",
346
+
inputSchema: {
347
+
type: "object",
348
+
properties: {
349
+
query: { type: "string" }
350
+
},
351
+
required: ["query"]
352
+
},
353
+
annotations: {
354
+
title: "Web Search",
355
+
readOnlyHint: true,
356
+
openWorldHint: true
357
+
}
358
+
}
359
+
360
+
// A destructive file deletion tool
361
+
{
362
+
name: "delete_file",
363
+
description: "Delete a file from the filesystem",
364
+
inputSchema: {
365
+
type: "object",
366
+
properties: {
367
+
path: { type: "string" }
368
+
},
369
+
required: ["path"]
370
+
},
371
+
annotations: {
372
+
title: "Delete File",
373
+
readOnlyHint: false,
374
+
destructiveHint: true,
375
+
idempotentHint: true,
376
+
openWorldHint: false
377
+
}
378
+
}
379
+
380
+
// A non-destructive database record creation tool
381
+
{
382
+
name: "create_record",
383
+
description: "Create a new record in the database",
384
+
inputSchema: {
385
+
type: "object",
386
+
properties: {
387
+
table: { type: "string" },
388
+
data: { type: "object" }
389
+
},
390
+
required: ["table", "data"]
391
+
},
392
+
annotations: {
393
+
title: "Create Database Record",
394
+
readOnlyHint: false,
395
+
destructiveHint: false,
396
+
idempotentHint: false,
397
+
openWorldHint: false
398
+
}
399
+
}
400
+
```
401
+
402
+
### Integrating annotations in server implementation
1.**Be accurate about side effects**: Clearly indicate whether a tool modifies its environment and whether those modifications are destructive.
459
+
460
+
2.**Use descriptive titles**: Provide human-friendly titles that clearly describe the tool's purpose.
461
+
462
+
3.**Indicate idempotency properly**: Mark tools as idempotent only if repeated calls with the same arguments truly have no additional effect.
463
+
464
+
4.**Set appropriate open/closed world hints**: Indicate whether a tool interacts with a closed system (like a database) or an open system (like the web).
465
+
466
+
5.**Remember annotations are hints**: All properties in ToolAnnotations are hints and not guaranteed to provide a faithful description of tool behavior. Clients should never make security-critical decisions based solely on annotations.
467
+
305
468
## Testing tools
306
469
307
470
A comprehensive testing strategy for MCP tools should cover:
description: "Explaining MCP and why it matters in simple terms"
4
+
---
5
+
6
+
## What is MCP?
7
+
8
+
MCP (Model Context Protocol) is a standard way for AI applications and agents to connect to and work with your data sources (e.g. local files, databases, or content repositories) and tools (e.g. GitHub, Google Maps, or Puppeteer).
9
+
10
+
Think of MCP as a universal adapter for AI applications, similar to what USB-C is for physical devices. USB-C acts as a universal adapter to connect devices to various peripherals and accessories. Similarly, MCP provides a standardized way to connect AI applications to different data and tools.
11
+
12
+
Before USB-C, you needed different cables for different connections. Similarly, before MCP, developers had to build custom connections to each data source or tool they wanted their AI application to work with—a time-consuming process that often resulted in limited functionality. Now, with MCP, developers can easily add connections to their AI applications, making their applications much more powerful from day one.
13
+
14
+
## Why does MCP matter?
15
+
16
+
### For AI application users
17
+
18
+
MCP means your AI applications can access the information and tools you work with every day, making them much more helpful. Rather than AI being limited to what it already knows about, it can now understand your specific documents, data, and work context.
19
+
20
+
For example, by using MCP servers, applications can access your personal documents from Google Drive or data about your codebase from GitHub, providing more personalized and contextually relevant assistance.
21
+
22
+
Imagine asking an AI assistant: "Summarize last week's team meeting notes and schedule follow-ups with everyone."
23
+
24
+
By using connections to data sources powered by MCP, the AI assistant can:
25
+
26
+
- Connect to your Google Drive through an MCP server to read meeting notes
27
+
- Understand who needs follow-ups based on the notes
28
+
- Connect to your calendar through another MCP server to schedule the meetings automatically
29
+
30
+
### For developers
31
+
32
+
MCP reduces development time and complexity when building AI applications that need to access various data sources. With MCP, developers can focus on building great AI experiences rather than repeatedly creating custom connectors.
33
+
34
+
Traditionally, connecting applications with data sources required building custom, one-off connections for each data source and each application. This created significant duplicative work—every developer wanting to connect their AI application to Google Drive or Slack needed to build their own connection.
35
+
36
+
MCP simplifies this by enabling developers to build MCP servers for data sources that are then reusable by various applications. For example, using the open source Google Drive MCP server, many different applications can access data from Google Drive without each developer needing to build a custom connection.
37
+
38
+
This open source ecosystem of MCP servers means developers can leverage existing work rather than starting from scratch, making it easier to build powerful AI applications that seamlessly integrate with the tools and data sources their users already rely on.
39
+
40
+
## How does MCP work?
41
+
42
+
<Frame>
43
+
<imgsrc="/images/mcp-simple-diagram.png" />
44
+
</Frame>
45
+
46
+
MCP creates a bridge between your AI applications and your data through a straightforward system:
47
+
48
+
-**MCP servers** connect to your data sources and tools (like Google Drive or Slack)
49
+
-**MCP clients** are run by AI applications (like Claude Desktop) to connect them to these servers
50
+
- When you give permission, your AI application discovers available MCP servers
51
+
- The AI model can then use these connections to read information and take actions
52
+
53
+
This modular system means new capabilities can be added without changing AI applications themselves—just like adding new accessories to your computer without upgrading your entire system.
54
+
55
+
## Who creates and maintains MCP servers?
56
+
57
+
MCP servers are developed and maintained by:
58
+
59
+
- Developers at Anthropic who build servers for common tools and data sources
60
+
- Open source contributors who create servers for tools they use
61
+
- Enterprise development teams building servers for their internal systems
62
+
- Software providers making their applications AI-ready
63
+
64
+
Once an open source MCP server is created for a data source, it can be used by any MCP-compatible AI application, creating a growing ecosystem of connections. See our [list of example servers](https://modelcontextprotocol.io/examples), or [get started building your own server](https://modelcontextprotocol.io/quickstart/server).
0 commit comments