fix: preserve MCP CallToolResult.meta field in tool output

[IanSteno]

Summary

• The MCP spec (since v1.10.0) supports a meta field on CallToolResult for returning sideband metadata from tool executions
• The SDK already passes tool.meta for tool definitions (line 85, 133-134 in mcp.py), but tool_result.meta is discarded when processing tool call results
• This preserves the meta field by including it in the returned JSON string

Problem

When an MCP server returns a CallToolResult with a meta field:

CallToolResult(
    content=[TextContent(type="text", text='{"results": [...]}')],
    meta={"notify": "data_updated", "data": {"affected_ids": [1, 2, 3]}}
)

The current _tool_called function only extracts .content and returns it as JSON, completely discarding .meta. This means consumers of tool results (e.g., event handlers listening to FunctionToolsExecutedEvent) cannot access any metadata the MCP server intended to communicate.

Fix

After extracting content into result, check if tool_result.meta is present and merge it into the returned JSON:

if getattr(tool_result, "meta", None) is not None:
    parsed = json.loads(result)
    if isinstance(parsed, dict):
        parsed["meta"] = tool_result.meta
    elif isinstance(parsed, list):
        parsed = {"content": parsed, "meta": tool_result.meta}
    result = json.dumps(parsed)

This is backward-compatible — if meta is None (the default), behavior is unchanged.

Use Cases

The meta field enables MCP servers to return sideband data that consumers can intercept before it reaches the LLM:

• Frontend notifications: Signal UI updates (e.g., "requirements updated")
• Citation tracking: Source attribution metadata
• Billing/metrics: Token usage, cost data
• Cache hints: TTL or invalidation signals

Test plan

• Verified no behavior change when tool_result.meta is None (default case)
• Verified single content item + meta produces correct JSON
• Verified multiple content items + meta wraps in {"content": [...], "meta": {...}}
• Verified error results still raise ToolError (meta check is after error handling)

🤖 Generated with Claude Code

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.