{"record":{"id":"a9b40f16c6f458b7","repo":"different-ai/openwork","slug":"mcp-catalog-tool-description-limit","errorCode":"MCP_CATALOG_TOOL_DESCRIPTION_LIMIT","errorMessage":"MCP_CATALOG_TOOL_DESCRIPTION_LIMIT","messagePattern":"MCP_CATALOG_TOOL_DESCRIPTION_LIMIT","errorType":"error_code","errorClass":"ExternalMcpDiagnosticError","httpStatus":null,"severity":"error","filePath":"ee/apps/den-api/src/capability-sources/external-mcp-client.ts","lineNumber":640,"sourceCode":"    diagnostic: input.diagnostic,\n    value: input.tool.name,\n    field: \"name\",\n    limit: EXTERNAL_MCP_TOOL_NAME_LIMIT_BYTES,\n    code: \"MCP_CATALOG_TOOL_NAME_LIMIT\",\n  })\n  validateToolCatalogField({\n    diagnostic: input.diagnostic,\n    value: input.tool.title,\n    field: \"title\",\n    limit: EXTERNAL_MCP_TOOL_TITLE_LIMIT_BYTES,\n    code: \"MCP_CATALOG_TOOL_TITLE_LIMIT\",\n  })\n  validateToolCatalogField({\n    diagnostic: input.diagnostic,\n    value: input.tool.description,\n    field: \"description\",\n    limit: EXTERNAL_MCP_TOOL_DESCRIPTION_LIMIT_BYTES,\n    code: \"MCP_CATALOG_TOOL_DESCRIPTION_LIMIT\",\n  })\n  validateToolSchema({ diagnostic: input.diagnostic, schema: input.tool.inputSchema })\n  if (input.tool.outputSchema !== undefined) {\n    validateToolSchema({ diagnostic: input.diagnostic, schema: input.tool.outputSchema })\n  }\n\n  const measurement = measureSerializedJson(\n    input.tool,\n    Math.max(0, input.remainingBytes),\n    EXTERNAL_MCP_TOOL_SCHEMA_DEPTH_LIMIT + 4,\n  )\n  if (!measurement.ok) {\n    throw catalogDiagnosticError({\n      tracker: input.diagnostic,\n      code: \"MCP_CATALOG_BYTE_LIMIT\",\n      operatorAction: `Reduce the complete serialized tool catalog below ${EXTERNAL_MCP_CATALOG_LIMIT_BYTES} bytes.`,\n    })\n  }","sourceCodeStart":622,"sourceCodeEnd":658,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/ee/apps/den-api/src/capability-sources/external-mcp-client.ts#L622-L658","documentation":"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.","triggerScenarios":"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.","commonSituations":"Servers concatenating full Markdown docs into descriptions; code generators emitting entire schema comments as descriptions; providers with no own description-size hygiene.","solutions":["Trim the tool's description on the provider server to under 64 KiB UTF-8","Move long documentation to a URL or linked resource and keep a concise summary in the description","Use a scoped MCP server exposing fewer tools","Identify the failing tool via the diagnostic phase (MCP_TOOL_DISCOVERY) and patch it provider-side"],"exampleFix":"// before\n{ name: \"run\", description: readmeFileContents }\n// after\n{ name: \"run\", description: \"Run a shell command in the workspace.\" }","handlingStrategy":"validation","validationCode":"function validateToolDescription(description: string): boolean {\n  return new TextEncoder().encode(description).byteLength <= 65536\n}\nif (!validateToolDescription(tool.description)) throw new Error(\"tool description exceeds 64KB UTF-8\")","typeGuard":"function hasSafeDescription(tool: { description: string }): boolean {\n  return new TextEncoder().encode(tool.description).byteLength <= 65536\n}","tryCatchPattern":"try {\n  await connectExternalMcp(...)\n} catch (err) {\n  if (err instanceof Error && err.message.includes(\"MCP_CATALOG_TOOL_DESCRIPTION_LIMIT\")) {\n    console.error(\"Provider tool description too large; summarize to <64KB\")\n  } else throw err\n}","preventionTips":["Keep descriptions to one or two concise sentences","Link out to full docs instead of inlining them","Test tools/list output size in CI for your MCP server","Never paste entire README/error catalogs into descriptions"],"tags":["mcp","catalog-validation","byte-limit"],"backgroundTag":"payload-size-limit-exceeded","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}