Plan the gauntlet

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds execution-relevant behavior: hosted stages need the connection token, core stages are answered by the model itself, and the plan requires no account. That auth/execution context is genuinely beyond the structured fields, though it stops short of describing ordering guarantees or failure modes.

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, front-loaded with the invocation condition, then the return shape, then the hosted/core execution caveat. Dense but every clause carries information; it could be marginally tightened but nothing is wasted.

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 an output schema exists (so return values needn't be spelled out), rich annotations, and a nested optional parameter, the description covers when to call, what the plan contains, and the token/account requirements for following through. An agent has everything needed to call it and act on the result.

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 is 100% and the single `context` parameter is documented in-schema as the same object prepare_review takes. The description adds only that empty Context fields are reported back, which is useful framing but not syntax or structure beyond the schema, so baseline 3 applies.

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 (plan/returns the 8 stages) and resource (the gauntlet pre-submission run), and enumerates the returned contents: stages, profiles, running tool, files and Context fields read, call instructions, empty fields, and the terminating build_packet call. It also distinguishes its role from siblings by naming run_review and build_packet.

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?

"Call when the researcher wants the full pre-submission run" gives a clear triggering condition and implies this is the entry point for the whole flow. It clarifies which stages route to run_review versus the agent's own model, but offers no explicit when-not or contrast against prepare_review/list_profiles beyond the shared context reference.

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