{"record":{"id":"099cee68c95f5c50","repo":"vercel/ai","slug":"tool-toolname-did-not-return-structuredconten","errorCode":null,"errorMessage":"Tool \"${toolName}\" did not return structuredContent or parseable text content","messagePattern":"Tool \"(.+?)\" did not return structuredContent or parseable text content","errorType":"exception","errorClass":"MCPClientError","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/tool/mcp-client.ts","lineNumber":1326,"sourceCode":"      const textContent = result.content.find(c => c.type === 'text');\n      if (textContent && 'text' in textContent) {\n        const parseResult = await safeParseJSON({\n          text: textContent.text,\n          schema: outputSchema,\n        });\n\n        if (!parseResult.success) {\n          throw new MCPClientError({\n            message: `Tool \"${toolName}\" returned content that does not match the expected outputSchema`,\n            cause: parseResult.error,\n          });\n        }\n\n        return parseResult.value;\n      }\n    }\n\n    throw new MCPClientError({\n      message: `Tool \"${toolName}\" did not return structuredContent or parseable text content`,\n    });\n  }\n\n  listResources({\n    params,\n    options,\n  }: {\n    params?: PaginatedRequest['params'];\n    options?: RequestOptions;\n  } = {}): Promise<ListResourcesResult> {\n    return this.listResourcesInternal({ params, options });\n  }\n\n  readResource({\n    uri,\n    options,\n  }: {","sourceCodeStart":1308,"sourceCodeEnd":1344,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/mcp/src/tool/mcp-client.ts#L1308-L1344","documentation":"MCPClientError thrown as the terminal fallback in output-schema-aware tool result processing: the tool returned neither `structuredContent` nor text content that could be parsed against the declared outputSchema. When a client supplies an outputSchema, the SDK guarantees a validated structured value or throws — this error signals the server simply produced nothing usable.","triggerScenarios":"Calling a tool with a declared outputSchema where the result contains no structuredContent and either no text content at all, empty text, or only non-text content blocks (images, audio, resource links).","commonSituations":"Server tool errored internally and returned an empty result; tool returns binary/multimodal content only while the client expects structured JSON; server not yet implementing structured output and returning an empty content array; connectivity or auth issues yielding truncated empty responses.","solutions":["Log the full tool result (result.content) to see what the server actually returned","Check the server tool for bugs/empty returns and fix it to emit structuredContent or JSON text","Remove the outputSchema from the client if the tool's output is genuinely unstructured or multimodal","Verify auth/connectivity so the server isn't returning empty error responses"],"exampleFix":"// before: expecting JSON but tool returns only an image block\nconst tool = mcpTool({ outputSchema: z.object({ url: z.string() }) });\n\n// after: either have the server wrap output as structuredContent\n// { structuredContent: { url: '...' } }\n// or handle the raw content without an outputSchema\nconst tool = mcpTool();","handlingStrategy":"try-catch","validationCode":"const result = await client.callTool({ name, arguments });\nconst hasUsableOutput =\n  result.structuredContent != null ||\n  (Array.isArray(result.content) && result.content.some(c => c.type === 'text' && c.text?.trim() !== ''));\nif (!hasUsableOutput) {\n  throw new Error('Tool returned no structuredContent or text content');\n}","typeGuard":"function isEmptyToolOutput(error: unknown): error is MCPClientError {\n  return MCPClientError.isInstance(error) && error.message.includes('did not return structuredContent or parseable text content');\n}","tryCatchPattern":"try {\n  const value = await mcpTool.execute(args, options);\n} catch (error) {\n  if (isEmptyToolOutput(error)) {\n    // inspect raw result/health of the server; retry or surface a clear message\n  } else {\n    throw error;\n  }\n}","preventionTips":["Only declare an outputSchema for tools known to return structured or JSON-text output","Check server tool health/empty-result handling; alert on empty content arrays","Inspect the full result.content to see what the server actually returned before blaming the schema"],"tags":["mcp","structured-output","empty-response","tools"],"backgroundTag":"empty-tool-output","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}