Improve ToolResult and structured output documentation

[jlowin]

Summary

Comprehensive documentation improvements following #2283 (ToolResult meta support). The existing docs were confusing about structured output behavior and ToolResult usage.

Changes

Restructured Structured Output Examples

• Renamed "Object-like Results" → "Dictionaries and Objects"
• Renamed "Non-object Results" → "Primitives and Collections"
• Renamed "Complex Type Example" → "Typed Models"
• Simplified CodeGroup examples to show Tool Definition + MCP Result (instead of 3-4 confusing tabs)
• Split Primitives/Collections into two separate before/after examples

Improved ToolResult Documentation

• Renamed "Full Control with ToolResult" → "ToolResult and Metadata" (so meta appears in TOC)
• Removed confusing "Parameters" and "Behavior" H4 headings
• Flattened structure with inline field descriptions
• Added version badge for meta field (2.13.1)
• Clarified that ToolResult meta (runtime) is separate from @mcp.tool meta (static)

Enhanced Example Server

• Updated tool_result_echo.py with realistic metadata (execution time, character count, word count)
• Added comprehensive docstring explaining metadata usage

Example

Before: Confusing tabs labeled "Traditional Text Content" and "Structured JSON Content"

After: Clear two-tab layout showing "Tool Definition" and "MCP Result" with both content and structuredContent fields visible inline

Fixes documentation confusion reported in #2283 review.

---

🤖 Generated with Claude Code

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

The pull request updates documentation for tool outputs, reorganizing sections describing ToolResult with expanded examples for content, structured_content, and metadata fields. An example tool is enhanced to demonstrate metadata handling including execution timing and character counts.

Changes

Cohort / File(s)	Summary
Documentation Updates docs/servers/tools.mdx	Reorganizes Tools/Output sections with revised subsection names ("Dictionaries and Objects," "Primitives and Collections," "Typed Models"), expands ToolResult field documentation with detailed examples, clarifies error handling and output behavior, updates output schema sections, and emphasizes ToolResult's role in controlling content, structured_content, and metadata.
Example Code Enhancement examples/tool_result_echo.py	Adds metadata tracking including execution time, character count, and word count; introduces length: int field to EchoData dataclass; populates structured_content with enhanced EchoData instance and enriches meta field in ToolResult with computed metrics.

Poem

🐰 With content, structure, and metadata so bright,
Our documentation now feels just right,
Examples echo with timing in hand,
ToolResults dancing across the land! ✨

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch meta-docs

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c18782f and 8a9034c.

📒 Files selected for processing (2)

• docs/servers/tools.mdx (4 hunks)
• examples/tool_result_echo.py (2 hunks)

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}