post_incident_update

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

Annotations only give the safety profile (readOnly=false, destructive=false, idempotent=false). The description adds genuinely non-obvious side effects: a resolved status closes the incident, public updates appear on status pages and are emailed to subscribers, and internal updates stay team-only. Those downstream notification effects are exactly what an agent needs and are not derivable from the annotations or schema.

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?

Two sentences, no waste, and the core action is front-loaded before the two conditional semantics (resolved, visibility). Every clause earns its place by changing how an agent would call the tool.

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 6-parameter mutation tool with no output schema, the description covers the highest-risk behaviors (incident closing, public email/status-page broadcast). It leaves minor gaps such as idempotency expectations and how the body is rendered, but nothing that would cause a clearly wrong invocation.

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 50%, so the description must carry weight, and it does for the two most consequential fields: it explains that status=resolved closes the incident and that visibility defaults to public with distinct distribution consequences. It adds nothing about id, body, project, or workspace, but those are either self-evident or covered by inline schema descriptions.

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 ('Post a status update on an incident'), which is clearer than the bare tool name and separates it from a generic incident mutation. It does not explicitly contrast itself with close siblings like update_incident or acknowledge_incident, so an agent still has to infer the boundary.

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?

Usage is implied through the effect descriptions ('status resolved closes it and must be public') and the default visibility behavior, which tells the agent what a call will do in a given case. However, there is no explicit when-to-use-this-vs-alternatives guidance against update_incident or acknowledge_incident, and no stated prerequisites or permissions.

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