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

Annotations cover only the safety profile (readOnly, idempotent), and the description adds substantial behavior beyond them: the default OPEN filter, the counts object, the exact response fields, recording-item cardinality (one comment per recording), the Markdown #t=/#rt= link semantics, and an explicit untrusted-content warning keyed to author_is_team_member.

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 routing, then defaults, then response shape, then recording/Markdown details, then the security caveat — a sensible ordering where each block is doing work. It is dense and long-form for a list tool, and the #t=/#rt= explanation is somewhat reiterated via visual_references, but there is no filler.

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?

With no output schema, the description carries the return-shape burden itself and does so: version_id, container_id, title, per-item body/tags/status/author/timestamp/reply_count/posted_by_agent, plus the recording sub-object. For a 4-param read tool with rich nested returns, an agent has everything needed to call it and interpret results.

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 adds real semantics beyond the schema: that asset_id accepts either an asset id or a version id and that folder ids are rejected with a redirect. The status default and 'in-progress included under open' merely restate the schema enum.

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 ('List top-level feedback on an asset') and immediately disambiguates scope: asset id → current version, version id → that exact version, folder id → refused. It also explicitly routes away from siblings, naming recent_activity(folder_id) and feedback_get for reply threads.

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?

Explicit when-to-use and when-not rules are given: folder ids are rejected with a named alternative, default is OPEN-only with status=all to widen, and get_annotated_frames(id) should be called once per item that carries visuals. Nothing about tool selection is left to inference.

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