davinci-mcp

Overview Schema Source Related Servers Discussions Admin

Job Cancel

job_cancel

Destructive

Stop a running job and return its state as cancelled. If the operation cannot be interrupted, it returns WRONG_STATE and leaves the job running; completed jobs are unchanged.

Instructions

Stop a running job and return its state ("cancelled").

A job whose operation cannot be interrupted returns WRONG_STATE and keeps running; a finished job is returned unchanged. Check it first with job_status if unsure.

Input Schema

Name	Required	Description	Default
`job_id`	Yes	Id from a write that returned status='started' (or job_list).

Output Schema

Name	Required	Description	Default
`id`	Yes
`kind`	Yes
`error`	No
`label`	Yes
`state`	Yes
`result`	No
`progress`	No
`started_at`	Yes
`finished_at`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.0.4Nov 1, 2026
- addedInput schema / properties / job_id / description
```
Added value: +"Id from a write that returned status='started' (or job_list)."
```
First observedv0.1.0Nov 1, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the structural hint of being destructive, the description provides complex behavioral logic: it specifies that operations that cannot be interrupted will return WRONG_STATE, and that already finished jobs will not change state. This level of operational detail is not in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is detailed, which is necessary given the complexity of the tool's behavior. While slightly verbose, every sentence serves to clarify a specific state transition or dependency and is well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers all critical operational context, including pre-conditions (check status first), success paths, and various defined failure/limitation paths (unchanged, WRONG_STATE). It is complete without needing an explicit output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

While schema coverage is 100%, the description adds vital semantic context for the 'job_id' by specifying that it must originate from a prior successful 'write' or a 'job_list' call, which is crucial for agent lifecycle management.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The purpose is stated clearly using a specific verb ('Stop') applied to a specific resource ('a running job'). It immediately distinguishes itself from siblings like job_status by defining it as a destructive action (cancel).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance by advising the user to check job_status first if they are unsure about the job's current state. It also covers failure cases, noting that finished jobs will be returned unchanged and non-interruptible jobs will return WRONG_STATE.

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