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

Annotations already convey destructive and non-read-only behavior. The description adds meaningful information beyond annotations by disclosing per-item outcomes and partial failures, which is not obvious from the schema. The idempotency_key retry instruction reinforces the idempotentHint annotation without contradicting it.

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 focused sentences with no filler. The core scope and constraint are front-loaded, followed by result behavior and retry instructions. Every sentence contributes necessary information.

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 mutation tool with an output schema, the description covers the key operational guardrails: explicit item identification, the 100-item limit, partial-failure reporting, and idempotent retries. Field-level details and authorized project behavior are left to the schema, which is appropriate. Nothing essential for correct invocation 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?

The schema already documents both top-level parameters. The description summarizes which fields can be changed and restates the 100-item cap and idempotency behavior, but most of this is already present in the schema. It adds limited semantic value beyond a useful field-level summary.

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 action ('Apply status, priority, tags, visibility, or archive changes') on a clearly bounded resource ('at most 100 explicitly identified feedback items'). The bulk scope and field list distinguish it from single-item siblings like update_comment and update_comment_status.

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?

Describes the appropriate context: when you have up to 100 explicitly identified feedback items and need to apply one or more field changes. It also gives retry guidance for idempotency_key. It does not explicitly exclude alternatives or say 'use update_comment for a single item,' but the usage context is clear.

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