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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to restate safety. Instead it adds real operational context beyond them: exactly what is destroyed (scans, dataLayer decisions), the recovered resource (quota slot), the permission requirement, the concurrency contract (If-Match via etag), and the specific error-to-action mapping (409 scan_in_progress, precondition_failed → re-fetch and retry).

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?

Front-loaded with the verb and permission, then consequences, then edge cases — good ordering with almost no waste. The final sentence runs on slightly ('If-Match: pass the etag of your last get_journey; on precondition_failed call get_journey again and retry'), which costs a little crispness.

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 destructive two-parameter mutation with no output schema, the description covers permissions, cascade effects, blocking states, and retry behavior — essentially everything needed to call it correctly. It omits behavior for a nonexistent/already-deleted id, which matters given idempotentHint=true.

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 baseline is 3, but the description adds semantics the schema lacks: etag is a concurrency token that must come from the last get_journey, and what to do when the precondition fails. That turns a documented field into an actionable protocol.

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?

States a specific verb and resource ('Delete a journey') and immediately scopes the blast radius ('with its scans on its own test and its dataLayer decisions; this frees its quota slot'). That distinguishes it clearly from siblings like patch_journey, replace_journey, delete_target and cancel_scan.

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?

Gives concrete preconditions for use: requires edit permission, requires the etag from a prior get_journey, and specifies a retry loop (call get_journey again on precondition_failed). It also states the blocking condition (active scan → 409 scan_in_progress). It does not name alternative siblings for non-destructive intent, but the delete context is unambiguous.

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