fix: implement Python SDK consistency with JSON string returns

- Return JSON.stringify() results when useStructuredContent=true for Python SDK parity
- Update all tests to expect JSON strings instead of objects/arrays
- Maintain backward compatibility when useStructuredContent=false (default)
- Honor commitment made to @seratch for Python SDK consistency
- Preserve falsy value handling (0, false, '', null) within JSON strings
- Update documentation and changeset to reflect JSON string approach

This resolves the conflict between the author's commitment and implementation,
ensuring true cross-SDK compatibility as requested by maintainers.

Author: boice-sealint

.changeset/mcp-structured-content.md

@@ -6,4 +6,4 @@ feat(mcp): add structuredContent support behind `useStructuredContent`; return f
 
 - `MCPServer#callTool` now returns the full `CallToolResult` (was `content[]`), exposing optional `structuredContent`.
 - Add `useStructuredContent` option to MCP servers (stdio/streamable-http/SSE), default `false` to avoid duplicate data by default.
-- When enabled, function tool outputs include `structuredContent` (or return it alone when no `content`).
+- When enabled, function tool outputs return JSON strings for consistency with Python SDK implementation.

packages/agents-core/src/mcp.ts

@@ -457,6 +457,7 @@ export async function getAllMcpTools<TContext = UnknownContext>(
 
 /**
  * Converts an MCP tool definition to a function tool for the Agents SDK.
+ * When useStructuredContent is enabled, returns JSON strings for consistency with Python SDK.
  */
 export function mcpToFunctionTool(
   mcpTool: MCPTool,
@@ -476,32 +477,31 @@ export function mcpToFunctionTool(
     }
     const result = await server.callTool(mcpTool.name, args);
 
-    // JS ergonomics: return objects/arrays; include structuredContent when enabled
     if (result.content && result.content.length === 1) {
       if (
         server.useStructuredContent &&
         'structuredContent' in result &&
         result.structuredContent !== undefined
       ) {
-        return [result.content[0], result.structuredContent];
+        return JSON.stringify([result.content[0], result.structuredContent]);
       }
       return result.content[0];
     } else if (result.content && result.content.length > 1) {
-      const outputs: any[] = [...result.content];
       if (
         server.useStructuredContent &&
         'structuredContent' in result &&
         result.structuredContent !== undefined
       ) {
-        outputs.push(result.structuredContent);
+        const outputs = [...result.content, result.structuredContent];
+        return JSON.stringify(outputs);
       }
-      return outputs;
+      return result.content;
     } else if (
       server.useStructuredContent &&
       'structuredContent' in result &&
       result.structuredContent !== undefined
     ) {
-      return result.structuredContent;
+      return JSON.stringify(result.structuredContent);
     }
     // Preserve backward compatibility: return empty array when no content
     return result.content || [];

packages/agents-core/test/mcpStructuredContent.test.ts

@@ -107,7 +107,7 @@ describe('MCP structuredContent handling', () => {
     );
 
     const out = await tool.invoke({} as any, '{}');
-    expect(out).toEqual([{ type: 'text', text: 'hello' }, { foo: 1 }]);
+    expect(out).toEqual(JSON.stringify([{ type: 'text', text: 'hello' }, { foo: 1 }]));
   });
 
   it('includes structuredContent when enabled: no content -> structuredContent only', async () => {
@@ -148,7 +148,7 @@ describe('MCP structuredContent handling', () => {
     );
 
     const out = await tool.invoke({} as any, '{}');
-    expect(out).toEqual({ foo: 1 });
+    expect(out).toEqual(JSON.stringify({ foo: 1 }));
   });
 
   it('includes structuredContent when enabled: multiple contents -> array with structuredContent appended', async () => {
@@ -192,11 +192,11 @@ describe('MCP structuredContent handling', () => {
     );
 
     const out = await tool.invoke({} as any, '{}');
-    expect(out).toEqual([
+    expect(out).toEqual(JSON.stringify([
       { type: 'text', text: 'a' },
       { type: 'text', text: 'b' },
       { foo: 1 },
-    ]);
+    ]));
   });
 
   it('preserves falsy structuredContent values when enabled', async () => {
@@ -243,7 +243,7 @@ describe('MCP structuredContent handling', () => {
       );
 
       const out = await tool.invoke({} as any, '{}');
-      expect(out).toEqual([{ type: 'text', text: 'hello' }, falsyValue]);
+      expect(out).toEqual(JSON.stringify([{ type: 'text', text: 'hello' }, falsyValue]));
     }
 
     // Test with no content + falsy structuredContent
@@ -269,7 +269,7 @@ describe('MCP structuredContent handling', () => {
       );
 
       const out = await tool.invoke({} as any, '{}');
-      expect(out).toEqual(falsyValue);
+      expect(out).toEqual(JSON.stringify(falsyValue));
     }
   });
 
@@ -357,10 +357,10 @@ describe('MCP structuredContent handling', () => {
     );
 
     let out = await tool.invoke({} as any, '{}');
-    expect(out).toEqual([
+    expect(out).toEqual(JSON.stringify([
       { type: 'text', text: 'with-structured' },
       { data: 'structured' },
-    ]);
+    ]));
 
     // Second call: no structured content
     (server as any).callTool = async () => ({