debugger_scopes

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the meaningful constraint that the frame must be retained (i.e., the session is still suspended), but says nothing about what happens when the frame handle has expired or about rate/expiry behavior beyond the schema's own note on generation.

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?

A single front-loaded sentence with no filler; the scoping constraint appears immediately after the action. Nothing extraneous, though it is arguably under-written rather than over-written.

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?

An output schema exists, so return values need no explanation, and annotations cover safety. For a debugger tool that requires an opaque, generation-bound frame handle, however, the description omits the prerequisite workflow (snapshot via debugger_get, frames via debugger_stack) that an agent needs to call it successfully.

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 description coverage reports 0% at the top level, and the description explains none of the three parameters (session_id, frame, timeout). Some relief comes from the nested FrameRef definition, which documents session_id and generation provenance, but the description itself adds no meaning about the opaque handle or the timeout's effect.

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?

States a specific verb and resource ("List the variable scopes") plus a binding constraint ("belonging to a retained stack frame"), which distinguishes it from a plain variables listing. It does not explicitly name debugger_variables or debugger_stack as the related siblings, so differentiation is partial rather than explicit.

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?

No when-to-use or when-not-to-use guidance is given. The word "retained" hints that a suspended frame is required, but it never says how to obtain such a frame or how this relates to debugger_variables / debugger_stack, leaving the agent to infer the workflow order.

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