postfader_execute_run

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

Annotations already carry the destructive/non-idempotent/read-only profile, so the description's job is to add context beyond them. It does: the run lifecycle ('until its plan completes or blocks'), the validate-completely-before-executing ordering, and the explicit mutation authorization gate. What it does not disclose is what 'blocks' concretely means, partial-execution behavior, or whether failures are reversible — but with destructiveHint=true already declared, this is solid supplementary disclosure rather than a gap.

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?

One 13-word sentence that front-loads the action, names the resource, and states the termination condition. Every clause in the description and both parameter descriptions carries distinct information. No filler, no restatement of the title, and no bloat despite the enormous schema it accompanies.

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 size and danger profile, the description is largely sufficient: it states the core lifecycle, the validate-then-execute ordering, and the auth precondition, while output schema and annotations cover the safety profile. It could be more complete by routing the agent toward postfader_validate_run for pre-flight checks or defining what conditions cause a run to block, but those are refinements, not essential omissions.

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%, so the baseline is 3, but both descriptions add genuine meaning beyond the bare refs. The plan description explains the consumption contract (validate completely, execute in order), and the request description explains the task-scoped nature and the authorized_to_modify=true requirement. These are not restatements of schema structure; they convey ordering and authorization semantics the schema alone cannot.

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+resource ('Create and execute one task-scoped run') and adds a crisp termination condition ('until its plan completes or blocks'). This distinguishes it from sibling tools at a glance: validate_run only validates, continue_run resumes, stop_run stops, get_run/list_runs observe. No ambiguity about what this entry point does.

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 itself gives clear context for when this tool is the right choice (creating and executing a run end-to-end versus validating or continuing one). The parameter descriptions strengthen this: the plan description states it must be a 'Closed bounded plan to validate completely, then execute in order,' and the request description sets a critical precondition that mutating plans require authorized_to_modify=true. It stops short of explicitly naming alternatives or when-not-to-use, so it earns a 4 rather than a 5.

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