debug_python_repro

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

No annotations are provided, so the description carries the full burden, and it discloses only the happy-path sequence. It omits critical behavior: what happens on timeout (default 20s), whether a debugpy server or child process is left running or cleaned up, what is returned when a breakpoint is never hit, and the cost or side effects of spawning a process. "Launch...under debugpy" hints at a side effect but nothing about lifecycle or failure modes is stated.

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?

Two tightly packed sentences with the routing directive front-loaded and zero filler. Every clause carries information an agent needs.

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?

For a 10-parameter tool with a nested breakpoint object, no annotations and no output schema, the description is too thin. It should explain the session lifecycle (interaction with keep_session), timeout semantics and what a returned stack looks like, since none of that is recoverable from structured fields alone.

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 a middling 60%, and the description adds no parameter-level meaning beyond loosely implying stop_on_entry ("continue to the first stop") and locals_limit ("top-frame locals"). Undocumented parameters such as args, timeout, locals_limit and stop_on_entry are left entirely to the schema, so the coverage gap is not compensated.

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 names a specific verb set and resource: launch a Python script under debugpy, set breakpoints, continue to the first stop, and return the stack plus top-frame locals. "Use this first for a reproducible Python bug" also distinguishes it from the sibling debug_launch/debug_attach tools, so an agent can pick it without opening a 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?

It gives clear entry-point guidance ("Use this first") and states the triggering condition (a reproducible Python bug). It never names the alternatives or gives exclusions, such as what to use when the bug is not reproducible or the process is already running, so an agent gets context but no comparisons.

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