Runtime comparison

crates/tinytools/src/result/types.rs

@@ -53,8 +53,17 @@ pub struct ToolResult {
     /// it reads this field directly and decides how to place it on the wire.
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub follow_up: Vec<ToolContent>,
-    /// Host-only metadata: never shown to the model, but available to the host
-    /// for events, persistence, or telemetry.
+    /// Host-only metadata: available to the host for events, persistence, or
+    /// telemetry, but never *included in the model-facing rendering*
+    /// ([`Self::text`], [`Self::output`], [`Self::output_for_llm`]).
+    ///
+    /// This field still round-trips through [`Serialize`]/[`Deserialize`],
+    /// the same as every other field, because that is what lets a host
+    /// persist the complete `ToolResult` to a transcript, RPC reply, or JSONL
+    /// session record. A host that builds a model-facing message must use
+    /// one of the rendering methods above (or otherwise construct the
+    /// message deliberately) rather than serializing this struct wholesale
+    /// and sending the JSON to the model, or it will leak this field.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub metadata: Option<serde_json::Value>,
     /// Loop-control hints a harness may honour, such as ending the loop

docs/specs/tinytools-vocabulary.md

@@ -149,8 +149,9 @@ this section specifies the additions below. All are additive to the wire shape
 see "Versioning" — so they shipped as a `0.2.0` → `0.3.0` minor bump.
 
 - **`ToolContent::Image` / `ToolContent::File`** extend the block-list result
-  with image and file blocks (`ImageData` / `FileData`, each `Base64`, `Url`,
-  or `Path`), alongside the existing `Text` and `Json` blocks.
+  with image and file blocks (`ImageData` supports `Base64` and `Url`, while
+  `FileData` also supports `Path`), alongside the existing `Text` and `Json`
+  blocks.
 - **`ToolResult::follow_up: Vec<ToolContent>`** carries content a caller should
   present to the model as a *separate* message after the tool result — a
   screenshot or document the next turn should read — rather than folding it