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

readOnlyHint=true is consistent with a read tool, and the description adds a lot beyond it: row types, hidden flags set by remove_fillers, manual/silence rows having no words, page-based return, and an explicit error behavior ('Refuses a from_row past the last row, naming the row count'). That is exactly the behavioral context annotations cannot carry.

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?

Purpose is front-loaded and every sentence carries information about return shape or continuation. Some sentences are long run-ons (the words/from_word_index clause in particular) that could be split for faster scanning, which keeps it from a 5.

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?

There is no output schema, so the description bears the return-shape burden alone and does it thoroughly: field-by-field row anatomy, word arrays, hidden rows, and pagination. An agent can call this and interpret the response without further documentation.

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 100%, so baseline is 3, but the description earns more by explaining where from_row's value comes from (the reply's next_from_row) and by defining what word indexes mean relative to words[]. The project_id parameter is left to the schema, which is adequate given its 100% coverage.

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?

The first clause states a specific verb and resource: read caption rows, and immediately ties them to the ids that edit_caption, move_caption and cut_transcript_span consume. That framing distinguishes it from the sibling editing tools without requiring the agent to open 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?

It explains the practical use case (fetch row ids and word indices for downstream edits) and gives explicit continuation instructions: pass the reply's next_from_row as from_row. It does not name a when-not condition or an alternative transcript source, so it falls short of a 5.

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