cancel_compaction

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

Annotations already indicate the operation is not read-only and not flagged as destructive, but the description adds important behavioral context: only pending dispatches are affected, and sent requests are irreversible. This goes beyond the structured annotations and helps the agent set accurate expectations about side effects.

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?

Two tightly written sentences with the core action, the critical caveat, and a follow-up instruction. No filler or redundant restatement; the most important scoping information is front-loaded.

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 cancellation tool with two required parameters, no output schema, and clear annotations, the description covers the essential behavior, the limitation about already-sent requests, and the recommended next step of inspecting status. It omits failure modes or return-value details, but these are not critical for correct invocation here.

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?

The schema documents threadId but leaves jobId without a description, so schema coverage is only 50%. The description compensates slightly by saying 'exact job ID,' which reinforces that jobId must precisely identify the target, but it does not add meaningful semantics for threadId or go beyond what the schema already provides.

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 uses a specific verb ('Cancel') and names a precise resource ('pending compaction/continuation dispatches') while scoping it to an exact job ID. This clearly differentiates it from sibling tools like schedule_compaction, probe_compaction, and compaction_status without needing to infer from the tool name alone.

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 clearly signals this tool is for canceling pending dispatches and explicitly warns that already sent requests cannot be undone, which defines the boundary of when it is effective. It also advises inspecting status afterward, which implies a follow-up with a status tool, though it does not explicitly name alternatives or provide a when-not-to-use condition.

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