能力自检（本服务能做什么、哪条通道现在通）

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and the description is fully consistent with them (no contradiction). Beyond that, it adds rich behavioral context the annotations cannot express: the output payload can be large with an output-control mechanism, truncated/dropped/trimmed content is always reported in the output field (never silently discarded), env vars MDKDEBUG_COMPACT/MDKDEBUG_MAX_LINES affect defaults, and channel availability depends on Keil runtime and UVSOCK state.

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 core purpose is front-loaded in the first sentence ('冷启动第一步的能力自检'), and every subsequent block — four return sections, keil_health differentiation, output-control rules, parameter summary — earns its place. The output-control paragraph is long, but justified given this tool returns large payloads and obeys environment variables. Minor redundancy exists between the description body and the input-schema parameter texts.

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 — an output schema documenting return values, complete annotations covering safety/idempotence, and three optional parameters — the description is complete. An agent has everything needed to call it correctly: what it returns (4 sections), when to call it (cold-start first), how sizing controls behave and interplay with env vars, and the guarantee of no silent data truncation. The presence of an output schema relieves the description of explaining return-value shapes.

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 each of the three parameters (full, compact, max_lines) is already documented in the schema, giving a baseline of 3. The description adds real value beyond the schema by explaining how the params interact with each other and with the environment variables (defaults, precedence, 'default not passed = unchanged behavior'), and by clarifying that dropped content is reported rather than silently lost. It slightly exceeds the baseline but the schema still carries the core burden.

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-plus-resource pair: '能力自检' (capability self-check) enumerated across four concrete return sections (channels, modules, env, tool_surface). It explicitly differentiates itself from the sibling keil_health ('keil_health 做诊断, capabilities 做枚举'), so an agent can distinguish it without opening either schema.

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 is explicit about when to invoke it: '冷启动第一步' (first step on cold-start) before trying features the agent might not have. It names the alternative keil_health and gives the exact selection criterion (diagnosis vs enumeration), and even advises which of the two debug channels to use per scenario (uvsock needs Keil running with UVSOCK open vs uv4_cmdline which does not depend on UVSOCK).

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