read_run_progress

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

Annotations already declare readOnly/idempotent/non-destructive/non-open-world, but the description adds real behavior beyond them: it does not invoke the SDK, does not reconnect, does not block on timeout convergence, caps events at 200, and warns that the snapshot is not liveness evidence. This is exactly the kind of consequence-level 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?

A single dense clause front-loads the purpose, then the operational exclusions, then the routing caveat — no filler and nothing repeated from the name or schema. Sized appropriately for a two-parameter read tool.

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 low-complexity read tool with no output schema and strong annotations, the description covers behavior and the liveness caveat well, and loosely characterizes what comes back (state plus bounded events). The remaining gap is the absence of any parameter guidance, which is the one thing an agent still needs to call 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 description coverage is 0%, so the description must explain the two parameters, and it does not: neither relayRunId's meaning/format nor afterSequence's role as an incremental-event cursor is described. The phrase about 'up to 200 incremental events' hints at incremental semantics but never connects it to afterSequence, leaving the agent to guess how to page.

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-resource pair (read-only retrieval of a run's persisted state) and bounds the payload explicitly ('up to the most recent 200 incremental events'). It also differentiates itself from the sibling wait_run by stating that live monitoring belongs to that tool rather than this one.

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 an explicit when-not rule ('the snapshot is not proof the task is alive; for actual monitoring use wait_run') and names the alternative tool, so an agent can route between a point-in-time snapshot and a blocking wait without inference. It additionally rules out side effects (no SDK call, no reconnect, no timeout convergence).

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