debug_session_stop

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

With no annotations, the description carries the burden and does well: it discloses that OpenOCD itself is shut down, and explains the core-state consequence of resume_first (firmware keeps running vs. core left halted) including the default. It omits failure modes (unknown/expired session), whether OpenOCD must be restarted afterward, and whether breakpoints/session artifacts are discarded.

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?

Front-loaded with the action and the loudest side effect in the first sentence; the Args/Returns blocks are short and every line adds information. No padding or restatement of the tool name.

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?

An output schema exists, so the Returns line is optional and the description needn't detail the payload. For an unannotated teardown tool the behavioral essentials (what is shut down, what happens to the core) are covered; error handling and post-shutdown state would round it out.

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 0%, and the description compensates fully: session_id is tied to its source tool, and resume_first is documented with its default and the concrete behavioral outcome of each setting. This is meaningfully more than the schema's bare titles and default.

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 and resource ('Stop a debug session') plus the consequential side effect ('shut down OpenOCD'), which clearly distinguishes it from debug_halt/debug_resume and from live_memory_stop. The implicit pairing with debug_session_start (via the session_id reference) makes the lifecycle position obvious.

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?

Usage is only implied: the session_id provenance ('from debug_session_start') establishes it as the teardown counterpart, but there is no explicit statement of when to call it or what to call instead when only halting/stopping a run is desired. No exclusions or prerequisites are given.

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