docs(rfd): clarify usage accounting placeholders

agent-client-protocol-schema/src/v1/agent.rs

@@ -3195,23 +3195,23 @@ pub enum StopReason {
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub struct Usage {
-    /// Sum of all token types across session.
+    /// Sum of all reported token categories according to the final accounting semantics.
     pub total_tokens: u64,
-    /// Total input tokens across all turns.
+    /// Input token count according to the final accounting semantics.
     pub input_tokens: u64,
-    /// Total output tokens across all turns.
+    /// Output token count according to the final accounting semantics.
     pub output_tokens: u64,
-    /// Total thought/reasoning tokens
+    /// Thought/reasoning token count, if reported by the agent.
     #[serde_as(deserialize_as = "DefaultOnError")]
     #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
     #[serde(default)]
     pub thought_tokens: Option<u64>,
-    /// Total cache read tokens.
+    /// Cache read token count, if reported by the agent.
     #[serde_as(deserialize_as = "DefaultOnError")]
     #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
     #[serde(default)]
     pub cached_read_tokens: Option<u64>,
-    /// Total cache write tokens.
+    /// Cache write token count, if reported by the agent.
     #[serde_as(deserialize_as = "DefaultOnError")]
     #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
     #[serde(default)]
@@ -3244,21 +3244,21 @@ impl Usage {
         }
     }
 
-    /// Total thought/reasoning tokens
+    /// Thought/reasoning token count, if reported by the agent.
     #[must_use]
     pub fn thought_tokens(mut self, thought_tokens: impl IntoOption<u64>) -> Self {
         self.thought_tokens = thought_tokens.into_option();
         self
     }
 
-    /// Total cache read tokens.
+    /// Cache read token count, if reported by the agent.
     #[must_use]
     pub fn cached_read_tokens(mut self, cached_read_tokens: impl IntoOption<u64>) -> Self {
         self.cached_read_tokens = cached_read_tokens.into_option();
         self
     }
 
-    /// Total cache write tokens.
+    /// Cache write token count, if reported by the agent.
     #[must_use]
     pub fn cached_write_tokens(mut self, cached_write_tokens: impl IntoOption<u64>) -> Self {
         self.cached_write_tokens = cached_write_tokens.into_option();

agent-client-protocol-schema/src/v2/agent.rs

@@ -3314,23 +3314,23 @@ pub enum StopReason {
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub struct Usage {
-    /// Sum of all token types across session.
+    /// Sum of all reported token categories according to the final accounting semantics.
     pub total_tokens: u64,
-    /// Total input tokens.
+    /// Input token count according to the final accounting semantics.
     pub input_tokens: u64,
-    /// Total output tokens.
+    /// Output token count according to the final accounting semantics.
     pub output_tokens: u64,
-    /// Total thought/reasoning tokens
+    /// Thought/reasoning token count, if reported by the agent.
     #[serde_as(deserialize_as = "DefaultOnError")]
     #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
     #[serde(default)]
     pub thought_tokens: Option<u64>,
-    /// Total cache read tokens.
+    /// Cache read token count, if reported by the agent.
     #[serde_as(deserialize_as = "DefaultOnError")]
     #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
     #[serde(default)]
     pub cached_read_tokens: Option<u64>,
-    /// Total cache write tokens.
+    /// Cache write token count, if reported by the agent.
     #[serde_as(deserialize_as = "DefaultOnError")]
     #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
     #[serde(default)]
@@ -3363,21 +3363,21 @@ impl Usage {
         }
     }
 
-    /// Total thought/reasoning tokens
+    /// Thought/reasoning token count, if reported by the agent.
     #[must_use]
     pub fn thought_tokens(mut self, thought_tokens: impl IntoOption<u64>) -> Self {
         self.thought_tokens = thought_tokens.into_option();
         self
     }
 
-    /// Total cache read tokens.
+    /// Cache read token count, if reported by the agent.
     #[must_use]
     pub fn cached_read_tokens(mut self, cached_read_tokens: impl IntoOption<u64>) -> Self {
         self.cached_read_tokens = cached_read_tokens.into_option();
         self
     }
 
-    /// Total cache write tokens.
+    /// Cache write token count, if reported by the agent.
     #[must_use]
     pub fn cached_write_tokens(mut self, cached_write_tokens: impl IntoOption<u64>) -> Self {
         self.cached_write_tokens = cached_write_tokens.into_option();

docs/protocol/v1/draft/schema.mdx

@@ -9006,37 +9006,37 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/d
 
 </ResponseField>
 <ResponseField name="cachedReadTokens" type={"integer | null"} >
-  Total cache read tokens.
+  Cache read token count, if reported by the agent.
 
     - Minimum: `0`
 
 </ResponseField>
 <ResponseField name="cachedWriteTokens" type={"integer | null"} >
-  Total cache write tokens.
+  Cache write token count, if reported by the agent.
 
     - Minimum: `0`
 
 </ResponseField>
 <ResponseField name="inputTokens" type={"uint64"} required>
-  Total input tokens across all turns.
+  Input token count according to the final accounting semantics.
 
     - Minimum: `0`
 
 </ResponseField>
 <ResponseField name="outputTokens" type={"uint64"} required>
-  Total output tokens across all turns.
+  Output token count according to the final accounting semantics.
 
     - Minimum: `0`
 
 </ResponseField>
 <ResponseField name="thoughtTokens" type={"integer | null"} >
-  Total thought/reasoning tokens
+  Thought/reasoning token count, if reported by the agent.
 
     - Minimum: `0`
 
 </ResponseField>
 <ResponseField name="totalTokens" type={"uint64"} required>
-  Sum of all token types across session.
+  Sum of all reported token categories according to the final accounting semantics.
 
     - Minimum: `0`
 

docs/protocol/v2/draft/schema.mdx

@@ -9709,37 +9709,37 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
 
 </ResponseField>
 <ResponseField name="cachedReadTokens" type={"integer | null"} >
-  Total cache read tokens.
+  Cache read token count, if reported by the agent.
 
     - Minimum: `0`
 
 </ResponseField>
 <ResponseField name="cachedWriteTokens" type={"integer | null"} >
-  Total cache write tokens.
+  Cache write token count, if reported by the agent.
 
     - Minimum: `0`
 
 </ResponseField>
 <ResponseField name="inputTokens" type={"uint64"} required>
-  Total input tokens.
+  Input token count according to the final accounting semantics.
 
     - Minimum: `0`
 
 </ResponseField>
 <ResponseField name="outputTokens" type={"uint64"} required>
-  Total output tokens.
+  Output token count according to the final accounting semantics.
 
     - Minimum: `0`
 
 </ResponseField>
 <ResponseField name="thoughtTokens" type={"integer | null"} >
-  Total thought/reasoning tokens
+  Thought/reasoning token count, if reported by the agent.
 
     - Minimum: `0`
 
 </ResponseField>
 <ResponseField name="totalTokens" type={"uint64"} required>
-  Sum of all token types across session.
+  Sum of all reported token categories according to the final accounting semantics.
 
     - Minimum: `0`
 

docs/rfds/end-turn-token-usage.mdx

@@ -83,7 +83,7 @@ This shape is not ready for Preview. The RFD should resolve the open design ques
 
 - `usage` (object, optional, nullable) - Token usage reported for the completed prompt turn
   - If `usage` is omitted or `null`, the agent is not reporting token usage for this turn.
-- `totalTokens` (number, required, non-null) - Total token count according to the final accounting semantics
+- `totalTokens` (number, required, non-null) - Sum of all reported token categories according to the final accounting semantics
 - `inputTokens` (number, required, non-null) - Input token count according to the final accounting semantics
 - `outputTokens` (number, required, non-null) - Output token count according to the final accounting semantics
 - `thoughtTokens` (number, optional, nullable) - Thought or reasoning tokens, if the model exposes them

schema/v1/schema.unstable.json

@@ -4372,39 +4372,39 @@
       "type": "object",
       "properties": {
         "totalTokens": {
-          "description": "Sum of all token types across session.",
+          "description": "Sum of all reported token categories according to the final accounting semantics.",
           "type": "integer",
           "format": "uint64",
           "minimum": 0
         },
         "inputTokens": {
-          "description": "Total input tokens across all turns.",
+          "description": "Input token count according to the final accounting semantics.",
           "type": "integer",
           "format": "uint64",
           "minimum": 0
         },
         "outputTokens": {
-          "description": "Total output tokens across all turns.",
+          "description": "Output token count according to the final accounting semantics.",
           "type": "integer",
           "format": "uint64",
           "minimum": 0
         },
         "thoughtTokens": {
-          "description": "Total thought/reasoning tokens",
+          "description": "Thought/reasoning token count, if reported by the agent.",
           "type": ["integer", "null"],
           "format": "uint64",
           "minimum": 0,
           "x-deserialize-default-on-error": true
         },
         "cachedReadTokens": {
-          "description": "Total cache read tokens.",
+          "description": "Cache read token count, if reported by the agent.",
           "type": ["integer", "null"],
           "format": "uint64",
           "minimum": 0,
           "x-deserialize-default-on-error": true
         },
         "cachedWriteTokens": {
-          "description": "Total cache write tokens.",
+          "description": "Cache write token count, if reported by the agent.",
           "type": ["integer", "null"],
           "format": "uint64",
           "minimum": 0,

schema/v2/schema.unstable.json

@@ -6432,39 +6432,39 @@
       "type": "object",
       "properties": {
         "totalTokens": {
-          "description": "Sum of all token types across session.",
+          "description": "Sum of all reported token categories according to the final accounting semantics.",
           "type": "integer",
           "format": "uint64",
           "minimum": 0
         },
         "inputTokens": {
-          "description": "Total input tokens.",
+          "description": "Input token count according to the final accounting semantics.",
           "type": "integer",
           "format": "uint64",
           "minimum": 0
         },
         "outputTokens": {
-          "description": "Total output tokens.",
+          "description": "Output token count according to the final accounting semantics.",
           "type": "integer",
           "format": "uint64",
           "minimum": 0
         },
         "thoughtTokens": {
-          "description": "Total thought/reasoning tokens",
+          "description": "Thought/reasoning token count, if reported by the agent.",
           "type": ["integer", "null"],
           "format": "uint64",
           "minimum": 0,
           "x-deserialize-default-on-error": true
         },
         "cachedReadTokens": {
-          "description": "Total cache read tokens.",
+          "description": "Cache read token count, if reported by the agent.",
           "type": ["integer", "null"],
           "format": "uint64",
           "minimum": 0,
           "x-deserialize-default-on-error": true
         },
         "cachedWriteTokens": {
-          "description": "Total cache write tokens.",
+          "description": "Cache write token count, if reported by the agent.",
           "type": ["integer", "null"],
           "format": "uint64",
           "minimum": 0,