different-ai/openwork · error · ExternalMcpDiagnosticError

MCP_CATALOG_TOOL_DESCRIPTION_LIMIT

MCP_CATALOG_TOOL_DESCRIPTION_LIMIT

Error message

MCP_CATALOG_TOOL_DESCRIPTION_LIMIT

What it means

Thrown by measureCatalogTool when a tool's `description` exceeds EXTERNAL_MCP_TOOL_DESCRIPTION_LIMIT_BYTES (64 KiB of UTF-8). Descriptions are embedded in the serialized catalog passed to agents, so the gateway caps them to keep the catalog within its total byte budget.

Solutions

1. Trim the tool's description on the provider server to under 64 KiB UTF-8
2. Move long documentation to a URL or linked resource and keep a concise summary in the description
3. Use a scoped MCP server exposing fewer tools
4. Identify the failing tool via the diagnostic phase (MCP_TOOL_DISCOVERY) and patch it provider-side

Example fix

// before
{ name: "run", description: readmeFileContents }
// after
{ name: "run", description: "Run a shell command in the workspace." }

function validateToolDescription(description: string): boolean {
  return new TextEncoder().encode(description).byteLength <= 65536
}
if (!validateToolDescription(tool.description)) throw new Error("tool description exceeds 64KB UTF-8")

function hasSafeDescription(tool: { description: string }): boolean {
  return new TextEncoder().encode(tool.description).byteLength <= 65536
}

try {
  await connectExternalMcp(...)
} catch (err) {
  if (err instanceof Error && err.message.includes("MCP_CATALOG_TOOL_DESCRIPTION_LIMIT")) {
    console.error("Provider tool description too large; summarize to <64KB")
  } else throw err
}

When it happens

Trigger: A tools/list page returns a tool whose description field is larger than 65536 UTF-8 bytes; validation occurs right after the title check in measureCatalogTool.

Common situations: Servers concatenating full Markdown docs into descriptions; code generators emitting entire schema comments as descriptions; providers with no own description-size hygiene.

Related errors

• MCP_CATALOG_BYTE_LIMIT
• MCP_CATALOG_TOOL_TITLE_LIMIT
• MCP_CATALOG_CURSOR_SIZE_LIMIT
• MCP_CATALOG_DUPLICATE_TOOL
• MCP_CATALOG_ITEM_LIMIT

AI-assisted analysis of different-ai/openwork@2b7df46e8a (2026-09-01). Data as JSON: /api/errors/a9b40f16c6f458b7. Report an issue: GitHub.

Appendix: source

Thrown at ee/apps/den-api/src/capability-sources/external-mcp-client.ts:640

    diagnostic: input.diagnostic,
    value: input.tool.name,
    field: "name",
    limit: EXTERNAL_MCP_TOOL_NAME_LIMIT_BYTES,
    code: "MCP_CATALOG_TOOL_NAME_LIMIT",
  })
  validateToolCatalogField({
    diagnostic: input.diagnostic,
    value: input.tool.title,
    field: "title",
    limit: EXTERNAL_MCP_TOOL_TITLE_LIMIT_BYTES,
    code: "MCP_CATALOG_TOOL_TITLE_LIMIT",
  })
  validateToolCatalogField({
    diagnostic: input.diagnostic,
    value: input.tool.description,
    field: "description",
    limit: EXTERNAL_MCP_TOOL_DESCRIPTION_LIMIT_BYTES,
    code: "MCP_CATALOG_TOOL_DESCRIPTION_LIMIT",
  })
  validateToolSchema({ diagnostic: input.diagnostic, schema: input.tool.inputSchema })
  if (input.tool.outputSchema !== undefined) {
    validateToolSchema({ diagnostic: input.diagnostic, schema: input.tool.outputSchema })
  }

  const measurement = measureSerializedJson(
    input.tool,
    Math.max(0, input.remainingBytes),
    EXTERNAL_MCP_TOOL_SCHEMA_DEPTH_LIMIT + 4,
  )
  if (!measurement.ok) {
    throw catalogDiagnosticError({
      tracker: input.diagnostic,
      code: "MCP_CATALOG_BYTE_LIMIT",
      operatorAction: `Reduce the complete serialized tool catalog below ${EXTERNAL_MCP_CATALOG_LIMIT_BYTES} bytes.`,
    })
  }

View on GitHub (pinned to 2b7df46e8a)