Description

Reference agent: Codex CLI v0.118+, MCP spec (2025-11-05)

MCP tools can declare an `outputSchema` field in their `ToolAnnotations` that describes the JSON structure of their return value. When the agent forwards this schema to the LLM in the tool declaration, the LLM can:

1. Generate more accurate tool argument structures
2. Parse and validate tool results against the schema
3. Provide typed tool outputs for downstream tool chaining

Codex CLI added first-class forwarding of `outputSchema` details in tool declarations so structured tool results are typed more precisely. Zeph's current MCP client forwards tool `description`, `inputSchema`, and `annotations` but does not forward `outputSchema` if present.

Observed Gap

When Zeph registers MCP tools, it includes the tool's `inputSchema` in the `ToolDefinition` sent to the LLM. If an MCP server declares an `outputSchema`, Zeph discards it. This means:

• The LLM cannot reason about what a tool will return before calling it
• Tool-chaining prompts must describe return shapes manually in the system prompt
• Structured outputs from tools like databases or APIs lose their type information

Proposed Approach

1. Extend `ToolDefinition` (or `McpToolMetadata`) with an optional `output_schema: Option<serde_json::Value>` field
2. In MCP tool registration, capture `tool.annotations.output_schema` if present
3. When building the tool list for the LLM API call, include `output_schema` in supported formats (OpenAI supports it in response_format-style declarations; Claude currently ignores extra fields)
4. Log a DEBUG message when an `outputSchema` is found and forwarded

Evidence

• MCP spec `tools/list` response includes `outputSchema` in `ToolAnnotations`: https://modelcontextprotocol.io/specification/2025-11-05/
• Codex CLI changelog (v0.118.0): "code-mode tool declarations now include MCP outputSchema details so structured tool results are typed more precisely"

Environment

• Version: 0.18.6

Labels

P3 research — low-urgency parity item; no user-visible breakage today