delete_assertion

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the operation is mutating and destructive, mentions the record is permanently removed (not soft-deleted), states the impact on sufficiency/verification, clarifies it does not re-run verification, and explains the 'own vs. inherited' constraint.

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 well-structured with a behavioral overview followed by usage guidance. Every sentence contributes unique value, and the text is front-loaded with the core action and safety warnings.

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 fully covers the tool's purpose, behavioral traits, usage scenarios, and constraints (ownership, inherited assertions, relationship to verification). Since an output schema exists, the omission of return-value details is acceptable.

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 80%, so most parameters are already described in the schema. The description adds no significant parameter-specific details beyond the existing schema descriptions; it does imply the mutual exclusivity of control_id and assumption_id but that is already evident from the schema's 'omit if' phrasing.

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 clearly states the tool 'permanently delete[s] a single assertion from a control or assumption,' using a specific verb and resource. It also distinguishes the action from related tools like submit_assertions and list_assertions by referencing them as alternatives.

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?

It explicitly specifies when to use the tool ('use to retract a claim that was submitted in error or that get_verification_report flagged as misaligned') and names alternatives for adding ('submit_assertions') and inspecting ('list_assertions'). It also provides an exclusion by noting inherited assertions must be managed on their source model.

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