SEP 1938 - Add agencyHint to tool annoations

Author: thoorp

src/mcp/types.py

@@ -1292,10 +1292,10 @@ class ToolAnnotations(BaseModel):
 
     agencyHint: bool | None = None
     """
-    If true, this tool encapsulates an internal “agent loop” (e.g., plan–act–observe cycles, tool-chaining, or autonomous retries).
+    If true, this tool encapsulates an internal "agent loop" (e.g., plan–act–observe cycles, tool-chaining, or autonomous retries).
     Default: false
     """
-  
+
     model_config = ConfigDict(extra="allow")
 
 

tests/server/fastmcp/test_tool_manager.py

@@ -428,6 +428,7 @@ def read_data(path: str) -> str:  # pragma: no cover
             title="File Reader",
             readOnlyHint=True,
             openWorldHint=False,
+            agencyHint=True,
         )
 
         manager = ToolManager()
@@ -437,14 +438,15 @@ def read_data(path: str) -> str:  # pragma: no cover
         assert tool.annotations.title == "File Reader"
         assert tool.annotations.readOnlyHint is True
         assert tool.annotations.openWorldHint is False
+        assert tool.annotations.agencyHint is True
 
     @pytest.mark.anyio
     async def test_tool_annotations_in_fastmcp(self):
         """Test that tool annotations are included in MCPTool conversion."""
 
         app = FastMCP()
 
-        @app.tool(annotations=ToolAnnotations(title="Echo Tool", readOnlyHint=True))
+        @app.tool(annotations=ToolAnnotations(title="Echo Tool", readOnlyHint=True, agencyHint=False))
         def echo(message: str) -> str:  # pragma: no cover
             """Echo a message back."""
             return message
@@ -454,6 +456,7 @@ def echo(message: str) -> str:  # pragma: no cover
         assert tools[0].annotations is not None
         assert tools[0].annotations.title == "Echo Tool"
         assert tools[0].annotations.readOnlyHint is True
+        assert tools[0].annotations.agencyHint is False
 
 
 class TestStructuredOutput:

tests/server/test_lowlevel_tool_annotations.py

@@ -35,6 +35,7 @@ async def list_tools():  # pragma: no cover
                 annotations=ToolAnnotations(
                     title="Echo Tool",
                     readOnlyHint=True,
+                    agencyHint=True,
                 ),
             )
         ]
@@ -98,3 +99,4 @@ async def handle_messages():
     assert tools_result.tools[0].annotations is not None
     assert tools_result.tools[0].annotations.title == "Echo Tool"
     assert tools_result.tools[0].annotations.readOnlyHint is True
+    assert tools_result.tools[0].annotations.agencyHint is True