Wait for an ABAP Debuggee

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

Beyond the sparse annotations, the description candidly discloses side effects and hazards: registration persists as a side effect, the listener remains armed on SAP across timeouts until sap_debug_detach deletes it, the call performs the attach itself, and a STOPPED debuggee is a real frozen user session that SAP may kill. It also documents the server-side long-poll behavior and conflict error. No contradiction with annotations.

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 organized with a crisp opening, a behavior-change note, structured Args and Returns sections, state-by-state guidance, and an error-handling note. Every block adds operational value; the length is justified by the tool's stateful, side-effecting behavior.

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 stateful long-poll with no output schema, the description covers return fields, all three states, cleanup via sap_debug_detach, and conflict handling. The only notable gap is that it says 'Returns (json)' while response_format defaults to markdown in the schema, leaving how the markdown output is shaped slightly unclear.

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%, so the baseline is 3; the description adds meaning by explaining session_id origin, timeout as a client-side cap with post-timeout behavior, and poll_interval_ms as ignored compatibility. It does not repeat in depth what response_format does, but that is already fully covered by the schema.

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 leads with a specific verb and resource: 'Register the debug listener and block until the watched user's code traps on a breakpoint — then attach to it and return the stop position and call stack.' It clearly differentiates this from other debugger tools by describing a blocking long-poll and its attach/return behavior, and it names sap_debug_detach as the complementary cleanup call.

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 provides clear operational context: block until a breakpoint traps, handle TIMEOUT by calling again, handle CANCELLED by re-attaching, and release STOPPED debuggees promptly. It does not explicitly distinguish when to use this wait tool versus alternatives such as sap_debug_state, but the context is sufficient for most selections.

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