start_debug_session

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

Annotations already declare the non-read-only, non-idempotent, non-destructive profile, so the bar is lower; the description still adds value by disclosing a concrete failure mode (OpenOCD without server_args) and the fallback chain to the active profile. It does not say what happens to an already-running server/session, whether a process is spawned, or how failures surface, so it falls short of full disclosure.

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?

Purpose is front-loaded in the first clause, followed by the one constraint an agent will most likely trip over and a formatting example. Three sentences, no restatement of the name and no filler.

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 an 8-parameter, zero-required session-start tool with no output schema, the description covers the essential call-shaping information (backend choice, mandatory openocd args, profile fallbacks). It leaves unclear the interaction with stop_debug_session/close_session and whether a prior session must be closed first, which is the main remaining gap.

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, but the description genuinely adds meaning beyond it: it flags that server_args are mandatory for openocd (the schema calls them merely 'optional'), names the required -f interface/target form, and explains that unspecified parameters are resolved from the active debug profile.

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?

Gives a specific verb (starts) plus two concrete resources (the GDB server and the GDB client connection) and enumerates the supported backends (openocd, stlink, jlink). An agent immediately knows what the tool does, though it never names a sibling such as stop_debug_session or detect_probe to disambiguate the session lifecycle.

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 supplies a real precondition — OpenOCD cannot run without server_args naming probe and target, with a concrete example — and notes that omitted values fall back to the active debug profile. However, it gives no guidance on when to prefer this over adjacent tools (suggest_server_args, detect_probe, hub, recover_session); usage is implied rather than routed.

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