revoke_decision

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 usefully reveals a non-obvious consequence: 'the decision is marked revoked in the log so future similarity checks ignore it.' However, it does not disclose whether revocation is reversible, whether it affects dependent decisions, or what permissions are required, leaving notable gaps for a mutating tool.

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 four short sentences, front-loads the purpose, and includes the core trigger conditions and side effect without any filler. Every sentence contributes meaning, and the project_root instruction is placed at the end as an actionable note.

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?

The description gives the essential purpose, usage trigger, key side effect, and a parameter instruction, which is enough to attempt a call. However, parameter semantics are incomplete, and the absence of annotations combined with no mention of reversibility or edge cases makes it only partially complete. The output schema presumably covers return values, so that gap is excused.

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 for the lack of parameter documentation. It clarifies project_root with 'Always pass project_root as the current working directory', but gives no explanation of decision_id or reason beyond their names. This leaves two of three parameters only implicitly defined.

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 states a specific action ('Revoke or supersede') on a specific resource ('a previously approved decision'), making the tool's core purpose immediately clear. It also differentiates from sibling tools like confirm_decision and query_decisions by focusing on undoing or overriding an existing decision rather than creating or reading one.

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 explicitly states when to use the tool: 'when a past decision was wrong, circumstances changed, or it conflicts with new requirements.' It does not mention when not to use it or name alternative tools, so it stops short of a 5, but the context is clear enough for an agent to select it in most situations.

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