{"record":{"id":"06737a54c9ace610","repo":"crewAIInc/crewAI","slug":"failed-to-fetch-tools-from-agent-handler-tool-pack","errorCode":null,"errorMessage":"Failed to fetch tools from Agent Handler Tool Pack","messagePattern":"Failed to fetch tools from Agent Handler Tool Pack","errorType":"exception","errorClass":"MergeAgentHandlerToolError","httpStatus":null,"severity":"error","filePath":"lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/merge_agent_handler_tool.py","lineNumber":309,"sourceCode":"            ...     registered_user_id=\"91b2b905-e866-40c8-8be2-efe53827a0aa\",\n            ...     tool_names=[\"linear__create_issue\", \"linear__get_issues\"],\n            ... )\n        \"\"\"\n        temp_instance = cls(\n            name=\"temp\",\n            description=\"temp\",\n            tool_pack_id=tool_pack_id,\n            registered_user_id=registered_user_id,\n            tool_name=\"temp\",\n            base_url=base_url,\n            args_schema=BaseModel,\n        )\n\n        try:\n            result = temp_instance._make_mcp_request(method=\"tools/list\")\n\n            if \"result\" not in result or \"tools\" not in result[\"result\"]:\n                raise MergeAgentHandlerToolError(\n                    \"Failed to fetch tools from Agent Handler Tool Pack\"\n                )\n\n            available_tools = result[\"result\"][\"tools\"]\n\n            if tool_names:\n                available_tools = [\n                    t for t in available_tools if t.get(\"name\") in tool_names\n                ]\n\n                found_names = {t.get(\"name\") for t in available_tools}\n                missing_names = set(tool_names) - found_names\n                if missing_names:\n                    logger.warning(\n                        f\"The following tools were not found in the Tool Pack: {missing_names}\"\n                    )\n\n            tools = []","sourceCodeStart":291,"sourceCodeEnd":327,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/merge_agent_handler_tool.py#L291-L327","documentation":"Thrown by the classmethod that discovers tools in a Merge Tool Pack: it issues a tools/list MCP request and expects result.result.tools in the response. If either key is missing — malformed response, auth failure that returned an error object instead, or a tool_pack_id/registered_user_id pointing at an empty/nonexistent pack — this generic 'Failed to fetch tools' error results.","triggerScenarios":"Calling from_tool_name / the discovery classmethod with an invalid tool_pack_id or registered_user_id; the API returning a JSON-RPC error object (no 'result' key); an empty tool pack; a base_url serving a different API shape.","commonSituations":"Copied IDs wrong from the Merge dashboard; the pack has no registered tools; key env var unset so every request errors; environment mismatch (staging vs prod base_url).","solutions":["Verify AGENT_HANDLER_API_KEY is set and valid (requests fail into the same generic error)","Double-check tool_pack_id and registered_user_id against the Merge dev console","Confirm the pack actually contains tools (non-empty) in the dashboard","If using a custom base_url, hit {base_url}/api/v1/tool-packs/{id}/registered-users/{uid}/mcp manually with a tools/list payload to inspect the raw response"],"exampleFix":"# before\ntools = MergeAgentHandlerTool.from_tool_name(\n    tool_name=\"x\", tool_pack_id=\"wrong-id\", registered_user_id=UID\n)  # Failed to fetch tools\n\n# after\n# 1) confirm IDs and key\nassert os.environ[\"AGENT_HANDLER_API_KEY\"]\n# 2) use exact ids from the Merge dashboard\nTOOLS = MergeAgentHandlerTool.from_tool_name(\n    tool_name=\"x\", tool_pack_id=PACK_ID, registered_user_id=REG_USER_ID\n)","handlingStrategy":"validation","validationCode":"import os\n\ndef can_fetch_tool_pack() -> bool:\n    return bool(\n        os.environ.get(\"AGENT_HANDLER_API_KEY\")\n        and TOOL_PACK_ID  # non-empty, from dashboard\n        and REGISTERED_USER_ID\n    )\n\nassert can_fetch_tool_pack()","typeGuard":null,"tryCatchPattern":"try:\n    tools = MergeAgentHandlerTool.from_tool_name(name, PACK_ID, UID)\nexcept MergeAgentHandlerToolError as e:\n    if \"Failed to fetch tools\" in str(e):\n        raise SystemExit(\n            \"Check AGENT_HANDLER_API_KEY, tool_pack_id, registered_user_id \"\n            \"and that the pack has tools\"\n        ) from e\n    raise","preventionTips":["Validate env + IDs before discovery","Confirm in the Merge dashboard that the pack contains tools","Cache the discovered tool list to avoid repeated discovery calls"],"tags":["merge","tool-discovery","json-rpc","configuration","crewai-tools"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}