orchestrator_preflight

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

No annotations are provided, so the description carries the full burden. It does disclose return semantics (blockers gate, setup_required precedence) and implies the tool inspects external state including a 'caffeinate command', hinting at a possible side effect. However, it never states whether invoking it mutates anything, starts a process, or requires auth, which matters for a tool with no safety annotations.

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 dense sentences with the outcome condition ('Ready if blockers is empty') front-loaded in the second. No filler, though the slashed check list is somewhat telegraphic.

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-format detail is not required, and the description still adds the gate logic. For a zero-annotation preflight tool with two undocumented parameters, though, it omits prerequisites and side-effect behavior that an agent would need before calling it in a pipeline.

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 0% and neither of the two parameters is mentioned in the description. 'app_dir' is entirely absent, and 'skip_options_check' is only obliquely implied by the phrase 'run options confirmed' with no indication that it can be bypassed. The description does not compensate for the documentation gap.

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 function ('pre-flight for an autonomous run') and enumerates the concrete checks it performs: run options, config keys, fastlane session freshness, caffeinate command. An agent can tell this is a readiness gate rather than a setup mutator. It does not explicitly differentiate from the nearby setup_status sibling, which keeps it from a 5.

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 a decision rule ('Ready if blockers is empty') and an ordering rule ('Returns setup_required first when AppFactory is not set up yet'), which implies when the caller should proceed. But it never says when to call this versus setup_status, setup_services, or orchestrator_next_action, nor whether it must be run before the main run.

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