Start User-Space Debugging

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the bar is lower, yet the description still adds real substance: exclusive managed lease semantics, the shared-environment requirement, attach-mode rejection rules, the single-inferior/multithreaded/all-stop limitation, and the idempotency mechanism (unchanged owner + request_id). The notable gap is that for a destructiveHint=true tool it never says what is destroyed or what happens to an existing debug session, and it does not mention lease expiry or concurrency conflicts.

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?

Four dense sentences with no filler, front-loaded with the core action and mechanism before the constraints and retry note. The tradeoff is terseness bordering on cryptic ('ChannelTerm, GDB, gdbserver, and ELF must share one Linux environment'), which costs a read or two but wastes no words.

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 return values need no explanation, and the description covers the two operating modes, environment preconditions, and retry semantics for a tool with a destructive, leased, open-world profile. It falls short on failure modes and on the lifecycle after start (which siblings to call next, what debug_stop or lease release does to the session).

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?

With 100% schema description coverage the baseline is 3, and the description earns above that by adding behavior the schema does not: that omitting PID launches with isolated I/O, the attach rejection conditions, and the retry contract for owner/request_id. It still doesn't clarify the gdb/gdbserver default resolution or the 128-argument cap, but those are already in 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?

States a specific verb and resource — 'Start native Linux user-space GDB/MI on an idle Bash Session using an exclusive managed lease' — plus the exact environment constraint (ChannelTerm/GDB/gdbserver/ELF must share one Linux environment). An agent knows precisely what is being created. It does not, however, name or differentiate itself from the obvious siblings debug_bridge_start or debug_command, so the agent must infer the boundary between user-space GDB/MI debugging and the bridge tools.

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 launch-vs-attach split is spelled out conditionally ('PID omitted launches with isolated I/O; attach rejects controlling terminals, pipes, sockets, or shared character devices'), and the retry path is explicit ('Reuse owner and request_id unchanged to retry'). What is missing is routing guidance against alternatives: nothing says when to pick this over debug_bridge_start or when to follow with debug_command/debug_stop. Usage is implied by the constraints rather than stated as when-to-use.

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