interrupt

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

With no annotations, the description carries the full burden and does so: it explains the signal semantics, that state survives, that SIGINT can never kill the kernel, the exact force escalation sequence (graceful shutdown, SIGTERM, SIGKILL), the loss of every session's variables, and the failure-path guarantee that state files are kept and the pid reported. This is unusually complete behavioral disclosure for a mutation-capable tool.

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 primary action is front-loaded in the first clause, and nearly every clause adds distinct information (effects, refusals, escalation, failure path). The single dense paragraph with multiple em-dash clauses is information-rich but slightly harder to scan than a broken-out structure would be.

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 tool with no output schema and no annotations, the description covers the success path, the idle and cross-client edge cases, the forced escalation path, and what happens on signal failure. Nothing an agent needs to call this correctly is missing.

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 100%, and the schema already defines force as stopping the kernel with all state lost. The description goes further by giving the escalation rationale for force=true and the precise consequence (losing every session's variables), which is real added meaning rather than restatement. It stops short of documenting the default value or any other input nuance, so it is strong but not exhaustive.

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 the specific action (SIGINT the running computation) with its precise effect (job fails with KeyboardInterrupt, session keeps state), and explicitly contrasts it with the force variant that stops the kernel. An agent can distinguish this from run_file, poll, status, reset, drop, and exec without opening 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?

Explicitly names the primary case ('the first thing to try for a runaway job') and the escalation case for force=true ('last resort... a computation that ignores SIGINT, e.g. a wedged C-level loop'). It also states two exclusion conditions -- refused when the job belongs to another MCP client, no-op when idle -- which is exactly the when/when-not guidance an agent needs.

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