faa-traffic-delays-mcp-server

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), so the description's job is to add beyond them — and it does: advisory numbers restart at 1 each UTC day (a real keying pitfall), older advisories remain available, and the payload contains program rate by hour, delay assignment mode, scope, comments, and plan constraints/runway closures.

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 sentences, front-loaded with the core action, then sourcing, then what the returned text adds. No filler; every clause carries routing or content 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 an output schema present, return-value detail is unnecessary, and for a 2-param read tool the description fully covers invocation: input provenance, numbering/date semantics, data retention, and value over the status endpoints.

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 100% and the schema already documents accepted alternate formats (MM/DD/YYYY, 'ADVZY 082', '082'). The description adds only the pairing 'by its number and UTC date', so the schema does the heavy lifting and the baseline of 3 applies.

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 and resource with its identifying keys: 'Get the full text of one ATCSCC advisory by its number and UTC date.' It is immediately distinguishable from the list/status siblings it names, so an agent can route correctly without opening a schema.

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?

Explicitly says where the required inputs come from (rows from faa_delays_list_advisories; advisory references returned by list_active_events, get_airport_status, and get_operations_plan) and when this tool is needed over the status feeds ('what the status feed omits'). That is when-to-use plus alternatives, with no inference required.

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

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

Annotations already cover readOnly/idempotent/openWorld, yet the description adds substantial context beyond them: the feed's active-event-only coverage, the no_active_events sentinel, runway configuration availability being limited to listed airports, and the dual coordinate sourcing (feed vs NASR). These are exactly the behavioral traits an agent needs and cannot get from structured fields.

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?

Front-loaded with the core purpose and output contents, then layers caveats. It is a dense single paragraph and some return-value detail (event types, ARTCC, AAR) is arguably redundant given an output schema exists, but nothing is wasted or contradictory.

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 single-parameter, output-schema-backed read tool, the description covers the remaining ambiguity an agent faces: valid code formats, rejection behavior, feed coverage limits, and the no_active_events case. No material gap remains.

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 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that FAA 3-character or ICAO codes are accepted, that a code naming no US airport is rejected, and how the code interacts with includedFacilities/departureScopeNm matching. That is useful validation and semantics beyond the schema text.

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 ('Get') and resource ('current FAA traffic management status') and scopes it to one or more US airports. The enumeration of what the status contains (headline status, active events, delay profile, runway configuration, AAR) makes the tool's output identity unambiguous next to siblings like list_active_events.

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 explains feed behavior (only airports with an active event are listed, so a known airport returns no_active_events) which helps an agent interpret results, but it never states when to choose this tool over faa_delays_list_active_events or faa_delays_get_advisory. Usage is implied rather than contrasted with alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: this is a forward-looking summary ('expected later in the day') and it explicitly discloses that it omits active constraints and runway closures available elsewhere.

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 sentences, front-loaded with what is returned and followed by the escalation path to the advisory. The first sentence is a dense run-on list, but each item earns its place by telling the agent what fields to expect.

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-value documentation is not strictly required, yet the description still scopes the response (summary vs. full advisory text). Combined with the annotations, an agent has enough to call this correctly; the only shortfall is absent guidance against the other four siblings.

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 tool takes zero parameters, so the baseline of 4 applies. The description correctly implies a no-argument call by describing a global snapshot rather than anything filterable, and adds no misleading parameter expectations.

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 and resource ('Get the FAA Command Center's current operations plan') and enumerates the contents: terminal programs, en-route initiatives, UTC times, likelihood, and ATCSCC announcements. It explicitly distinguishes itself from faa_delays_get_advisory by describing itself as a summary that the advisory expands upon.

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?

Names the alternative sibling (faa_delays_get_advisory) and the condition that selects it: when the full plan text, active constraints, or runway closures are needed rather than this summary. It gives no guidance versus the other siblings (get_airport_status, list_advisories), so routing is clear but incomplete.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description goes beyond that by disclosing the exact sort order (closures, ground stops, GDPs and AFPs by average delay, delays by band maximum, NOTAMs, deicing) and the payload each row carries (reason, delay figures, times, advisory reference), which materially shapes how an agent reads the result. It says nothing about rate limits or freshness/caching of the feed.

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 sentences, with the scope-and-content statement front-loaded ahead of the sibling routing. The long parenthetical sort-order enumeration is dense but does real work for result interpretation; there is no filler.

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 an output schema present, the description need not explain return values, and it still covers scope, ordering and onward navigation. Schema coverage, annotations and output schema together leave no gap an agent needs to call this correctly.

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 100% and the single optional event_types parameter is fully documented there, including aliases, comma-separated strings, case-insensitivity, and the note that countsByType always covers the whole feed. The prose adds no additional meaning about the filter, so the baseline 3 applies.

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 and resource with explicit scope ("every active FAA traffic management event across the National Airspace System") and enumerates the eight event classes it returns. It is unmistakably distinct from siblings that fetch a single airport, an advisory, or the operations plan.

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?

Names the alternative for a concrete case: "Use faa_delays_get_airport_status for the full detail of one airport, including its GDP delay profile and runway configuration." It also routes the agent onward to faa_delays_get_advisory via the advisory reference carried in each row, so the when-to-use-this-vs-that decision is spelled out rather than inferred.

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

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

Annotations already cover the read-only/idempotent/open-world profile, and the description adds behavior the annotations cannot: newest-first ordering, inclusion of canceled and past-date advisories, default-to-today, and the quirk that CDM compression advisories are filed under no category. That is substantive operational context beyond the structured hints.

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, front-loaded with the action and ordering before enumerating categories and paging. Long, but nearly every clause carries distinct information; slight overloading of the first sentence costs it the top score.

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 structure need not be re-explained, yet the description still summarizes row fields (advisory number, control element, subject, title lines, send time), and it covers filtering, paging, and follow-up routing. Nothing an agent needs to call this correctly is missing.

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 100%, so the baseline is 3, but the description adds real semantics: categories omission includes uncategorized CDM compression advisories, and control_element only matches the indexed element (airports named solely in subject/details do not match). These parsing nuances beat the raw schema text.

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?

Opens with a specific verb+resource+scope ('List the ATCSCC advisories issued on one UTC date, newest first') and enumerates the advisory families covered (ground stops, reroutes, FCAs, ops plans, CDM compression). It explicitly separates itself from the NAS Status feed and from sibling tools, so an agent can distinguish it without opening a schema.

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?

States when to reach for this tool (historical/inactive advisories that the NAS Status feed lacks), how to narrow (categories, control_element, limit/offset paging), and routes to the sibling faa_delays_get_advisory for the full text. The condition that selects the alternative is spelled out rather than implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds a small behavioral detail ('pacing airports... read live'), but otherwise does not disclose caching, freshness, or response characteristics beyond what the annotations and output schema imply.

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?

A single, densely packed sentence that leads with the tool's function and then enumerates the five topics. No filler, no redundancy.

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 an output schema present, return-value explanation is not needed, and the description covers all five topic domains that the single parameter can select. Only marginal gaps around freshness/pagination, minor for a reference lookup.

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 100% and the enum is fully documented in the schema itself; the description's topic list largely restates that enum. Baseline 3 is appropriate since the schema carries the parameter semantics.

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 (decode) and a specific resource (the vocabulary/types used by the faa_delays tool family), and enumerates the domains covered. It is clearly distinguishable from the fetching siblings like get_advisory or list_active_events, since this is a lookup/reference tool, not a data-retrieval one.

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?

Implies the usage context strongly: use this to interpret the codes and terms returned by the other faa_delays tools, and names those tools. It does not give explicit when-not guidance or spell out prerequisites, but the routing intent is clear.

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