fix(mcp): validate required params before call_tool (#2453)

Author: weiguangli-io

src/agents/mcp/server.py

@@ -600,6 +600,7 @@ async def call_tool(
         assert session is not None
 
         try:
+            self._validate_required_parameters(tool_name=tool_name, arguments=arguments)
             if meta is None:
                 return await self._run_with_retries(lambda: session.call_tool(tool_name, arguments))
             return await self._run_with_retries(
@@ -617,6 +618,40 @@ async def call_tool(
                 f"The server may have disconnected."
             ) from e
 
+    def _validate_required_parameters(
+        self, tool_name: str, arguments: dict[str, Any] | None
+    ) -> None:
+        """Validate required tool parameters from cached MCP tool schemas before invocation."""
+        if self._tools_list is None:
+            return
+
+        tool = next((item for item in self._tools_list if item.name == tool_name), None)
+        if tool is None or not isinstance(tool.inputSchema, dict):
+            return
+
+        raw_required = tool.inputSchema.get("required")
+        if not isinstance(raw_required, list) or not raw_required:
+            return
+
+        if arguments is None:
+            arguments_to_validate: dict[str, Any] = {}
+        elif isinstance(arguments, dict):
+            arguments_to_validate = arguments
+        else:
+            raise UserError(
+                f"Failed to call tool '{tool_name}' on MCP server '{self.name}': "
+                "arguments must be an object."
+            )
+
+        required_names = [name for name in raw_required if isinstance(name, str)]
+        missing = [name for name in required_names if name not in arguments_to_validate]
+        if missing:
+            missing_text = ", ".join(sorted(missing))
+            raise UserError(
+                f"Failed to call tool '{tool_name}' on MCP server '{self.name}': "
+                f"missing required parameters: {missing_text}"
+            )
+
     async def list_prompts(
         self,
     ) -> ListPromptsResult:

tests/mcp/test_client_session_retries.py

@@ -4,6 +4,7 @@
 from mcp import ClientSession, Tool as MCPTool
 from mcp.types import CallToolResult, ListToolsResult
 
+from agents.exceptions import UserError
 from agents.mcp.server import _MCPServerWithClientSession
 
 
@@ -62,3 +63,88 @@ async def test_list_tools_unlimited_retries():
     assert len(tools) == 1
     assert tools[0].name == "tool"
     assert session.list_tools_attempts == 4
+
+
+@pytest.mark.asyncio
+async def test_call_tool_validates_required_parameters_before_remote_call():
+    session = DummySession()
+    server = DummyServer(session=session, retries=0)
+    server._tools_list = [  # noqa: SLF001
+        MCPTool(
+            name="tool",
+            inputSchema={
+                "type": "object",
+                "properties": {"param_a": {"type": "string"}},
+                "required": ["param_a"],
+            },
+        )
+    ]
+
+    with pytest.raises(UserError, match="missing required parameters: param_a"):
+        await server.call_tool("tool", {})
+
+    assert session.call_tool_attempts == 0
+
+
+@pytest.mark.asyncio
+async def test_call_tool_with_required_parameters_still_calls_remote_tool():
+    session = DummySession()
+    server = DummyServer(session=session, retries=0)
+    server._tools_list = [  # noqa: SLF001
+        MCPTool(
+            name="tool",
+            inputSchema={
+                "type": "object",
+                "properties": {"param_a": {"type": "string"}},
+                "required": ["param_a"],
+            },
+        )
+    ]
+
+    result = await server.call_tool("tool", {"param_a": "value"})
+    assert isinstance(result, CallToolResult)
+    assert session.call_tool_attempts == 1
+
+
+@pytest.mark.asyncio
+async def test_call_tool_skips_validation_when_tool_is_missing_from_cache():
+    session = DummySession()
+    server = DummyServer(session=session, retries=0)
+    server._tools_list = [MCPTool(name="different_tool", inputSchema={"required": ["param_a"]})]  # noqa: SLF001
+
+    await server.call_tool("tool", {})
+    assert session.call_tool_attempts == 1
+
+
+@pytest.mark.asyncio
+async def test_call_tool_skips_validation_when_required_list_is_absent():
+    session = DummySession()
+    server = DummyServer(session=session, retries=0)
+    server._tools_list = [MCPTool(name="tool", inputSchema={"type": "object"})]  # noqa: SLF001
+
+    await server.call_tool("tool", None)
+    assert session.call_tool_attempts == 1
+
+
+@pytest.mark.asyncio
+async def test_call_tool_validates_required_parameters_when_arguments_is_none():
+    session = DummySession()
+    server = DummyServer(session=session, retries=0)
+    server._tools_list = [MCPTool(name="tool", inputSchema={"required": ["param_a"]})]  # noqa: SLF001
+
+    with pytest.raises(UserError, match="missing required parameters: param_a"):
+        await server.call_tool("tool", None)
+
+    assert session.call_tool_attempts == 0
+
+
+@pytest.mark.asyncio
+async def test_call_tool_rejects_non_object_arguments_before_remote_call():
+    session = DummySession()
+    server = DummyServer(session=session, retries=0)
+    server._tools_list = [MCPTool(name="tool", inputSchema={"required": ["param_a"]})]  # noqa: SLF001
+
+    with pytest.raises(UserError, match="arguments must be an object"):
+        await server.call_tool("tool", cast(dict[str, object] | None, ["bad"]))
+
+    assert session.call_tool_attempts == 0