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

Annotations only declare read-only/non-destructive/non-open-world; the description adds substantial behavioral context beyond that — the polling contract, the 'next_after' cursor reuse, what each terminal state means, the HTTP 402 rejection case, and that a stream error does not imply the server-side run stopped. That is exactly the extra context the annotations do not 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?

Front-loaded with purpose and usage, then the return/terminal-state detail. Dense and every sentence carries information, though the enumerated return-field breakdown is somewhat long and partially overlaps the declared output schema.

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 an async polling tool with 8 possible run_status values and three distinct terminal outcomes, the description covers the full state machine, error handling, and recovery path. Since an output schema exists, the return-value detail is a bonus rather than a necessity, and nothing an agent needs to poll correctly is missing.

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 both parameters are already documented, but the description adds real meaning: session_key's provenance and non-secret nature, and the semantics of the 'after' cursor (taken from 'next_after' on the previous check, 0 on the first). It goes modestly beyond the schema text rather than merely restating it.

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 ('check the progress and final status of a specific AI development session using its session key') and names the sibling it must not be confused with (dreamagent_get_edit_progress) plus where the key originates (dreamagent_chat / dreamagent_list_sessions). An agent can distinguish this from cancel_chat, chat, and get_edit_progress without opening any 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 when-to-use ('monitor an asynchronous edit until it completes, fails, or is cancelled — keep checking until a terminal state') and routes to the alternative for the ambiguous stream-error case ('verify with dreamagent_get_edit_progress'). It also clarifies the session key is an identifier, not a secret, removing a likely agent hesitation.

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