Read a transcript export

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

Annotations only cover safety (readOnly, idempotent, non-destructive, closed-world); the description adds genuinely new behavior: fragments must be concatenated exactly then JSON-decoded, pagination must proceed until complete=true, and a version change actively refuses continuation rather than splicing transcripts. The authorization caveat ("URI manifests are not authorization; each read uses current Coval access") discloses a precondition the agent could not infer from structured fields.

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?

Five short, front-loaded sentences with no filler; the use condition leads and the protocol follows. The instruction to concatenate then JSON-decode is procedural guidance to the caller rather than tool behavior, which is defensible but slightly stretches what belongs here.

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 4-parameter tool with no output schema and no parameter descriptions, the definition explains the pagination/versioning protocol but leaves the uri input format and max_chars truncation behavior unaddressed. An agent still has to guess how large max_chars should be and what uri values are valid.

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 0% across 4 parameters, so the description carries the burden and only partly does: "next_offset" implies the offset continuation semantics and "returned version"/"changed version refuses continuation" explains expected_version. The uri parameter and max_chars are never explained, leaving half the schema opaque.

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 an authenticated transcript export") plus a qualifying condition ("when resource links are unavailable"), which separates it from the get_*/list_* siblings that fetch resources directly. It stops short of naming an actual alternative tool, so differentiation is contextual rather than explicit.

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?

The triggering condition is explicit: use this when resource links are unavailable, i.e., as a fallback path. The continuation rule ("Continue with next_offset ... until complete=true") also tells the agent how to keep using it. No sibling tool is named as an alternative, though, so it is clear context without full routing.

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