Draft incident update

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

The annotations already state this is a non-read-only, non-destructive, idempotent operation, and the description adds meaningful context: it saves only a draft, returns an approval link, does not publish publicly, and requires write access. The request_id retry guidance further clarifies idempotent behavior beyond the annotation. There is no contradiction with the annotations.

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?

The description is five short, front-loaded sentences with no wasted language. The core action, draft-only behavior, incident id source, retry guidance, and access requirement are all stated efficiently.

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?

Given the annotations, complete schema coverage, and the presence of an output schema, the description covers what an agent needs in order to call the tool correctly. It explains the draft-only safety property, auth requirement, id source, and retry semantics.

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 schema already documents all four parameters, establishing a baseline of 3. The description adds useful meaning by explaining where the incident id comes from and how request_id supports safe retries, though it does not discuss the optional state parameter beyond what the schema says.

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?

The description uses a specific verb and resource: saving a plain-text incident note as a draft. It clarifies that this does not publish and that the output is an approval link, distinguishing it from any publish action. It also points to get_incidents for the required incident id.

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?

It gives clear prerequisites: obtain the incident id from get_incidents and use request_id for safe retries. It also explains the draft will not appear publicly until a builder publishes it, implicitly defining the boundary against publishing. However, it does not explicitly enumerate alternatives or when-not-to-use cases beyond that boundary.

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