Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: rows are indexed, both window fields null means whole-asset-by-index, and transcript rows are individual words rather than sentences. It does not discuss limits/errors, but that gap is minor given the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, all front-loaded and load-bearing: scope, window parameters, paging bounds, and the two routing warnings. Nothing is redundant with the title or padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter read tool with no output schema, the description covers windowing, paging, and the shape of transcript rows. It could better describe what a returned row looks like per kind (beats, track, scenes), since there is no output schema to fall back on, but an agent has enough to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 57%, and the description fills key gaps: it explains the startSeconds/durationSeconds interaction (both null = whole asset by row index), that offset 0 starts at the first row, and that limit 1-40 bounds rows per page. These clarify offset/limit, which have no schema descriptions, though the meaning of the tai enum values remains undocumented anywhere.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read stored analysis rows of an asset') and scopes it with the window/start semantics. It also names the sibling it is not (read_transcript for readable conversation) and points to film props for full data, so an agent can distinguish it from read_transcript and read_film without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit steer-away guidance: 'use read_transcript for readable conversation' and 'bind full data through film props, not these rows.' These are concrete alternatives and exclusions. It stops short of an explicit positive trigger for when raw rows are the right choice, so it is clear context rather than a full when/when-not map.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.