Permanently delete a completed, failed, or cancelled job along with its logs and artifacts. Cancel queued or running jobs and wait for a terminal state before deletion.
Permanently delete a completed, failed or cancelled job with its logs and artifacts.
Queued and running jobs are refused; cancel them and wait for a terminal state first.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's job is to add context — and it does: it names the collateral damage (logs and artifacts) and the permanence, which annotations cannot express. It also discloses a runtime refusal mode for non-terminal jobs, though it says nothing about behavior for a nonexistent or already-deleted job_id.
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 short sentences, zero filler, with the destructive effect front-loaded before the precondition. The line break between them is slightly odd for such short text but costs nothing.
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 one-parameter destructive tool with an output schema (so return values need no explanation), the description covers effect, permanence, and preconditions adequately. The remaining gap is error behavior outside the queued/running case, which an agent will only discover at call time.
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 single job_id parameter has 0% schema description coverage, so the schema contributes nothing and the description must carry the load. It only indirectly constrains the value (must reference a terminal-state job) and gives no format, source, or idempotency guidance — an agent must infer that IDs come from list_jobs or job_status.
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 (delete), resource (job), and effect scope (with its logs and artifacts), then narrows it to terminal jobs (completed/failed/cancelled). That state qualifier alone separates it from cancel_job and list_jobs without requiring the agent to open any 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?
Gives an explicit when-to-use (jobs in a terminal state) and an explicit when-not (queued/running jobs, which are refused), plus the correct alternative path: cancel them and wait for a terminal state. This is the full when/when-not/alternative triad.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.