diff --git a/packages/ai/src/schemas.ts b/packages/ai/src/schemas.ts
index 416202396..74c75a2bf 100644
--- a/packages/ai/src/schemas.ts
+++ b/packages/ai/src/schemas.ts
@@ -17,16 +17,20 @@ export const ModelThinkingLevelSchema = Type.Union([Type.Literal("off"), Thinkin
 export const TextContentSchema = StrictObject({
 	type: Type.Literal("text"),
 	text: Type.String(),
-	/** Provider message metadata, such as an OpenAI response item identifier. */
+	/** OpenAI response message metadata, as either a legacy identifier or `TextSignatureV1` JSON. */
 	textSignature: Type.Optional(Type.String()),
 });
 
 export const ThinkingContentSchema = StrictObject({
 	type: Type.Literal("thinking"),
 	thinking: Type.String(),
-	/** Opaque provider reasoning identifier or encrypted payload used for multi-turn continuity. */
+	/** Provider reasoning item identifier. */
 	thinkingSignature: Type.Optional(Type.String()),
-	/** Whether safety filters redacted the thinking content. */
+	/**
+	 * When true, the thinking content was redacted by safety filters. The opaque
+	 * encrypted payload is stored in `thinkingSignature` so it can be passed back
+	 * to the API for multi-turn continuity.
+	 */
 	redacted: Type.Optional(Type.Boolean()),
 });
 
@@ -34,6 +38,7 @@ export const ImageContentSchema = StrictObject({
 	type: Type.Literal("image"),
 	/** Base64-encoded image data. */
 	data: Type.String(),
+	/** Image media type, for example `image/jpeg` or `image/png`. */
 	mimeType: Type.String({ minLength: 1 }),
 });
 
@@ -51,9 +56,13 @@ export const UsageSchema = StrictObject({
 	output: Type.Integer({ minimum: 0 }),
 	cacheRead: Type.Integer({ minimum: 0 }),
 	cacheWrite: Type.Integer({ minimum: 0 }),
-	/** Subset of cacheWrite written with one-hour retention. */
+	/** Subset of `cacheWrite` written with 1h retention. Only Anthropic reports this split. */
 	cacheWrite1h: Type.Optional(Type.Integer({ minimum: 0 })),
-	/** Provider-reported reasoning tokens, already included in output. */
+	/**
+	 * Reasoning/thinking tokens, when the provider reports them. This is a subset of
+	 * `output`: `output` already includes these tokens. Set to a number (possibly 0) by
+	 * providers that expose a reasoning breakdown; left undefined by providers that don't.
+	 */
 	reasoning: Type.Optional(Type.Integer({ minimum: 0 })),
 	totalTokens: Type.Integer({ minimum: 0 }),
 	cost: StrictObject({
@@ -75,8 +84,12 @@ export const StopReasonSchema = Type.Union([
 ]);
 
 export const ModelCostRatesSchema = StrictObject({
+	/** US dollars per million input tokens. */
 	input: Type.Number({ minimum: 0 }),
+	/** US dollars per million output tokens. */
 	output: Type.Number({ minimum: 0 }),
+	/** US dollars per million cache-read tokens. */
 	cacheRead: Type.Number({ minimum: 0 }),
+	/** US dollars per million cache-write tokens. */
 	cacheWrite: Type.Number({ minimum: 0 }),
 });