discard_flow_draft

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

The annotations declare destructiveHint=false, yet the description says the draft is "thrown away" — the description usefully discloses that the draft content is lost while the live version survives, which the annotations do not convey. Remaining gaps: it does not say whether discarding a non-existent draft errors or no-ops (relevant given idempotentHint=false), nor whether confirmation is advisable. The tension with destructiveHint=false is mild and consistent with the common convention that discarding transient draft state is not a destructive update to live resources.

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: identity of the action first, the consequence and the preserved state second, the call mechanics last. Nothing is redundant and the most important fact (live version is untouched) is front-loaded.

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 one-parameter mutation with no output schema, the description covers what is affected, what is preserved, and how to form the call — annotations carry the rest of the safety profile. It lacks only failure/no-draft behavior, which is a minor omission at this complexity level.

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 single `id` parameter is already documented, and the baseline is 3. "Send {} as the body" adds the useful detail that no body payload is needed, but it sits awkwardly against a schema that marks `id` as required with additionalProperties=false, leaving the agent to infer that `id` travels in the path rather than the body.

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?

"Discard a flow draft" names a specific verb and resource, and "the live version stands" immediately separates it from the sibling delete_flow, which removes the whole flow. It stops short of naming delete_flow or update_flow explicitly, so the differentiation is implied rather than stated.

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?

The phrase "the unpublished draft" implies the precondition (an unpublished draft must exist) and implies when not to use it (when you want the live flow removed, use delete_flow). There is no explicit when/when-not statement or named alternative, so an agent must infer the routing.

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