Debug This Crash

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

Annotations mark the tool destructiveHint=true and readOnlyHint=false, and the description expands that into concrete guidance by warning that execution modes 'can run application code and cause its normal side effects.' It further distinguishes current/dump as 'only inspect stopped evidence' and discloses deterministic fixed/blocked/budget-exhausted outcomes, which annotations do not convey.

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?

Three sentences with clear roles: mode overview, safety boundary, and workflow/return summary. It is dense but every sentence earns its place, and the front-loaded 'Preferred high-level native crash workflow' gives immediate orientation for a complex 18-parameter tool.

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 tool with 18 parameters, nested objects, and no output schema, the description covers the high-level decision axes of mode, safety, and workflow.stage, and what to expect in return. It leaves detailed response shape and substage mechanics to the schema or runtime, which is a modest gap given the schema's own richness.

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 100% description coverage, so the baseline is 3, and the description mostly restates mode and workflow.stage semantics already present in the schema. It adds limited selection-level framing, such as read-only postmortem versus execution-capable modes, but it does not materially expand parameter meaning beyond the well-described fields.

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 is explicitly framed as the 'Preferred high-level native crash workflow' and enumerates five modes, making it clear the tool owns end-to-end crash debugging rather than a single snapshot or disconnect action. It does not explicitly say how it differs from sibling tools like debug_diagnose_stop or debug_open_dump, so the differentiation is implicit through 'preferred high-level' and the mode list.

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?

Mode-to-condition mapping is explicit: current for an already stopped session, dump for read-only postmortem analysis, codelldb/lldb-dap to discover and launch local binaries, live for an initialized DAP adapter. It also provides a clear exclusion: do not use codelldb/lldb-dap/live when execution/attach is unauthorized, since those modes run code while current/dump only inspect stopped evidence. workflow.stage is also mapped to diagnose/verify/autonomous.

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