Delete Control

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It explicitly states that the operation is destructive/mutating, that it is a soft delete rather than a permanent erase, and that it can block with HTTP 409 under a specific coverage condition. This is substantial and goes well beyond a generic description, though it stops short of covering permissions or reversibility details.

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 front-loaded: the first sentence states the core action, the second clarifies destructiveness, and the third explains the blocking condition and required remedy. Every sentence contributes necessary operational information with no filler.

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?

Given the tool's moderate complexity and the presence of an output schema, the description covers the essential operational context: what the operation does, its side effects, and the key failure mode. It does not explain server_version semantics or mention any other restrictions, but the core invocation context is sufficiently complete for an agent to use the tool 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 75%, so the schema already documents most parameters. The description adds context about the justification being optional and about the 409 condition, but it does not add meaningful detail for model_id, control_id, or server_version beyond what the schema provides. This is adequate given the high schema coverage.

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 opens with a specific verb and resource: 'Soft-delete a security control,' which immediately distinguishes this from other control-related tools. It also clarifies the semantic nuance ('retired, not permanently erased'), removing ambiguity about the lifecycle impact. This clearly separates it from hard-delete or update operations.

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 provides clear context for when the tool will succeed or fail, including the HTTP 409 blocking condition and the prerequisite to add a replacement control or refine the threat model. It does not explicitly name alternative sibling tools or state when not to use the tool, but the practical guidance is strong enough to guide invocation correctly.

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