Preflight a task file scope without dispatch

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description's 'creates no run' and 'does not execute checks' largely restate that read-only profile; it adds little new behavioral context such as whether validation failures throw, what permissions the caller needs, or how policy conflicts are surfaced.

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 tight sentences with the validation scope front-loaded and the non-mutating guarantee immediately after. No filler; the only weakness is that brevity here trades away the parameter detail the low schema coverage requires.

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?

Annotations cover safety and idempotency, but with no output schema the description should explain what a validation run yields (pass/fail, policy violations, exit semantics). For a 7-parameter tool centered on path policy and admission, the description leaves the result contract and most inputs unaddressed.

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 very low at 14%, so the description carries the burden and does not meet it. It gestures at 'declared external paths' and 'configured path policy,' loosely mapping to externalPaths/writeScope, but says nothing about workspace, reviewTargets, contextReadScope, excludedPaths, or permissionPreset, leaving most of the 7 parameters unexplained.

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 verb (validate) applied to concrete resources (project admission, declared external paths, path policy), and the title adds the distinct framing 'preflight a task file scope without dispatch.' That separates it from run-dispatch siblings like start_run and queue_run, though no sibling is named explicitly in the description.

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 phrase 'Does not execute task checks or commands and creates no run' implies a preflight/dry-run positioning, which hints that this should be called before dispatch. However, there is no explicit when-to-use statement, no stated prerequisites, and no named alternative (e.g., 'call this before start_run'), so usage must be inferred.

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