preflight_files

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

Beyond the readOnly and idempotent annotations, the description adds critical behavioral context: it explicitly states that no directory scanning occurs and that omitted optional inputs are reported as 'unavailable capabilities' rather than clean results. This clarifies how the tool handles missing parameters, which is a significant behavioral nuance beyond the annotations alone.

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?

The description is three sentences with no filler. The first sentence states purpose, the second clarifies input scope, and the third explains behavior on omission. It is front-loaded with the core action and each sentence earns its place by contributing distinct, necessary information.

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?

With 8 parameters, no output schema, and no explicit enumeration of the checks performed, the description provides sufficient context: it defines the tool's domain (local files), its safety profile, and handling of missing inputs. The output_format parameter handles return shape, and sibling tools list_preflight_rules/explain_preflight_rule can cover rule details. It is complete enough for an agent to use correctly, though slightly more detail on what 'readiness' entails would elevate it.

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?

The schema already provides descriptions for all 8 parameters (100% coverage), so the baseline is 3. The description adds meaning by explaining the collective effect of omitting optional parameters (e.g., suppressions_path yields 'suppression checks did not run'), which is a parameter-level semantic not present in the schema. This justifies a 4 over the baseline.

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 action ('Check a campaign described by local files and return its readiness report') with a clear resource (local files). It distinguishes itself from siblings by emphasizing 'local files' and the scoping rule 'Reads only the paths given here', which sets it apart from tools like preflight_demo or preflight_instantly_campaign that likely handle other sources.

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 implies usage for file-based campaigns and clarifies that only explicit paths are read, but it does not explicitly contrast with sibling tools or state when to choose this over preflight_instantly_campaign or preflight_demo. The guidance is implied rather than directive, so it misses the 'when/when-not' bar for a higher score.

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