paperclipai/paperclip · error · ToolGatewayHttpError

tool_not_found

tool_not_found

Error message

Tool "${toolName}" not found

What it means

Catalog lookup miss: the requested tool name (static tool, connected MCP tool, or virtual on-demand tool) is not present for this company/session, so no descriptor can be resolved and the call is rejected before any policy evaluation. Usually caused by a disconnected app, a renamed upstream tool, or calling a virtual tool when no on-demand targets exist.

Solutions

1. Check the tool name against the list of available tools for this session; it may be misspelled or the providing plugin/connection is down.

When it happens

Trigger: Thrown at server/src/services/tool-gateway.ts:1865 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/752bf4c08c1ee7d9. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/tool-gateway.ts:2596

        upstreamToolName: input.tool.upstreamToolName ?? input.tool.name,
        riskLevel: input.tool.risk,
        arguments: input.parameters ?? {},
        idempotencyKey: input.idempotencyKey ?? null,
        sideEffecting: input.tool.risk !== "read",
      },
      consumeRateLimit: input.consumeRateLimit === true,
    };
  }

  function policyErrorStatus(decision: ToolAccessDecision) {
    if (decision.decision === "rate_limited") return 429;
    return 403;
  }

  function findStaticTool(toolName: string): ToolGatewayDescriptor {
    const tool = allTools().find((candidate) => candidate.name === toolName);
    if (!tool) {
      throw new ToolGatewayHttpError(
        404,
        `Tool "${toolName}" not found`,
        "tool_not_found",
        { tool: toolName },
      );
    }
    return tool;
  }

  async function findToolForSession(
    session: ToolGatewaySession,
    toolName: string,
  ): Promise<ToolGatewayDescriptor> {
    const connectedTools = await connectedMcpToolsForCompany(session.companyId);
    const hasOnDemandTargets = connectedTools.some(isOnDemandRemoteTool);
    const virtualTools = hasOnDemandTargets ? VIRTUAL_TOOLS : [];
    const tool = [...allTools(), ...connectedTools, ...virtualTools]
      .filter(

View on GitHub (pinned to 3f1d897a7c)