Stop session

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

Annotations mark destructiveHint=true, and the description goes well beyond that by detailing exactly what happens: in-flight units are released with checkpoints, the session is classified as resumable/waiting_for_human/blocked/completed, and markFailed:true permanently fails the session. It also notes the final report return value, giving a clear side-effect model with no contradiction.

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 three tight sentences, front-loaded with the core action and followed by side effects and the markFailed flag. No filler or redundancy is present.

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 destructive, non-idempotent tool with a required reason parameter, the description omits what 'reason' should contain and what 'notes' are for. While the output schema may describe the final report, invocation-critical parameter semantics are incomplete.

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 description coverage is 75%, so most parameters are already documented. The description repeats markFailed's behavior but does not compensate for the required 'reason' parameter or optional 'notes', neither of which have schema descriptions or explanatory text here.

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 states a specific action, 'End the current run', and explains the consequences: in-flight units are released with checkpoints, the session is classified into one of four states, and markFailed:true ends it permanently. This clearly differentiates stop_session from sibling tools like pause_session and resume_session.

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 implies this tool is for ending a run versus pausing it, and explains that markFailed:true makes the end permanent. However, it never explicitly names the alternative tools (pause_session or resume_session) or states when not to use stop_session, relying on inference.

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