framerudiments_preflight

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

The description goes materially beyond the annotations by disclosing that each call creates a new evidence directory and returns a retained background job requiring polling — behavior consistent with idempotentHint=false but not derivable from it. It also warns that base flags are 'write' with conditional inference/download effects that must be inspected elsewhere, which is meaningful context for a mutation-flagged tool. It stops short of saying what gets destroyed or overwritten if the target exists.

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 short sentences, front-loaded with the action and scope, then the async contract, then the permission caveat — no filler. The final sentence is slightly cryptic ('Inspect danceflow_component for conditional inference/download effects') but still earns its place by pointing at the permission decision.

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 not be explained, and the async/polling contract is covered. What is missing is the semantic meaning of the required project and output arguments and any statement of what the preflight checks for or what constitutes success versus failure.

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 50%: the nested permissions object carries its own description, but project and output have none in either schema or description. The description adds real meaning for the effect flags ('base write', 'conditional inference/download'), which partially compensates for the gap, but the two required path-like arguments remain undocumented.

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 and resource ('Run the canonical renderer preflight') and states its scope ('in a new evidence directory'), which distinguishes it from siblings like framerudiments_render and framerudiments_plan. However, 'preflight' is domain jargon and the description never says what the preflight actually validates, so an agent gets the shape of the operation but not its substance.

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 useful follow-up routing ('poll danceflow_job_status') and points at danceflow_component for conditional effects, which is real when-to-use guidance. It does not say when an agent should choose this over framerudiments_plan or framerudiments_render, nor what prerequisites must be in place, so the choice among sibling renderer tools remains implied.

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