Post an update

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive mutation. The description adds the key behavioral fact beyond that: the post appears as a reply on the original feedback thread, so the reporter is the audience. It omits retry/duplication behavior, which matters for a non-idempotent write, so it falls short of a 5.

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?

Three short sentences, front-loaded with the purpose, followed by effect and timing. The audience rationale is stated twice (description plus schema), a minor redundancy that doesn't meaningfully bloat it.

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 simple write tool with full schema coverage and no output schema, this covers what an agent needs: what to write, where it lands, and when to invoke it. The remaining gap is idempotency/duplicate-post risk, which an agent should know before retrying.

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 100%, so every parameter is already documented including 'itemId from list_items' and the mentions formatting convention. The description only echoes the body content already in the schema, adding no syntax or constraint detail beyond it, which is the baseline case.

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 ('report back on an item') and enumerates the content types it accepts (findings, changes, PR link). It implicitly distinguishes itself from siblings like set_status or create_item by framing itself as a report/reply rather than a state change, though it never names those siblings.

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?

'Use this when you finish work on an item, and when you get stuck' gives clear triggering conditions, including a non-obvious one (blocked state). It does not state exclusions, e.g., whether status changes belong here or in set_status.

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