{"record":{"id":"91afcc320ed20ded","repo":"PrefectHQ/fastmcp","slug":"unknown-tool-tool-name","errorCode":null,"errorMessage":"Unknown tool: {tool_name}","messagePattern":"Unknown tool: (.+?)","errorType":"exception","errorClass":"NotFoundError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/experimental/transforms/code_mode.py","lineNumber":621,"sourceCode":"        ) -> Any:\n            \"\"\"Execute tool calls using Python code.\"\"\"\n\n            call_count = 0\n\n            async def call_tool(tool_name: str, params: dict[str, Any]) -> Any:\n                nonlocal call_count\n                if max_tool_calls is not None:\n                    call_count += 1\n                    if call_count > max_tool_calls:\n                        raise ToolError(\n                            f\"Tool call limit exceeded: at most {max_tool_calls} \"\n                            \"call_tool() invocations are allowed per execute().\"\n                        )\n\n                backend_tools = await transform.get_tool_catalog(ctx)\n                tool = transform._find_tool(tool_name, backend_tools)\n                if tool is None:\n                    raise NotFoundError(f\"Unknown tool: {tool_name}\")\n\n                result = await ctx.fastmcp.call_tool(tool.name, params)\n                return _unwrap_tool_result(result)\n\n            return await transform.sandbox_provider.run(\n                code,\n                external_functions={\"call_tool\": call_tool},\n            )\n\n        return Tool.from_function(\n            fn=execute,\n            name=self.execute_tool_name,\n            description=self._build_execute_description(),\n        )\n\n\n__all__ = [\n    \"CodeMode\",","sourceCodeStart":603,"sourceCodeEnd":639,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py#L603-L639","documentation":"Inside the CodeMode sandbox, call_tool() resolves the requested tool against the backend catalog via _find_tool(). If no tool matches the given name, NotFoundError('Unknown tool: <name>') is raised, and the sandboxed code sees this as a failed tool call.","triggerScenarios":"Generated code calls call_tool() with a name not present in the transform's tool catalog — a hallucinated/mistyped tool name, a name only available after prefixing/renaming by the transform, or a tool removed from the underlying server between catalog fetches.","commonSituations":"LLM-written code guessing tool names instead of using the discovery tool's catalog; stale catalogs after server tool changes; name mismatches because discovery lists transformed names while code uses original server names.","solutions":["Fix the tool name in the generated code to match one in the catalog exactly","Have sandboxed code call the discovery/catalog tool first to list valid names before invoking","Verify the tool exists on the underlying FastMCP server and isn't filtered out by the transform's tool set","Catch NotFoundError inside generated code and fall back to listing tools"],"exampleFix":"// before\nresult = await call_tool(\"get_wether\", {\"city\": \"Paris\"})\n\n// after\ncatalog = await get_tool_catalog()\nresult = await call_tool(\"get_weather\", {\"city\": \"Paris\"})","handlingStrategy":"try-catch","validationCode":"catalog = await transform.get_tool_catalog(ctx)\navailable = {t.name for t in catalog}\nassert \"get_weather\" in available, f\"Tool missing; available: {sorted(available)}\"","typeGuard":"def tool_exists(catalog_names: set[str], tool_name: str) -> bool:\n    return tool_name in catalog_names","tryCatchPattern":"try:\n    result = await call_tool(\"get_weather\", params)\nexcept NotFoundError:\n    catalog = await get_tool_catalog()\n    raise RuntimeError(f\"Unknown tool 'get_weather'; valid: {[t.name for t in catalog]}\")","preventionTips":["Always consult the discovery/catalog tool to list valid names before calling","Instruct the code-generating model to use only names from the catalog, verbatim","Remember discovery names may be transformed/prefixed versus raw server tool names"],"tags":["code-mode","not-found","tool-error","fastmcp"],"backgroundTag":"tool-not-found","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}