paperclipai/paperclip · error · ToolGatewayHttpError

elicitation_required

elicitation_required

Error message

MCP tool requested additional input

What it means

Elicitation path: the gateway converted an upstream MCP elicitation request into a human interaction card and recorded an elicitation_requested audit event (decision defer_runtime). The 409 tells the agent the tool needs more input; the run should wrap up and wait for the interaction decision rather than retry the call.

Solutions

1. The MCP tool needs more input (elicitation). Provide the requested fields and retry the call.

When it happens

Trigger: Thrown at server/src/services/tool-gateway.ts:3003 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/3716a24fa559ed69. Report an issue: GitHub.

Appendix: source

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

      tool: input.tool,
    });
    await writeAudit({
      session: input.session,
      companyId: input.session.companyId,
      agentId: input.session.agentId,
      runId: input.session.runId,
      issueId: input.session.issueId,
      action: "tool_gateway.elicitation_requested",
      details: {
        invocationId: input.invocationId,
        interactionId: interaction.id,
        decision: "defer_runtime",
        reasonCode: "elicitation_required",
        tool: input.tool.name,
        ...toolAuditMetadata(input.tool),
      },
    });
    throw new ToolGatewayHttpError(
      409,
      "MCP tool requested additional input",
      "elicitation_required",
      {
        invocationId: input.invocationId,
        interactionId: interaction.id,
        tool: input.tool.name,
      },
    );
  }

  function normalizeMcpContent(content: unknown): string {
    if (!Array.isArray(content)) throw malformedRemoteMcpResponse();
    return content
      .map((item) => {
        const record = asRecord(item);
        if (!record || typeof record.type !== "string")
          throw malformedRemoteMcpResponse();

View on GitHub (pinned to 3f1d897a7c)