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

Annotations declare readOnlyHint=true, and the description adds valuable context beyond that: the output format (IOM with source_lineage and methodology_version), weekly update frequency, history since 2003, and the composite z-score basis. It does not discuss rate limits or error handling, but the read-only nature is already covered.

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 concise and front-loaded with the main output. The only redundancy is the final 'Updates: weekly' which repeats the weekly frequency already stated in the first sentence, causing minor waste.

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?

For a simple read-only tool with one optional parameter and no output schema, the description covers the score range, data source, calculation method, update cadence, return format, and audit trail fields. The schema handles the parameter details, making the overall definition complete.

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 only parameter 'days' is fully described in the schema, including the Gold-tier requirement and fallback to snapshot. The description does not mention any parameter specifics, so with 100% schema coverage, the baseline of 3 is appropriate.

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 clearly states the tool returns a 0-100 US live air-traffic density score, explains the composite z-score methodology, specifies the output as an IOM with source_lineage and methodology_version, and lists concrete use cases. It distinguishes this tool from generic data tools by its focused aviation demand scope.

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 provides explicit trigger phrases ('air traffic volume', 'flight activity', 'airspace congestion', etc.) and a specific use case for airline-sector equity models. It lacks explicit exclusions or alternative tool names, but the context is clear enough for an agent to decide when to invoke.

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