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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), it discloses non-obvious constraints: visibility to project members, markdown with a 1–10,000 character bound, 'only allowed on your own change', 'one live note per change', and that API tokens can only add free comments. The requestId retry semantics ('reusing it only for retries of the same call') directly explain the idempotentHint in operational terms.

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 the purpose, then progressively narrows to the changeId branching and requestId note — every clause carries information. It is a single dense paragraph, however, and the changeId rules would scan better as separate clauses rather than one long run-on sentence.

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 5-parameter mutation with no annotations on permissions and no output schema, the description covers visibility, validation bounds, eligibility, token behavior, and idempotency thoroughly. The only gap is that it never indicates what is returned (e.g., the new comment id) for a tool that creates a resource.

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?

With 0% schema description coverage, the description carries the full burden and does well: body format and length, changeId origin ('a triage:… or resolution:… id from get_error_group') and its eligibility rules, and requestId UUID freshness/retry semantics. projectId and groupId are left unexplained, presumably because their names and UUID formats are self-evident.

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 ('Add an internal team comment to an error group') and immediately clarifies visibility scope ('internal team notes, visible to project members only'), which cleanly separates it from the ticket-comment siblings. An agent can tell this acts on error groups, not tickets, without opening the 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 branching conditions: 'Without changeId it is a free comment' versus 'With changeId … it is the note explaining that status change', plus the token-based exclusion ('API tokens never make status changes'). It stops short of naming sibling alternatives like update_error_comment or delete_error_comment, so it is clear context rather than full alternative routing.

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