workflow_waive_guard

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

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose that the waiver is recorded with approver and reason, and that the guard will show as 'waived' instead of 'fail' on subsequent checks. However, it omits other relevant behaviors like reversibility, permission requirements, or whether the transition proceeds automatically, so it provides only partial transparency.

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 compact and well-structured: a clear opening statement, a few behavioral details, then a bulleted Args list. Every sentence adds value, though the format could be slightly tightened without losing 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 4-parameter tool with no annotations and an output schema present, the description covers the core behavior, parameter semantics, and the effect on checks. The main gap is the ambiguous relationship with workflow_transition—whether the transition is automatically executed or only unblocked—but this is partially inferable from the tool name and siblings. Overall, an agent can likely use it correctly with the provided information.

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 description coverage is 0%, so the description must compensate. It does this effectively: guard is tied to workflow_check results, approver defines who approved, reason explains risk acceptance, and project_dir notes default to working directory. This adds real meaning beyond the raw schema types and required flags.

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 first line 'Waive a transition guard so the transition can proceed' uses a specific verb and resource, clearly distinguishing it from sibling tools like workflow_check (which checks) and workflow_transition (which performs the transition). The description is explicit about the action and its effect.

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 description implicitly places the tool after workflow_check results and before a transition, but it never explicitly states when to use it vs. alternatives or when not to use it. There is no direct comparison to workflow_item_waive or workflow_transition, leaving the selection decision partially to inference.

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