{"record":{"id":"71c965bc9b682a4b","repo":"agentscope-ai/agentscope","slug":"e-71c965","errorCode":null,"errorMessage":"{e}","messagePattern":"\\{e\\}","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"src/agentscope/workspace/_mcp_gateway/_mcp_gateway_app.py","lineNumber":182,"sourceCode":"        raw = await client.list_raw_tools()\n        return [t.model_dump(mode=\"json\") for t in raw]\n\n    @app.post(\"/mcps/{name}/tools/{tool}\")\n    async def _call_tool(\n        name: str,\n        tool: str,\n        request: Request,\n        agent_id: str = \"\",\n        session_id: str = \"\",\n    ) -> dict[str, Any]:\n        client = _lookup(agent_id, session_id, name)\n        body = await request.json()\n        arguments = body.get(\"arguments\") or {}\n        try:\n            tool_obj = await client.get_tool(tool)\n            chunk = await tool_obj(**arguments)\n        except ValueError as e:\n            raise HTTPException(404, str(e)) from e\n        except Exception as e:  # noqa: BLE001\n            raise HTTPException(500, str(e)) from e\n        return {\"chunk\": chunk.model_dump(mode=\"json\")}\n\n    return app\n\n\nasync def _run(\n    port: int,\n    auth_token: str | None = None,\n    instance_nonce: str | None = None,\n) -> None:\n    \"\"\"Start uvicorn on an empty registry, clean up upstreams on exit.\"\"\"\n    state = _State()\n    app = _build_app(\n        state,\n        auth_token=auth_token,\n        instance_nonce=instance_nonce,","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/workspace/_mcp_gateway/_mcp_gateway_app.py#L164-L200","documentation":"Raised as HTTP 404 by _call_tool when client.get_tool(tool) or the tool invocation raises ValueError — the MCP layer signals 'unknown tool' via ValueError, which the gateway maps to 404 with the original message. It means the connected MCP server does not expose a tool with that name.","triggerScenarios":"POST call with a tool name not offered by the registered MCP server, or calling before the server's tool list was refreshed so stale/renamed tools are referenced.","commonSituations":"Server updated and tool renamed/removed, typo in tool name, calling a tool from a different MCP server than the one registered under this name.","solutions":["List tools for the registered client first and use an exact name from the result.","Update the tool name after server upgrades; check the server's changelog.","Confirm you registered the intended server under this name (a wrong server may expose different tools).","Re-register the client if the server changed its tool set since registration."],"exampleFix":"# before\nawait client.post(\"/mcps/srv/call\", json={\"tool\": \"summarise\", \"arguments\": {}})  # 404 unknown tool\n\n# after\ntools = await client.get(\"/mcps/srv/tools\")\n# use exact name, e.g. \"summarize\"\nawait client.post(\"/mcps/srv/call\", json={\"tool\": \"summarize\", \"arguments\": {}})","handlingStrategy":"validation","validationCode":"tools_resp = await client.get(f\"/mcps/{name}/tools\", params={\"agent_id\": aid, \"session_id\": sid})\nknown = {t[\"name\"] for t in tools_resp.json().get(\"tools\", [])}\nif tool not in known:\n    raise SystemExit(f\"unknown tool {tool}; available: {sorted(known)}\")","typeGuard":null,"tryCatchPattern":"r = await client.post(f\"/mcps/{name}/call\", json={\"tool\": tool, \"arguments\": args})\nif r.status_code == 404:\n    tools = await client.get(f\"/mcps/{name}/tools\")\n    raise KeyError(f\"{tool} not in {[t['name'] for t in tools.json()['tools']]}\")","preventionTips":["Fetch and cache the tool list after registration; validate names before calling.","After upgrading an MCP server, refresh your tool name references.","Keep a single source of truth for tool names in config, not string literals scattered in code."],"tags":["agentscope","mcp","gateway","http-404","tool-not-found","unknown-tool"],"backgroundTag":"unknown-tool-invoked","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}