Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

docs: standardize ToolAnnotations examples (#3952)

Gnani Rahulff8aa484ff07
diff --git a/docs/integrations/chatgpt.mdx b/docs/integrations/chatgpt.mdx
index 92ddb7404..23249f92c 100644
--- a/docs/integrations/chatgpt.mdx
+++ b/docs/integrations/chatgpt.mdx
@@ -92,10 +92,12 @@ The connector must be explicitly enabled in each chat session through Developer
### Skip Confirmations
-Use `annotations={"readOnlyHint": True}` to skip confirmation prompts for read-only tools:
+Use `annotations=ToolAnnotations(readOnlyHint=True)` to skip confirmation prompts for read-only tools:
```python
[email protected](annotations={"readOnlyHint": True})
+from mcp.types import ToolAnnotations
+
[email protected](annotations=ToolAnnotations(readOnlyHint=True))
def get_status() -> str:
"""Check system status."""
return "All systems operational"
@@ -153,4 +155,3 @@ def fetch(id: str) -> dict:
5. Ask research questions
ChatGPT will use your `search` and `fetch` tools to find and cite relevant information.
-
diff --git a/docs/servers/tools.mdx b/docs/servers/tools.mdx
index 129d0b2dc..073a16f6d 100644
--- a/docs/servers/tools.mdx
+++ b/docs/servers/tools.mdx
@@ -915,15 +915,17 @@ Annotations serve several purposes in client applications:
- Describing the safety profile of tools (destructive vs. non-destructive)
- Signaling if tools interact with external systems
-You can add annotations to a tool using the `annotations` parameter in the `@mcp.tool` decorator:
+You can add annotations to a tool using the `annotations` parameter in the `@mcp.tool` decorator. FastMCP accepts either a plain dict or `ToolAnnotations`; the examples below use `ToolAnnotations` for consistency and stronger editor/type support.
```python
+from mcp.types import ToolAnnotations
+
@mcp.tool(
- annotations={
- "title": "Calculate Sum",
- "readOnlyHint": True,
- "openWorldHint": False
- }
+ annotations=ToolAnnotations(
+ title="Calculate Sum",
+ readOnlyHint=True,
+ openWorldHint=False,
+ )
)
def calculate_sum(a: float, b: float) -> float:
"""Add two numbers together."""
@@ -959,7 +961,7 @@ from mcp.types import ToolAnnotations
mcp = FastMCP("Data Server")
[email protected](annotations={"readOnlyHint": True})
[email protected](annotations=ToolAnnotations(readOnlyHint=True))
def get_user(user_id: str) -> dict:
"""Retrieve user information by ID."""
return {"id": user_id, "name": "Alice"}
@@ -981,7 +983,7 @@ def update_user(user_id: str, name: str) -> dict:
"""Update user information."""
return {"id": user_id, "name": name, "updated": True}
[email protected](annotations={"destructiveHint": True})
[email protected](annotations=ToolAnnotations(destructiveHint=True))
def delete_user(user_id: str) -> dict:
"""Permanently delete a user account."""
return {"deleted": user_id}
diff --git a/docs/v2/integrations/chatgpt.mdx b/docs/v2/integrations/chatgpt.mdx
index 18028c69d..d40855551 100644
--- a/docs/v2/integrations/chatgpt.mdx
+++ b/docs/v2/integrations/chatgpt.mdx
@@ -93,10 +93,12 @@ The connector must be explicitly enabled in each chat session through Developer
### Skip Confirmations
-Use `annotations={"readOnlyHint": True}` to skip confirmation prompts for read-only tools:
+Use `annotations=ToolAnnotations(readOnlyHint=True)` to skip confirmation prompts for read-only tools:
```python
[email protected](annotations={"readOnlyHint": True})
+from mcp.types import ToolAnnotations
+
[email protected](annotations=ToolAnnotations(readOnlyHint=True))
def get_status() -> str:
"""Check system status."""
return "All systems operational"
@@ -154,4 +156,3 @@ def fetch(id: str) -> dict:
5. Ask research questions
ChatGPT will use your `search` and `fetch` tools to find and cite relevant information.
-
diff --git a/docs/v2/servers/tools.mdx b/docs/v2/servers/tools.mdx
index 1ec8d62be..3cdcf3be5 100644
--- a/docs/v2/servers/tools.mdx
+++ b/docs/v2/servers/tools.mdx
@@ -792,15 +792,17 @@ Annotations serve several purposes in client applications:
- Describing the safety profile of tools (destructive vs. non-destructive)
- Signaling if tools interact with external systems
-You can add annotations to a tool using the `annotations` parameter in the `@mcp.tool` decorator:
+You can add annotations to a tool using the `annotations` parameter in the `@mcp.tool` decorator. FastMCP accepts either a plain dict or `ToolAnnotations`; the examples below use `ToolAnnotations` for consistency and stronger editor/type support.
```python
+from mcp.types import ToolAnnotations
+
@mcp.tool(
- annotations={
- "title": "Calculate Sum",
- "readOnlyHint": True,
- "openWorldHint": False
- }
+ annotations=ToolAnnotations(
+ title="Calculate Sum",
+ readOnlyHint=True,
+ openWorldHint=False,
+ )
)
def calculate_sum(a: float, b: float) -> float:
"""Add two numbers together."""
@@ -836,7 +838,7 @@ from mcp.types import ToolAnnotations
mcp = FastMCP("Data Server")
[email protected](annotations={"readOnlyHint": True})
[email protected](annotations=ToolAnnotations(readOnlyHint=True))
def get_user(user_id: str) -> dict:
"""Retrieve user information by ID."""
return {"id": user_id, "name": "Alice"}
@@ -858,7 +860,7 @@ def update_user(user_id: str, name: str) -> dict:
"""Update user information."""
return {"id": user_id, "name": name, "updated": True}
[email protected](annotations={"destructiveHint": True})
[email protected](annotations=ToolAnnotations(destructiveHint=True))
def delete_user(user_id: str) -> dict:
"""Permanently delete a user account."""
return {"deleted": user_id}