Collect Adaptive Runtime Evidence

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

The description explains the phased behavior in detail: it starts with stack and small locals, expands only when symbols/exception state/variables are insufficient, and finishes with a full runtime report when needed. Since annotations already mark it read-only and idempotent, the description adds meaningful behavior context beyond static hints.

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 no filler: behavior, usage condition, and exclusion are each covered in a focused, front-loaded manner. Every sentence earns its place.

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?

With full schema parameter coverage, an output schema, and strong annotations, the description provides the missing behavioral and usage context. An agent has everything needed to decide when to call it and understand how it behaves.

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 input schema already covers 100% of parameter descriptions, including forceFull, sessionId, and maxVariables. The description does not add parameter-level detail, but because the schema is complete, the baseline score of 3 is appropriate.

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 identifies a specific verb and resource: 'Collect runtime evidence' in progressively richer bounded phases. It also explicitly contrasts itself with requesting a maximal snapshot and with deliberate deep inspection, which distinguishes it from sibling tools like debug_snapshot and debug_runtime_report.

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?

It gives explicit guidance on when to use the tool ('when token/DAP cost matters or the amount of evidence needed is unknown') and when not to use it ('Do not use it to replace deliberate deep inspection when the required evidence is already known'). This is direct and actionable.

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