crewAIInc/crewAI · error · MergeAgentHandlerToolError

Failed to fetch tools from Agent Handler Tool Pack

Error message

Failed to fetch tools from Agent Handler Tool Pack

What it means

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.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/merge_agent_handler_tool.py:309

            ...     registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa",
            ...     tool_names=["linear__create_issue", "linear__get_issues"],
            ... )
        """
        temp_instance = cls(
            name="temp",
            description="temp",
            tool_pack_id=tool_pack_id,
            registered_user_id=registered_user_id,
            tool_name="temp",
            base_url=base_url,
            args_schema=BaseModel,
        )

        try:
            result = temp_instance._make_mcp_request(method="tools/list")

            if "result" not in result or "tools" not in result["result"]:
                raise MergeAgentHandlerToolError(
                    "Failed to fetch tools from Agent Handler Tool Pack"
                )

            available_tools = result["result"]["tools"]

            if tool_names:
                available_tools = [
                    t for t in available_tools if t.get("name") in tool_names
                ]

                found_names = {t.get("name") for t in available_tools}
                missing_names = set(tool_names) - found_names
                if missing_names:
                    logger.warning(
                        f"The following tools were not found in the Tool Pack: {missing_names}"
                    )

            tools = []

View on GitHub (pinned to 754d7323be)

Solutions

1. Verify AGENT_HANDLER_API_KEY is set and valid (requests fail into the same generic error)
2. Double-check tool_pack_id and registered_user_id against the Merge dev console
3. Confirm the pack actually contains tools (non-empty) in the dashboard
4. 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

Example fix

# before
tools = MergeAgentHandlerTool.from_tool_name(
    tool_name="x", tool_pack_id="wrong-id", registered_user_id=UID
)  # Failed to fetch tools

# after
# 1) confirm IDs and key
assert os.environ["AGENT_HANDLER_API_KEY"]
# 2) use exact ids from the Merge dashboard
TOOLS = MergeAgentHandlerTool.from_tool_name(
    tool_name="x", tool_pack_id=PACK_ID, registered_user_id=REG_USER_ID
)

import os

def can_fetch_tool_pack() -> bool:
    return bool(
        os.environ.get("AGENT_HANDLER_API_KEY")
        and TOOL_PACK_ID  # non-empty, from dashboard
        and REGISTERED_USER_ID
    )

assert can_fetch_tool_pack()

try:
    tools = MergeAgentHandlerTool.from_tool_name(name, PACK_ID, UID)
except MergeAgentHandlerToolError as e:
    if "Failed to fetch tools" in str(e):
        raise SystemExit(
            "Check AGENT_HANDLER_API_KEY, tool_pack_id, registered_user_id "
            "and that the pack has tools"
        ) from e
    raise

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• AGENT_HANDLER_API_KEY environment variable is required. Set
• API Error: {error_msg}
• Failed to load Tool Pack: {e!s}
• Failed to communicate with Agent Handler API: {e!s}
• Tool execution failed: {e!s}

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/06737a54c9ace610. Report an issue: GitHub.