feat(tool): add support for excluding arguments from tool definition

This introduces an `exclude_args` parameter to omit specified arguments
(such as `state`, `memory`, etc.).

It will exclude the mentioned args from the schema sent to the LLM and still allow them
to be passed when the tool is called.

This doesn't come with the MCP protocol but can be useful in many use cases.

src/fastmcp/server/openapi.py

@@ -226,6 +226,7 @@ class OpenAPITool(Tool):
         tags: set[str] = set(),
         timeout: float | None = None,
         annotations: ToolAnnotations | None = None,
+        exclude_args: list[str] | None = None,
         serializer: Callable[[Any], str] | None = None,
     ):
         super().__init__(
@@ -235,6 +236,7 @@ class OpenAPITool(Tool):
             fn=self._execute_request,  # We'll use an instance method instead of a global function
             tags=tags,
             annotations=annotations,
+            exclude_args=exclude_args,
             serializer=serializer,
         )
         self._client = client

src/fastmcp/server/server.py

@@ -497,6 +497,7 @@ class FastMCP(Generic[LifespanResultT]):
         description: str | None = None,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | dict[str, Any] | None = None,
+        exclude_args: list[str] | None = None,
     ) -> None:
         """Add a tool to the server.
 
@@ -519,6 +520,7 @@ class FastMCP(Generic[LifespanResultT]):
             description=description,
             tags=tags,
             annotations=annotations,
+            exclude_args=exclude_args,
         )
         self._cache.clear()
 
@@ -540,6 +542,7 @@ class FastMCP(Generic[LifespanResultT]):
         description: str | None = None,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | dict[str, Any] | None = None,
+        exclude_args: list[str] | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a tool.
 
@@ -583,6 +586,7 @@ class FastMCP(Generic[LifespanResultT]):
                 description=description,
                 tags=tags,
                 annotations=annotations,
+                exclude_args=exclude_args,
             )
             return fn
 

src/fastmcp/tools/tool.py

@@ -46,6 +46,10 @@ class Tool(BaseModel):
     annotations: ToolAnnotations | None = Field(
         None, description="Additional annotations about the tool"
     )
+    exclude_args: list[str] | None = Field(
+        None,
+        description="Arguments to exclude from the tool schema, such as State, Memory, or Credential",
+    )
     serializer: Callable[[Any], str] | None = Field(
         None, description="Optional custom serializer for tool results"
     )
@@ -58,6 +62,7 @@ class Tool(BaseModel):
         description: str | None = None,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
+        exclude_args: list[str] | None = None,
         serializer: Callable[[Any], str] | None = None,
     ) -> Tool:
         """Create a Tool from a function."""
@@ -86,10 +91,14 @@ class Tool(BaseModel):
         schema = type_adapter.json_schema()
 
         context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
+        temp_prune_params: list[str] = []
         if context_kwarg:
-            prune_params = [context_kwarg]
-        else:
-            prune_params = None
+            temp_prune_params.append(context_kwarg)
+        if exclude_args:
+            temp_prune_params.extend(exclude_args)
+        prune_params: list[str] | None = (
+            None if not temp_prune_params else temp_prune_params
+        )
 
         schema = compress_schema(schema, prune_params=prune_params)
 
@@ -100,6 +109,7 @@ class Tool(BaseModel):
             parameters=schema,
             tags=tags or set(),
             annotations=annotations,
+            exclude_args=exclude_args,
             serializer=serializer,
         )
 

src/fastmcp/tools/tool_manager.py

@@ -66,6 +66,7 @@ class ToolManager:
         description: str | None = None,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
+        exclude_args: list[str] | None = None,
     ) -> Tool:
         """Add a tool to the server."""
         tool = Tool.from_function(
@@ -75,6 +76,7 @@ class ToolManager:
             tags=tags,
             annotations=annotations,
             serializer=self._serializer,
+            exclude_args=exclude_args,
         )
         return self.add_tool(tool)
 

tests/server/test_tool_exclude_args.py

@@ -0,0 +1,76 @@
+from typing import Any
+
+from mcp.types import TextContent
+
+from fastmcp import Client, FastMCP
+
+
+async def test_tool_exclude_args_in_tool_manager():
+    """Test that tool args are excluded in the tool manager."""
+    mcp = FastMCP("Test Server")
+
+    @mcp.tool(exclude_args=["state"])
+    def echo(message: str, state: dict[str, Any] | None = None) -> str:
+        """Echo back the message provided."""
+        if state:
+            # State was read
+            pass
+        return message
+
+    tools = mcp._tool_manager.list_tools()
+    assert len(tools) == 1
+    assert tools[0].exclude_args is not None
+    for args in tools[0].exclude_args:
+        assert args not in tools[0].parameters
+
+
+async def test_add_tool_method_exclude_args():
+    """Test that tool exclude_args work with the add_tool method."""
+    mcp = FastMCP("Test Server")
+
+    def create_item(
+        name: str, value: int, state: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Create a new item."""
+        if state:
+            # State was read
+            pass
+        return {"name": name, "value": value}
+
+    mcp.add_tool(create_item, name="create_item", exclude_args=["state"])
+
+    # Check internal tool objects directly
+    tools = mcp._tool_manager.list_tools()
+    assert len(tools) == 1
+    assert tools[0].exclude_args is not None
+    assert tools[0].exclude_args == ["state"]
+    for args in tools[0].exclude_args:
+        assert args not in tools[0].parameters
+
+
+async def test_tool_functionality_with_exclude_args():
+    """Test that tool functionality is preserved when using exclude_args."""
+    mcp = FastMCP("Test Server")
+
+    def create_item(
+        name: str, value: int, state: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Create a new item."""
+        if state:
+            # state was read
+            pass
+        return {"name": name, "value": value}
+
+    mcp.add_tool(create_item, name="create_item", exclude_args=["state"])
+
+    # Use the tool to verify functionality is preserved
+    async with Client(mcp) as client:
+        result = await client.call_tool(
+            "create_item", {"name": "test_item", "value": 42}
+        )
+        assert len(result) == 1
+        assert isinstance(result[0], TextContent)
+
+        # The result should contain the expected JSON
+        assert '"name": "test_item"' in result[0].text
+        assert '"value": 42' in result[0].text