get_stop_reason

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

With no annotations, the description carries the burden of explaining behavior. It clearly communicates that the tool is a read-style query returning diagnostic stop information, which is useful. It does not disclose edge cases such as what happens if no stop has occurred, whether session_id must refer to a valid session, or the exact response structure, so transparency is only partially complete.

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 a single compact sentence with no filler. The key information—what is returned and what categories of stop reason are included—is front-loaded and every word earns its place.

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 simple one-parameter getter, the description covers the core purpose and the return content at a summary level. It is incomplete because there is no output schema, no annotation guidance, and no explanation of session_id semantics or the conditions under which the stop reason is available.

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 schema has 0% description coverage, so the description needed to explain session_id but does not mention it at all. The parameter name and title provide some clue that it identifies a session, and it is optional, but the description adds no meaning about how it is used or what null means.

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 names the specific resource ('the inferior') and the exact data returned (signal, fault address, breakpoint info), making the tool's function clear. It does not use an explicit action verb like 'retrieve' or 'get', and it does not directly distinguish itself from siblings like crash_report or session_status, though the focus on stop reason is fairly unique.

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 the tool should be used when the agent needs to know why the inferior last stopped, which is a reasonable contextual cue. However, it does not explicitly say when to use it versus alternatives such as wait_for_stop, get_backtrace, or crash_report, nor does it mention prerequisites like an active stopped session.

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