一键诊断当前现场

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond that: it aggregates multiple read-only diagnostics, is subject to interrupt context limitations (locals/call stack may be empty), and never silently drops data (truncation is reported in output). It also discloses that unrecognized parameter names are rejected, not ignored. 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 lengthy but well-structured with clear sections (purpose, limitations, output control, parameters, aliases). It front-loads the core purpose and includes necessary operational details without redundancy. Every sentence adds value, though the length is justified by the tool's complexity.

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?

Given the tool's complexity (6 optional parameters, output schema exists), the description covers purpose, prerequisites, limitations, output control behavior, and parameter aliases. The only gap is the unstated meaning of disasm_count and source_context, which are minor and inferable from context. The output schema handles return structure, so the description is largely complete for an agent to call it correctly.

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 only 50% (descriptions exist for full, compact, max_lines but not for globals, disasm_count, source_context). The description compensates partially: it explains globals (array or comma/semicolon string) and the output-control trio (compact/max_lines/full) in detail, but does not explain the semantics of disasm_count or source_context beyond their names and defaults. This is a moderate compensation, but not complete for all parameters.

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 clearly states the tool aggregates all on-site diagnostic information (registers, disassembly, source context, call stack, locals, globals) into a structured report. It explicitly names the alternatives it replaces (get_current_location/read_registers/disassemble/read_locals) and distinguishes itself as a one-call diagnostic aggregator, making its purpose unambiguous.

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 explains when to use this tool: when an AI receives a bug report and needs a comprehensive snapshot in one call, avoiding multiple round trips. It also notes prerequisites (debug entered, .axf configured) and limitations (interrupt context may restrict locals/call stack). It doesn't explicitly say when NOT to use it, but the context and alternatives are clear enough for an agent to make a decision.

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