docs(result): fix ImageData/Path spec mismatch, clarify metadata boundary

[senamakel]

Summary

Small follow-up to #10, landing two review findings that came in on that PR's
head after it merged (from CodeRabbit/tinysweeper re-review of the last
pushed commit), plus one pre-existing unrelated test fix that was on the
branch at merge time:

• docs/specs/tinytools-vocabulary.md: the new "rich results" section said
  both ImageData and FileData support Base64/Url/Path, but
  ImageData only has Base64/Url — Path is FileData-only. Fixed the
  spec to match the actual enum.
• crates/tinytools/src/result/types.rs: clarified ToolResult::metadata's
  doc comment to be explicit that it round-trips through Serialize/
  Deserialize like every other field (so a host can persist the whole
  ToolResult to a transcript/RPC reply/JSONL record), and that "never shown
  to the model" refers specifically to the model-facing rendering methods
  (text()/output()/output_for_llm()) — a caller that instead serializes
  the whole struct for a model-facing message will still include it. This is
  documentation only; no behavior change, since stripping the field from
  Serialize itself would break the documented host-persistence use case.
• fix(result): handle empty string in from_str for Result — an
  already-committed, unrelated small test fix that was on the
  runtime-comparison branch when Rich ToolResult: follow-up content, metadata, control hints, replay class (tinyagents#171) #10 merged.

Behavior changes

None. Both substantive changes are documentation/spec accuracy fixes.

Validation

• cargo fmt --all -- --check
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test --all-features
• RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features -p tinytools

All pass locally.

[coderabbitai]

Warning

Review limit reached

• Run on-demand review

_{This review includes 2 billable files and costs up to $0.50.}

Or wait 22 minutes for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: d84c0cbf-52e3-4fc5-b3d4-dc636ce2cb83

📥 Commits

Reviewing files that changed from the base of the PR and between 24e17cb and 611bd22.

📒 Files selected for processing (2)

• crates/tinytools/src/result/types.rs
• docs/specs/tinytools-vocabulary.md

---

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

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-20T07:54:34.451030Z	611bd22	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[tinysweeper]

Tiny Sweeper review

Tiny Sweeper reviewed this change across 6 lane(s) and found 0 active actionable finding(s). Detailed lane evidence and any incomplete work are listed below.

State: Ready for maintainer review
Priority: none
Reviewed head: 611bd2246fdd
Updated: 1789891325 (Unix time)

Review snapshot

Change surface	Files	Review signal	Count
Production	1	Active findings	0
Tests	0	Noted findings	0
Documentation	1	Resolved findings	0
Configuration	0	Pending checks/questions	0

Completeness: Complete
Test assessment: No supported feature-to-test mapping was available; this does not mean tests are absent or passed.

What changed

The review could not produce a supported behavioral summary; inspect the cited changed surface and lane details below.

Features

None identified with supported citations.

Tests

No supported feature-to-test mapping was produced. Test execution is not inferred.

Findings

No active actionable findings.

Before merge

None.

How this fits together

flowchart LR
  n0["success"]:::impacted
  n1["success_with_markdown"]:::impacted
  n2["...lls_back_when_markdown_is_absent_or_blank"]:::impacted
  n3["result_is_pinned_to_its_literal_wire_shape"]:::impacted
  n4["result_round_trips_through_json"]:::impacted
  n2 -->|calls| n0
  n2 -->|tests| n0
  n3 -->|calls| n1
  n3 -->|tests| n1
  n4 -->|calls| n0
  n4 -->|tests| n0
  classDef changed fill:#0d4429,stroke:#238636,color:#e6edf3
  classDef impacted fill:#161b22,stroke:#6e7681,color:#c9d1d9
  classDef flagged fill:#5a1e02,stroke:#d93f0b,color:#ffffff
  classDef blocking fill:#67060c,stroke:#f85149,color:#ffffff

Loading

Agent review details

critique

• Conclusion: Success
• Scope reviewed: all assigned evidence
• Lane summary: Reviewed 2 files; 0 findings. _The code index is behind this pull request (indexed at `d2d0a89e2c6b`), so retrieved context may be out of date._ _Memory was unavailable (model: cortex: v1/recall: timed out after 10s), so this review ran without it._

security

• Conclusion: Success
• Scope reviewed: all assigned evidence
• Lane summary: The change clarifies that metadata is excluded from model-facing renderers while preserving complete-result serialization for host persistence. It looks safe to merge. 1 file was not security-reviewed: docs/specs/tinytools-vocabulary.md (prose or tabular data). _The code index is behind this pull request (indexed at `d2d0a89e2c6b`), so retrieved context may be out of date._ _Memory was unavailable (model: cortex: v1/recall: timed out after 10s), so this review ran without it._

tests

• Conclusion: Success
• Scope reviewed: all assigned evidence
• Lane summary: This pull request only improves documentation: the `metadata` field comment now clarifies it is excluded from model-facing rendering, and the spec doc rephrases `ImageData`/`FileData` support. No behavioural change, so no new test is needed. Safe to merge. _The code index is behind this pull request (indexed at `d2d0a89e2c6b`), so retrieved context may be out of date._ _Memory was unavailable (model: cortex: v1/recall: timed out after 10s), so this review ran without it._

commits

• Conclusion: Neutral
• Scope reviewed: all assigned evidence
• Lane summary: Nothing sensitive found in what this pull request commits.

description

• Conclusion: Success
• Scope reviewed: all assigned evidence
• Lane summary: Two documentation fixes: corrects the spec to match that `ImageData` only supports `Base64`/`Url` (not `Path`), and clarifies the `metadata` field's doc comment about round-tripping and not being included in model-facing rendering. No behavior changes; all checks pass. Safe to merge. _The code index is behind this pull request (indexed at `d2d0a89e2c6b`), so retrieved context may be out of date._ _Memory was unavailable (model: cortex: v1/recall: timed out after 10s), so this review ran without it._

e2e

• Conclusion: Neutral
• Scope reviewed: all assigned evidence
• Lane summary: No end-to-end harness in this repository: no e2e test files and no e2e workflow.

Evidence and run details

• Models: ladder/vectors, gpt-5.6-luna, deepseek/deepseek-v4-flash
• Spend: $0.004624
• Tokens: 68459 input · 3028 output · 12220 cached · 190 embedding

Head	State	Pass summary
611bd2246fdd	ready for maintainer review	0 active finding(s), 0 resolved finding(s) (at 1789891325)

[tinysweeper]

tinysweeper found nothing blocking. Approving.

             $0.0046 · 68,459 in / 3,028 out · 12,220 cached (18%) · ladder/vectors, gpt-5.6-luna, deepseek/deepseek-v4-flash · 190 embedded
critique:    $0.0022 · 38,210 in / 730 out   · 6,084 cached (16%)  · gpt-5.6-luna
security:    $0.0006 · 11,614 in / 85 out    · 1,784 cached (15%)  · gpt-5.6-luna
tests:       $0.0011 · 12,525 in / 364 out   · 1,280 cached (10%)  · deepseek/deepseek-v4-flash
description: $0.0004 · 4,030 in  / 522 out   · 1,280 cached (32%)  · deepseek/deepseek-v4-flash