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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds genuinely new behavior by mapping each status value to a different return shape (full transcript, error message, or bare in-progress status) and prescribing a polling cadence. It also flags a real cost trait (per-word data is ~17 KB per minute of audio). It stops short of noting rate limits in explicit terms or auth requirements, so it is strong but not exhaustive.

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, front-loaded with the core fetch behavior and the status contract, then polling instructions, then the optional-parameter caveat. A small amount of the include_words sentence restates schema text, but nothing is wasted at the level of an agent's decision.

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 carries the full burden of explaining return values — and it does so by enumerating the status-conditioned shapes. Combined with the polling protocol and the size caveat on include_words, an agent has everything needed to call and interpret this tool 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 100%, so the baseline is 3, but the description reinforces include_words with task-level context ('word-level tasks such as subtitles') and where the words land in the response depending on speaker_labels. Some of this duplicates the schema's own parameter description, which keeps it from a 5.

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 ('Fetch the current state of a transcript by id') and implicitly distinguishes itself from the mutating siblings submit_transcript and delete_transcript by framing itself as a read/poll operation. An agent can tell immediately which sibling to call for retrieval versus submission or deletion.

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 timing guidance ('Poll this tool every ~3 seconds after submit_transcript until you see completed or error'), which names the prerequisite sibling and the termination condition. It also gives a conditional exclusion for include_words ('only for word-level tasks such as subtitles'), covering both when to use and when not to.

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