sassy_shell_confirm

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

Annotations declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false; the description's 'Mutating:' prefix aligns with those. Beyond annotations it adds rich behavioral context: single-use tokens, 60-second expiry, binding to exact command/shell/cwd with replay rejection, the HIGH-tier confirm_phrase requirement, and audit logging as pattern_confirm_executed. This materially exceeds what the annotations alone convey, with no contradiction.

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 longer than average, but every sentence carries essential security-relevant information: mutation nature, flow position, token expiry, binding, replay rejection, phrase requirement, and audit logging. It is front-loaded with the purpose ('Mutating: executes...') before diving into constraints. The length is justified for a security-critical mutation tool; little is waste.

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 complex, security-sensitive tool, the description covers purpose, mutation behavior, token lifecycle, binding, replay protection, phrase rules, audit trail, and usage constraints. An output schema exists, so return-value documentation is handled elsewhere. The only minor gap is not explicitly naming the sibling first-step tool, but the flow is clear enough that an agent can execute correctly.

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 carry the semantic load — and it does. It explains that token is single-use, expires after 60 seconds, and is bound to the originating command/shell/cwd (hence replay-safe), and that confirm_phrase is required only for HIGH-tier commands and must match the phrase from the original response. Both parameters get meaningful semantics the bare schema lacks.

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 names a precise verb+resource combination — 'executes a sassy_shell command that was returned as confirmation_required' — and situates it as the second step of a two-phase confirm flow. This clearly distinguishes it from the sibling sassy_shell tool that initiates commands, so an agent can differentiate them without inspecting either schema.

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 constrains usage: 'Use it only as the second step of the confirm flow; it cannot start a command on its own.' This is a clear when-to-use/when-not-to-use directive. It names the trigger condition (commands returned as confirmation_required because interceptor.destructiveAction='confirm') though it does not explicitly name the sibling tool for the first step, leaving the alternative slightly implicit.

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