跨会话状态：保存/读取上次调试上下文

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

All annotations are false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), so the description carries the full behavioral burden — and it over-delivers. It discloses the destructive clear action (requires confirm=true), reversal path (.bak backup, '必要时可回退'), the honesty convention (unobservable fields marked available=false, never faked to default), and the output-truncation guarantee (truncated/dropped/trimmed/hint always reported, data never silently dropped). The only tension is clear-action vs destructiveHint=false, but the confirm gate, .bak backup, and re-creatable state file make this guarded destructive behavior, so I do not treat it as a contradiction.

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 dense but well-sectioned (purpose, content, actions, conventions, path, output-control, params, risk) and front-loaded with the core purpose and the key problem it solves. The output-control section is verbose relative to its importance, and the section markers are a bit processor-like, but every section carries genuinely useful information for a 7-parameter complex tool, so it earns its length.

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 (7 params, 4 actions, env-var fallbacks, output truncation, risk) the description covers nearly everything: purpose, recorded content, all action semantics, two behavioral conventions, path resolution, output control, and a medium-risk disclosure. An output schema exists so return-shape details are covered. The one gap is a call example of {} that gives the agent no concrete invocation template — a minor omission against an otherwise complete definition.

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 43% — action, path, apply, confirm have titles but no descriptions. The description compensates for exactly these gaps: it enumerates action values (show/save/load/clear) with semantics, explains apply=true recovery scope, requires confirm=true for clear, and gives path resolution (path param vs MDKDEBUG_STATE_FILE env var vs ~/.mdkdebug/state.json default). The schema already documents compact/max_lines/full. This is solid supplementation of the weaker schema fields, though not exhaustive on every parameter.

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 states a specific verb+resource: persist/load debug configuration (state.json) to carry context across MCP sessions, and names the concrete problem it solves (symbol file drift, .axf mismatch causing expression failures). It lists the exact recorded content (project, symbol file, breakpoints, serial port, SVD device, snapshot_diff baseline), which clearly differentiates it from siblings like get_status, wait_state, target_info, and direct debug mutators (set_breakpoint, run, reset). Purpose is unambiguous and distinct.

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 gives a clear lifecycle guide: show (default) to inspect current-vs-disk difference, save with .bak auto-backup, load with apply=false for compare-only and apply=true for recoverable items, clear requiring confirm=true. It explicitly states when load applies versus not (host-side reversible items only; target-side state never auto-replayed). It does not name sibling alternatives or state when NOT to use the tool, but given no sibling overlaps with cross-session persistence, the per-action guidance is strong enough to earn a 4.

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