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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context: it returns only a count, not the flights themselves, and it clarifies the query syntax family. It does not describe pagination or error behavior, but for a count tool with read-only annotations, the added context is solid.

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 with zero waste. The core behavior is front-loaded, the syntax distinction is stated immediately, and the example is compact. Every sentence earns its place.

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 count tool with 2 parameters, 100% schema coverage, and read-only annotations, the description is nearly complete. It explains the return shape, the syntax family, and gives an example. The only minor gap is that it doesn't explicitly state what happens with an empty result or invalid query, but that is not essential for an agent to call it 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 coverage is 100%, so the schema already documents both parameters. The description adds meaning by clarifying that the query parameter uses the simplified syntax and by giving a concrete example ('-airline UAL -belowAltitude 30000'). It also explains the view parameter's compact/full distinction in the schema itself, so the description's added value is moderate but real.

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 verb ('Count'), a resource ('flights'), and a clear scope ('matching a query without returning the flights themselves'). It also explicitly distinguishes itself from fa_search_flights and fa_search_flights_advanced by naming the syntax family it uses, so an agent can tell it apart from siblings without opening schemas.

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 explicitly says it uses the SIMPLIFIED '-key value' syntax, same as fa_search_flights, and NOT the structured grammar of fa_search_flights_advanced. This gives clear when-to-use and when-not-to-use guidance, and names the alternative tools. The example further anchors correct usage.

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 declare this is a non-read-only, non-idempotent, open-world write, but the description adds substantially more: a user-confirmation step, the fact that phase 1 makes NO network call and only returns a preview plus confirmToken, that a repeat call with the token is what actually proceeds, and the tier-based 401 failure mode. That is exactly the behavioral context an agent needs before invoking a mutating call.

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?

Purpose is front-loaded in the first sentence, and the confirmation and tier details follow in a logical order. The confirmation sentence is long and clause-dense, but each clause (elicitation off switch, preview contents, token semantics) carries actionable information rather than 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?

For a 15-parameter, no-required-field, no-output-schema mutation tool, the description covers the safety flow, the prerequisite tier, and the failure mode, which is most of what an agent needs. It omits what happens after creation (no output schema exists, so return shape is unaddressed) and any rate-limit or uniqueness behavior, leaving minor gaps.

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%, with all 15 parameters individually documented, so the schema carries the parameter burden. The description adds no per-parameter meaning beyond what the schema already states (even confirmToken's guidance is duplicated in the schema). 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?

The first sentence states a specific verb and resource ('Create a flight alert') on a named account, so an agent immediately knows this is the alert-creation tool. It does not explicitly contrast itself with fa_update_alert, fa_list_alerts, or fa_delete_alert, but the verb makes the distinction inferable.

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 gives strong conditional guidance about the confirmation flow (elicitation-supported clients vs. the two-step confirmToken fallback) and a hard prerequisite (Standard/Premium tier; free Personal returns 401). It never states when to prefer this tool over siblings such as fa_update_alert for an existing alert, so usage is implied rather than explicit.

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 flag destructive=true and idempotent=true, and the description adds a lot on top: the confirmation flow, that phase 1 makes NO network call, the confirmToken replay requirement, the ability to disable elicitation via MCP_CONFIRM_ELICITATION, and the 401 failure mode on the free tier. This is exactly the behavioral context an agent needs before a destructive call.

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 verb+resource, then layered with the confirmation and tier caveats. Dense but every clause carries information; the environment-variable references add slight reading overhead.

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 destructive tool with no output schema, it covers the safety profile, the confirmation protocol, the phase-1 return shape (method, path, body, confirmToken) and the tier requirement. It does not describe the success response of the actual deletion, a minor gap.

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% and the schema's own descriptions already explain both 'id' and the 'confirmToken' contract in detail. The description reinforces the two-phase model but adds no syntax or format detail beyond what the schema states, 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 ('Delete a flight alert by id'), which cleanly separates it from fa_create_alert, fa_update_alert, fa_get_alert and fa_list_alerts. An agent knows immediately this is the destructive alert operation.

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?

Gives rich conditional guidance on how to invoke it (confirmation prompt vs. two-step preview fallback) and states the required AeroAPI tier, so the agent knows the prerequisites. It stops short of explicitly naming alternatives, but for a delete tool the usage context is clear.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the premium-tier billing/auth constraint and the expected 402/403 failure mode, which the agent cannot learn from annotations or schema.

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, front-loaded with what the tool does and followed immediately by the caveat that matters most operationally. No wasted words.

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?

All four parameters are documented in the schema, read-only behavior is covered by annotations, and no output schema exists to explain. The description adds the query-language nature and the billing failure mode, making it complete enough to call correctly, though pagination behavior across pages is only covered in the schema.

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 schema already documents all four parameters with meaningful detail (view semantics, cursor format, page billing cap). The description only hints at the Boolean query syntax, so it adds little beyond the structured fields — 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+resource ('Predictive flight search via AeroAPI Foresight') and explicitly differentiates from the sibling fa_search_flights_advanced by noting it returns predicted rather than actual data. An agent can select between the two without opening either 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?

It names the analogous sibling (fa_search_flights_advanced) and adds a premium-tier caveat, which implies the selection context. However it never states explicitly when to prefer predictive data over actual data or what conditions make this the right choice, leaving usage to inference.

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=true and openWorldHint=true, so the safety profile is covered. The description adds nothing behavioral beyond that — no note on auth requirements, best-effort/possibly-missing owner data, rate limits, or error behavior for an unrecognized tail number.

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 front-loaded sentence with the resource and the input format, zero filler. It is efficient, though it is arguably terse enough that a little more context would not have hurt.

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 lookup with full schema coverage and annotations, this is close to sufficient. However, with no output schema in existence, the description could state what comes back (owner name, address, etc.) and whether owner data may be absent, which it does not.

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 both parameters are already documented, including the fairly detailed view enum. The description's 'tail number / registration (e.g. N12345)' merely echoes the ident schema text and does not explain the compact/full view tradeoff.

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 + resource (get the registered owner of an aircraft) and names the key input (tail number / registration with an N-number example). It is clearly distinguishable from the flight-, airport-, operator-, and alert-oriented siblings, though it never explicitly contrasts itself with any of them.

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?

Usage is implied: call it when you have a tail number and want the owning entity. There is no explicit statement of when to prefer it, no prerequisite/permission notes, and no mention of what happens for an unregistered or unknown ident.

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=true and openWorldHint=true, so the description does not need to repeat these. It adds minimal behavioral context beyond the input format, such as clarifying that the tool returns 'details' but without specifying the response structure or error behavior. Given the annotations cover the main safety and data assumptions, this is adequate but not rich.

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 a single sentence that front-loads the primary purpose and input format. There is no redundant information, and it achieves maximum clarity with minimal words.

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 tool with only two parameters (one required) and no output schema, the description is nearly complete. It explains the required input format and implies the return type ('details'). However, it does not mention the optional 'view' parameter or what fields are included, though these are covered in the schema. Given the tool's simplicity, this is a minor gap.

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% with clear descriptions for both parameters: 'id' as 'Airport code (ICAO/IATA/LID)' and 'view' with a detailed explanation of compact/full behavior. The description repeats the code formats with examples (KJFK, JFK) but adds no new semantic meaning beyond the schema. This matches the baseline for full schema coverage.

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 verb 'Get', the resource 'airport', and the input method 'by code (ICAO like KJFK, IATA like JFK, or LID)'. This unambiguously identifies the tool's function and distinguishes it from sibling tools like fa_list_airports (listing) or fa_resolve_airport (code resolution).

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 the use case (retrieve airport details by code) but does not explicitly state when to prefer this over related tools such as fa_get_airport_flights or fa_get_airport_weather. No exclusions or alternatives are mentioned, leaving the agent to infer the appropriate context from the tool name alone.

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?

The readOnlyHint=true and openWorldHint=true annotations already establish this as a safe, live external read, so the description's burden is lower. It adds that results reflect 'current' delays, but says nothing about pagination behavior, freshness window, or the per-page billing note that only appears in the schema.

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 sentence that front-loads the resource and then the scope switch. No filler, no restated name, no redundant field list.

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 no output schema, the agent must rely on the description plus the well-documented schema; the description covers scope and currency but is thin on what a delay record actually contains. All four parameters are fully covered by the schema, so nothing essential is missing for a call to succeed.

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 regex pattern on `id`, the view enum explanation, the cursor semantics, and the 1-20 max_pages cap with billing rationale are all already documented. The description's 'just one when `id` is given' merely restates the schema, 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 ('Get current airport delays') plus the scope variants (all delayed airports vs. a single one via `id`). That is enough to distinguish it from flight-oriented siblings like fa_get_flight_route, though it never names an alternative tool explicitly.

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 conveys the id/no-id branching, which tells an agent how to widen or narrow the query. But it gives no when-to-use guidance relative to siblings such as fa_get_airport_flights or fa_get_airport, so selection between delay data and other airport data is left to inference.

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 provide readOnlyHint=true and openWorldHint=true. The description adds context about the response shape (specifically the metrics returned) and the schema's description of 'view' adds behavioral detail about field projection and the risk of dropping fields, which goes beyond annotations.

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 a single concise sentence that front-loads the key purpose and metrics. It avoids fluff, though it could be slightly more structured to note input requirements, but it's already efficient.

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 read-only count tool, the description is sufficient to understand what it returns. The schema explains both parameters fully. No output schema, but the returned fields are enumerated. Potential missing info like exact response format is minor given the low complexity.

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 covers parameters 100%: 'id' has a pattern and description, 'view' explains the enum options in detail. The description slightly adds by listing the metrics, but the schema already explains the 'view' parameter's purpose comprehensively.

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 retrieves current flight counts at an airport, listing the exact metrics returned (departed, enroute, scheduled_arrivals, scheduled_departures). It distinguishes from sibling tools like fa_get_airport, fa_get_airport_delays, and flight-specific tools by focusing on aggregate counts.

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 it's for aggregate counts at an airport but doesn't explicitly state when to use this vs. alternatives like fa_get_airport_flights which might list flights. However, the metric names clarify its purpose for counts, and the schema description for 'view' provides usage guidance on response shape.

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 declare readOnlyHint and openWorldHint, so the safety profile is already covered. The description adds nothing about pagination behavior or billing, even though the schema's max_pages field mentions per-page billing — that context lives in the schema, not the description.

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 compact sentence that front-loads the verb and resource and lists the variants. Nothing wasted.

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?

Adequate for a read-only list tool whose annotations carry the safety profile and whose schema documents all 8 parameters. It is missing usage routing versus the many flight-search siblings and any note on pagination cost, which a caller of a paged, billed endpoint would want.

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%, with each parameter documented including enums, defaults, and the cursor format. The description repeats the board enum but adds no syntax or format detail the schema does not already provide, so 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 clear verb+resource: 'Get a flight board for an airport', and enumerates the board views. It is distinguishable from sibling fa_get_scheduled_flights and fa_search_flights by the airport-board framing, though it does not explicitly name those alternatives.

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 enumerates the board variants, which implies when to use each, but it never states when to use this tool over fa_get_scheduled_flights or fa_search_flights, nor any prerequisite about an airport id being 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 declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the shape of the payload (aircraft types, counts, filed altitudes), which is useful with no output schema, but says nothing about pagination, ranking, or the time window behind 'most popular'.

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 sentence, front-loaded with the verb and resource and parenthetically listing the returned fields. Zero wasted words.

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 no output schema, the description usefully enumerates the returned fields, and annotations cover the safety profile. It is close to complete, though it omits how 'popular' is measured and how paging interacts with the billed max_pages limit.

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 itself documents id, destination, view, cursor, and max_pages in detail. The description adds no parameter-level meaning beyond what the schema already provides, so 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?

The description gives a specific verb+resource: 'Get the most popular routes ... flown between an origin and destination airport,' and names the response fields (aircraft types, counts, filed altitudes). It is clearly distinguishable from airport-level siblings like fa_get_airport_flights, though it never explicitly names an alternative.

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?

Usage is implied by the two-airport framing (use it to see routes between a specific origin and destination), but there is no explicit when-to-use, when-not-to-use, or named alternative among the many siblings. Adequate but with clear gaps.

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=true and openWorldHint=true, so the safety profile is covered. The description adds that output is METAR/TAF data, but says nothing about auth, rate limits, or billing behavior (billing is only hinted at in the schema's max_pages note). Adequate but thin.

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 front-loaded sentence with zero waste. The resource and the two report variants come first, which is exactly what an agent needs to route on.

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 read-only lookup with full schema coverage and no output schema, the description is sufficient to call correctly. It could optionally note the default view/report behavior or pagination expectations, but nothing essential 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 schema already documents all five parameters in detail (id pattern, view semantics, cursor, report enum, max_pages billing cap). The description only restates the report concept, adding no meaning beyond the schema. 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 (get weather for an airport) and enumerates the two content types returned (METAR observations, TAF forecast). No sibling tool covers weather, so differentiation is inherently satisfied, but the description does not call this out explicitly.

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 'current METAR observations, or the TAF forecast' implies which option to pick via the report parameter, but there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives. Usage is only 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?

The description adds a concrete behavioral fact beyond the readOnlyHint/openWorldHint annotations: the tool requires Standard or Premium tier and fails with 401 on the free tier. This is useful operational context. It does not contradict any annotation, and no read/write confusion exists since 'Get' aligns with readOnlyHint.

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 one compact sentence plus a terse tier requirement, with no filler. The primary action and resource are front-loaded, and the auth note is a meaningful second sentence.

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 two-parameter read operation, the description plus rich schema coverage is nearly complete. The auth requirement is stated, the response is implied as the alert object, and annotations already cover read-only/open-world behavior. It only stops short of 5 because it does not explicitly mention not-found behavior or describe the response shape outside the view parameter text.

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 id and view are already documented in the schema. The description itself only repeats 'by its id' and does not add new parameter-level semantics, so the schema-covered 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 uses a specific verb ('Get') with a clear resource ('a single configured flight alert') and the retrieval key ('by its id'). This cleanly distinguishes it from alert-list, create, update, and delete siblings without requiring schema inspection.

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 the right time to use it: when you need one specific alert by id. It also adds an important real-world prerequisite by stating the required AeroAPI tier and the 401 on the free Personal tier. It does not explicitly name fa_list_alerts for listing multiple alerts, but the single-by-id wording makes the selection clear.

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 mark readOnlyHint=true and openWorldHint=true. The description adds a meaningful behavioral disclosure: the tier requirement and the specific 401 error for free tier users. This goes beyond the annotations and helps the agent anticipate failure modes. No contradiction with annotations.

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 two sentences with no filler. The purpose is front-loaded, followed by the critical prerequisite. Every word earns its place, and the structure is clean and scannable.

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 getter with one optional parameter, the description covers the core purpose and a key prerequisite. The lack of an output schema is not a major gap because the response shape (the endpoint URL) is implicitly understood. It could note that the response is the endpoint string, but the current level is adequate for correct invocation.

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 itself contains a detailed description of the 'view' parameter, including the compact/full distinction and the rationale for dropping fields. The tool description adds no additional parameter information, so it does not exceed the baseline for fully covered schema.

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 verb 'Get' and the resource 'current delivery (webhook) endpoint' for AeroAPI alerts. It is distinct from sibling tools like fa_set_alerts_endpoint (set) and fa_list_alerts (list alerts), leaving no ambiguity about what this tool retrieves.

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 the key prerequisite (Standard/Premium tier) and the consequence of not having it (401), which informs when the tool can be used. It does not explicitly contrast with alternatives like fa_set_alerts_endpoint, but the retrieval-versus-set purpose is clear from the name and description, so the usage context is effectively communicated.

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 safety profile (readOnlyHint=true, openWorldHint=true), so the description's job is to add auth/operational context — which it does with the tier requirement and the 401 outcome. It adds no further detail on pagination cost or response shape beyond what the schema carries, so it falls short of 5.

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, zero filler, with the scope boundary front-loaded before the tier caveat. Every clause carries actionable 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?

For a 7-parameter read tool with full schema coverage, no output schema, and minimal annotations, the description supplies the crucial routing and auth context. It is nearly complete, though it could say more about expected result volume/ordering when paging through history.

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. The description restates that 'ident' accepts designator/registration/fa_flight_id, which the schema already documents, and adds no guidance on start/end window semantics, view, or paging 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 and resource ('Get historical flights for an ident') plus the scope boundary ('beyond the recent window'), and explicitly names the sibling fa_get_flights as the recent-window counterpart. An agent can distinguish it from fa_get_flights without opening either 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?

Routes the agent explicitly: use this for history beyond the recent window, use fa_get_flights for the recent window. It also states a hard prerequisite (Standard/Premium AeroAPI tier; free Personal tier returns 401), which is the kind of when-not guidance that prevents failed calls.

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 (readOnlyHint=false, idempotentHint=false, destructiveHint=false) hint that this is a non-destructive but side-effecting operation; the description concretely discloses the side effect (writing a PNG to disk) and the exact default location, which is valuable context beyond the flags. It could add more about overwrite behavior given idempotentHint=false, but it already adds real behavioral value.

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 tightly written sentences, front-loaded with the core purpose followed by return/side-effect behavior. Every clause earns its place with 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 no output schema, the description carries the return-value burden and does so by naming both possible returns (file path or base64). It is nearly complete for a single-artifact tool, missing only minor details like repeated-call overwrite semantics.

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 all six parameters are already documented, making a 3 the baseline. The description restates the inline toggle and output_dir default, which the schema already conveys, adding little new syntax or edge-case meaning (e.g., how width/height interact with the render).

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 a rendered map image (PNG) of a flight') keyed by fa_flight_id, which clearly distinguishes it from sibling read tools like fa_get_flight_track and fa_get_flight_route. An agent can identify the exact artifact produced without opening the 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?

Explains the two operating modes well: write-to-disk-by-default versus inline base64 when inline:true, which is the key invocation choice. However it gives no explicit when-to-use / when-not-to-use guidance relative to the other flight-visualization siblings, so it stops short of a full routing statement.

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=true and openWorldHint=true, so the safety profile is covered. The description contributes the non-obvious constraint that only in-air flights have a reported position, but it does not say how stale the report may be, what is returned for a grounded flight, or whether an error or empty result occurs.

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 front-loaded sentence with a verb, resource, scope qualifier, and lookup key, with zero filler. Nothing could be removed without losing 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?

For a simple read-only lookup with full schema coverage this is close to adequate, but there is no output schema and the description gives no hint of the response payload (position fields, timestamp of the report). The view parameter's effect on the response is only explained in the schema, not tied back to the description.

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 rich 'view' enum documentation lives entirely in the schema, including the compact/full tradeoffs. The description only restates that lookup is by fa_flight_id, which adds no meaning beyond the schema; baseline 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?

States a specific verb (get) plus a precise resource (most recent reported position) and the lookup key (fa_flight_id). The 'in-air' qualifier implicitly separates it from fa_search_flight_positions and fa_get_flight_track, but no sibling is named, so an agent still has to infer the distinction.

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?

There is no when-to-use guidance, no statement of what happens when the flight is not in the air (scheduled, landed, unknown), and no pointer to alternatives like fa_search_flight_positions for multi-flight position queries. Usage is only weakly implied by the phrase 'in-air flight'.

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 and openWorldHint, so the safety profile is covered. The description adds that the route is 'decoded' into fixes/waypoints, but says nothing about return size, rate limits, or how the route relates to a live position.

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 front-loaded sentence with no filler; the resource and identifier are stated immediately.

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 read-only tool with no output schema and fully documented parameters, the description is minimally adequate. It could say more about what the route represents (past track vs planned route) to help an agent choose among the flight-position 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?

Schema description coverage is 100% and the view enum is thoroughly documented in the schema. The description only echoes the id parameter ('by fa_flight_id') and adds nothing about the view parameter, so 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 ('Get') and resource ('decoded route (fixes/waypoints) for a specific flight'), keyed by fa_flight_id. It is clear what the tool returns, though it does not explicitly distinguish itself from near-siblings such as fa_get_flight_track or fa_get_flight_map.

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?

There is no guidance on when to use this tool versus fa_get_flight_track, fa_get_flight_map, fa_get_flight_position, or fa_get_flight_history, which all operate on the same flight id. The agent gets no conditions or exclusions.

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 and openWorldHint, so the safety profile is covered. The description adds the temporal scope of results (recent/current/scheduled), which is genuinely useful, but says nothing about pagination behavior, page-based billing, or result-size limits even though those materially affect a call.

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, front-loaded with the verb and the ambiguity-prone ident argument; every clause earns its place.

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 7-parameter, no-output-schema tool, the description covers the argument forms but omits the time-window/paging story that start, end, cursor and max_pages imply. Adequate rather than 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?

Schema description coverage is 100% (including ident patterns, enum values, cursor semantics and the per-page billing cap on max_pages), so the schema already carries the parameter load. The description's ident examples (UAL123, N12345) are mildly reinforcing but add nothing the schema lacks.

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 ('flights') and enumerates the three accepted ident forms with examples, so an agent knows exactly what the tool retrieves. It does not, however, explicitly differentiate itself from near-siblings like fa_get_flight_history or fa_resolve_flight, which the ident-overloading makes necessary.

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 says what comes back ('recent, current, and scheduled flights') but never states when to pick this over fa_get_flight_history, fa_search_flights, or fa_resolve_flight. With 30+ siblings, the absence of any routing guidance leaves selection to inference.

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=true and openWorldHint=true, so the safety profile is covered. The description adds the semantic that the response is a track/log rather than a snapshot, but says nothing about the time span covered, sampling density, or pagination of the breadcrumb points.

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 front-loaded sentence with no filler; the resource and the identifying parameter are both stated immediately.

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 read-only tool with full schema coverage and no output schema, the definition is minimally adequate but leaves the most important contextual gap unaddressed: how this track differs from fa_get_flight_position and fa_get_flight_history in the same family. An agent picking among these five siblings gets no help.

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 all three parameters (id, view, include_estimated_positions) are already fully documented in the schema, including the enum values and the compact/full tradeoff. The description adds no parameter meaning beyond restating that the id is an fa_flight_id, 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?

The description gives a specific verb and resource ('Get the position track (breadcrumb log) for a specific flight'), and 'breadcrumb log' usefully characterizes the resource as a series of positions rather than a single point. However, it never distinguishes itself from near-identical siblings like fa_get_flight_position, fa_get_flight_history, or fa_get_flight_route.

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?

There is no when-to-use guidance at all, which is a real problem given five sibling tools (fa_get_flight_position, fa_get_flight_route, fa_get_flight_map, fa_get_flight_history, fa_search_flight_positions) that an agent could easily confuse with this one. Nothing states when the breadcrumb track is the right call versus a single position or a history.

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=true and openWorldHint=true, so the safety profile is covered. The description adds the unit of measure (statute miles) for the radius, which is genuinely useful, but says nothing about pagination behavior, per-page billing, or response shape. With annotations doing the heavy lifting, this is a modest but real contribution.

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 tight sentence with the primary constraint (lat/lon proximity) front-loaded and zero filler. Nothing to trim.

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 7-parameter geo-search tool with no output schema, the schema documentation is thorough, so the description does not need to explain return values. It is nevertheless thin on routing (when this beats fa_list_airports) and silent on paging and billing, which the least-surprising invocation would want.

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 every parameter (view, cursor, only_iap, max_pages, radius, latitude, longitude) is documented in the schema itself. The description restates only the radius units, adding nothing beyond the structured fields, 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?

Clear specific verb 'Find' with resource 'airports' and the qualifying constraints (latitude/longitude, radius). An agent can tell this is a geospatial proximity search. However, it does not distinguish itself from sibling list/search tools such as fa_list_airports or fa_get_airport, so it falls short of a 5.

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?

No when-to-use guidance, no prerequisites, and no mention of alternative tools. The agent must infer that this is the right tool when it has coordinates rather than an airport code; sibling routing to fa_list_airports or fa_resolve_airport is absent.

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=true and openWorldHint=true, so the safety profile is covered. The description adds no behavioral disclosure beyond 'Get details'; it does not describe response characteristics, whether the returned data is normalized, or any caveats about open-world fields. No contradiction exists with the annotations.

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?

One concise sentence, front-loaded with the verb and resource, followed by a useful parenthetical about code formats. No filler or repetition of schema content.

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 single-operator lookup, the description plus schema is nearly complete: both parameters are documented, annotations cover the read-only nature, and the code format is clarified. It is slightly incomplete because it provides no pointer to sibling operator tools and the lack of an output schema leaves return details unstated, but the core calling intent is well specified.

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?

Input schema coverage is 100%, so the baseline is 3. The description adds concrete examples ('UAL' vs 'UA') and clarifies that either ICAO or IATA is acceptable, reducing ambiguity for the required id parameter. The view parameter is already fully documented in the schema, so the description does not need to repeat it.

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?

Description uses a specific verb and resource: 'Get details for an operator (airline) by code.' It clearly distinguishes from sibling tools like fa_list_operators, which lists operators, and fa_get_operator_flights, which returns flights for an operator. The ICAO/IATA clarification makes the target resource unambiguous.

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 'by code' implies the tool should be used when the caller already has an ICAO or IATA code and wants operator details. However, the description does not name alternatives or exclusion conditions, such as using fa_list_operators to enumerate operators or fa_get_operator_flights for flight activity. Usage guidance is therefore mostly implied rather than explicit.

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=true and openWorldHint=true, so safety is covered elsewhere. The description adds essentially no behavioral context beyond the name: no mention of per-page billing/rate constraints, pagination semantics, or what the board payload resembles.

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 efficient sentence with the resource front-loaded and no filler. It is terse, but every word earns its place and nothing is wasteful.

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 5-parameter tool with no output schema, the description is thin on routing guidance, but the schema itself is thorough (100% coverage, enums, paging and billing notes), so an agent can call it correctly. It is adequate rather than 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?

Schema description coverage is 100%, including rich enum and paging documentation, so the schema carries all parameter meaning. The description only restates the board options already enumerated in the schema, adding no new 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 (Get) and resource (flight board) with the actor (operator/airline) and the range of board variants. This helps distinguish it from fa_get_airport_flights and generic fa_get_flights, though it never explicitly names those alternatives.

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 says what boards are available but never states when to use this tool over siblings like fa_get_flights, fa_search_flights, or fa_get_airport_flights, nor any prerequisites. Usage is only implied through the board enum.

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 and openWorldHint, covering the safety profile. The description adds only the implicit scheduled-vs-actual distinction and the date-range requirement; it says nothing about pagination behavior, per-page billing, or rate limits, all of which the schema carries instead.

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?

One well-formed sentence with the resource up front and the filter list trailing, so the key information lands first. The filter enumeration adds little that the schema doesn't already give, but the sentence is short enough that the redundancy costs almost nothing.

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 10-parameter, paginated, per-page-billed endpoint, the description omits any mention of paging, cost, or result scope, relying on the schema for all of it. With full schema coverage and an annotated safety profile that is minimally acceptable, but the description does not carry its share for a tool of this complexity.

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 every parameter (view, cursor, max_pages, include_codeshares, codes, dates) is already documented in the schema, often richly. The description's filter list merely restates four of the ten parameters and adds no format or semantic detail beyond the schema.

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 ('airline-scheduled flights') with a clear range constraint, so the purpose is unambiguous. However, it does nothing to distinguish itself from close siblings like fa_get_flights, fa_search_flights, or fa_search_flights_advanced, which an agent must disambiguate by name alone.

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 never says when to choose this tool over the many overlapping flight-lookup siblings, nor does it state any exclusions or prerequisites. The 'optionally filtered by' clause lists capabilities rather than usage conditions, leaving routing entirely to inference.

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 mark it read-only and idempotent, but the description adds meaningful behavioral detail: it resolves the credential the same way real tools do, makes exactly one authenticated request, reports the credential source, round-trip time, and a plain-English failure hint, and never returns the credential itself. This goes well beyond the annotations.

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 compact yet information-dense, with the core behavior front-loaded and every sentence contributing either the action, the output details, the safety guarantee, or the usage trigger. No filler or redundant restatement of the title exists.

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 no output schema, the description fully explains what the tool reports: credential source, acceptance status, round-trip time, and a hint distinguishing failure modes. It also covers safety (read-only, no credential leakage) and the intended use case, making it complete for an agent to invoke 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?

The tool has zero parameters and the schema is empty, so there is no parameter ambiguity. Per the baseline for 0-parameter tools, the description does not need to compensate for missing schema information, and it appropriately focuses on behavior and output instead.

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 diagnostic purpose: resolving credentials, making one authenticated request to aeroapi.flightaware.com, and reporting whether the credential was accepted. It clearly distinguishes this healthcheck tool from the many data-fetching siblings by focusing on connectivity and credential validation rather than flight/airport data.

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 gives an explicit trigger: 'Call this when a real tool fails and you want to know which hop broke.' This tells an agent exactly when to use the tool and frames it as a diagnostic aid rather than a data source, which is sufficient given no sibling serves the same role.

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=true and openWorldHint=true, so the safety and open-world profile is covered. The description adds only that results are paged; it says nothing about page size, per-page billing, or response contents. Because max_pages billing behavior lives in the schema rather than the description, this adds modest value over structured data.

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 short sentences with no filler, front-loading the resource and the paging trait. It is efficient, though arguably terse enough to leave useful routing information unsaid.

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 no output schema, the description never indicates what an airport record or a page of results contains, nor how many records roughly come back. Annotations plus the rich parameter schema cover enough to call it correctly, but the return-shape gap keeps it at minimum-viable.

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 all three parameters (view, cursor, max_pages) carry detailed inline descriptions, so the baseline is 3. The description's single mention of the cursor duplicates what the schema already explains in more depth.

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?

"List airports known to AeroAPI" gives a specific verb+resource that is clearly the enumeration counterpart to fa_get_airport, fa_resolve_airport and fa_get_nearby_airports. It does not explicitly name how it differs from those siblings, but the plural list scope is unambiguous.

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 only guidance is "Use the cursor to page through," which is an invocation mechanic the cursor schema already covers. There is no statement of when to reach for this bulk listing versus fa_get_airport, fa_resolve_airport, or fa_get_nearby_airports, and no exclusions or prerequisites.

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=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context by specifying the required AeroAPI tier and the exact error (401) for the free Personal tier, which an agent cannot infer from 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?

Two sentences with zero waste: the first states the action front and center, and the second delivers a critical prerequisite. Every sentence earns its place.

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?

Given the simple list operation, three optional parameters fully documented in the schema, and annotations covering safety and open-world access, the description is nearly complete. It omits any hint about return shape, which would be marginally useful since there is no output schema, but the missing detail is minor for this operation.

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 schema fully documents the view, cursor, and max_pages parameters. The description adds no additional parameter meaning, consistent with the baseline 3 when the schema does all the work.

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 verb ('List') and resource ('flight alerts configured on your AeroAPI account'), making the scope clear. It does not explicitly contrast with sibling tools like fa_get_alert (singular retrieval) or fa_create_alert, so sibling differentiation is missing.

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 by naming the operation ('List the flight alerts') and provides a prerequisite about account tier, but it gives no guidance on choosing between this and related sibling tools such as fa_get_alert or fa_get_alerts_endpoint. The tier note is a helpful constraint but not a comparison to 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=true and openWorldHint=true, so the safety profile is covered. The description adds that results are paged and cursor-driven, which is genuine behavioral context, but says nothing about result volume, ordering, or what happens when the cursor expires. Adds some value over annotations, nothing rich.

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 short sentences, purpose front-loaded, zero filler. Every clause carries information and nothing is buried.

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 no-required-param list tool with readOnly annotations and no output schema, this covers the essentials but is thin: it never describes what an operator record returns or how results are ordered. Adequate to call, but not 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?

Schema description coverage is 100%, so the schema already fully documents view, cursor, and max_pages including the billing rationale behind the 20-page cap. The description only reinforces "cursor" for paging and adds no format or semantics beyond what the schema provides. 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 ("List") and resource ("operators (airlines)") scoped to AeroAPI, and the parenthetical disambiguates operators as airlines. It is clearly distinct from fa_get_operator in form, but the description never names that sibling, so the agent must infer the singular-vs-list distinction from the name alone.

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?

"Use the cursor to page through" is mechanical guidance about a parameter, not a statement of when to use this tool versus alternatives like fa_get_operator. There is no mention of prerequisites, when-not-to-use, or which sibling to reach for.

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?

With readOnlyHint=true and openWorldHint=true already in annotations, the safety profile is covered. The description adds genuine behavioral context beyond that: the tier requirement and the specific 401 failure mode, informing an agent that a 401 is an expected eligibility outcome rather than a tool malfunction. This is a meaningful disclosure for a tool with auth-dependent behavior.

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 zero filler: the core function is front-loaded, and the operational constraint follows as a clearly marked NOTE. Every word earns its place; the structure makes the key facts instantly scannable.

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 3-param, 1-required resolution tool with fully documented params and read-only annotations, the description covers purpose and the key failure mode. The main gap is that 'equivalents' is undefined and there is no output schema, leaving the response shape underspecified for an agent trying to interpret the result. openWorldHint() mitigates this somewhat.

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%: id, view, and id_type each carry descriptive schema text, including enum meanings and the compact/full response-shape difference. The description itself contributes no parameter details, so the baseline 3 applies — the schema does the heavy lifting.

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 uses a specific verb ('Resolve') with a specific resource ('airport code') and a concrete outcome ('canonical AeroAPI identifier (and equivalents)'). This clearly differentiates it from sibling lookups like fa_get_airport or fa_resolve_flight, which operate on different resources. The scope is unambiguous even before inspecting the 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?

There is no guidance on when to choose this tool over siblings — e.g., use fa_get_airport when the ID is already canonical, or fa_resolve_flignt for flight identifiers. The only usage-relevant note is the AeroAPI tier eligibility (Standard/Premium required, free tier returns 401), which is an operational constraint rather than an alternative-routing rule. An agent must infer selection criteria from the name alone.

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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses a concrete auth constraint — Standard or Premium tier required, free Personal tier returns 401 — which is exactly the kind of operational context annotations cannot carry. It also describes the return payload shape, though it omits rate-limit or error-handling detail.

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 zero padding: the purpose is front-loaded and the tier caveat follows. Every clause earns its place and nothing is redundant with the schema.

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 no output schema, the description takes on the burden of describing the return and does so (canonical form, alternate idents), and it flags the tier/auth failure mode. It is complete enough to call correctly; the only gap is richer detail on failure modes beyond the 401 case.

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 schema already documents ident, ident_type, and the view enum in detail (including the compact/full trade-off). The description's mention of "designator/registration" adds only marginal framing over the ident_type enum, 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 ("Resolve a flight ident") and even names what comes back (canonical form plus alternate idents), which lets an agent distinguish it from the flight-fetching siblings like fa_get_flights and fa_search_flights. It stops short of explicitly contrasting itself with fa_resolve_airport or the search tools, so it is clear but not fully differentiated.

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 canonicalization goal implies the use case (normalize an ident before issuing other calls), which is a reasonable implied-usage signal. There is no explicit when-to-use/when-not statement and no alternatives named, so an agent must infer that this precedes a lookup rather than replacing one.

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=true and openWorldHint=true, so safety is covered. The description adds genuinely useful non-annotation context: the required query grammar family, that output is position points rather than summaries, and a concrete example. It omits any note on billing/rate limits, which is left to the schema's max_pages text.

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 dense sentences: purpose first, grammatical constraint second, distinguishing return semantics third, closed with one minimal example. No filler and the most decision-relevant information is front-loaded.

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 no output schema, the description correctly compensates by stating the return shape ('position points rather than flight summaries'), and pagination/response shape are covered by the schema. It stops short of describing the position-record contents, so an agent knows the category but not the fields.

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 every parameter is already documented well in the schema (view, cursor, max_pages are all richly described there). The description only restates the query grammar, which the schema already carries, so it adds no meaning beyond structured data — 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+resource (search live flight positions) and immediately distinguishes the result type from siblings: 'Returns position points rather than flight summaries.' An agent can separate this from fa_search_flights and fa_search_flights_advanced 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?

It names the query grammar relationship explicitly — use the structured '{operator key value}' form, same as fa_search_flights_advanced, and NOT the simplified '-key value' syntax — which is real routing guidance between siblings. It does not, however, say when to prefer this over fa_get_flight_position or fa_get_flight_track for a single flight.

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=true and openWorldHint=true, so the safety and external-data profile is covered. The description adds that results are limited to currently airborne flights (an instantaneous-state trait) but says nothing about billing implications, result freshness/latency, or pagination behavior beyond what the schema already notes for max_pages. Adequate but thin.

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?

Purpose is front-loaded in the first clause, followed by the necessary key enumeration and a concrete example. Given that the schema does not document the query grammar, the key list earns its space; the dash-prefixed list is dense but readable.

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?

No output schema exists, yet the schema's view param explains response shaping, and the description fully covers query construction, which is the hard part of calling this tool. The main gap is that it never positions itself against fa_search_flights_advanced or the position/history search siblings, which matters given how many similar tools exist.

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 schema's own description of the required 'query' param is minimal ('Simplified "-key value" search string'), so the description carries real weight by enumerating every supported key and giving a worked example. This goes meaningfully beyond the structured field. Only the latlong sub-grammar and -filter values are lightly specified.

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 scope: 'Search airborne flights'. The word 'airborne' usefully narrows it to live in-flight traffic, distinguishing it from airport/operator/history siblings. However, it never contrasts itself with the closely named fa_search_flights_advanced or fa_search_flight_positions, so the sibling boundary is left to inference.

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?

There is no when-to-use guidance, no stated preconditions, and no routing to alternatives. The most relevant sibling, fa_search_flights_advanced, is never mentioned, so an agent cannot tell which search tool to pick. Only the implicit 'airborne' scoping hints at usage.

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=true and openWorldHint=true, so safety is covered. The description adds substantial behavioral context the annotations do not: the predicate syntax, the full operator set, and the meaning/units of common keys (alt in hundreds of ft, ICAO codes, airline 1=airline/0=GA). It does not discuss auth, rate limits, or result ordering, so it is not exhaustive.

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 dense, front-loaded paragraph: purpose and sibling comparison first, then syntax, operators, and keys. No filler sentences, and every clause carries usable information for constructing a query.

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?

No output schema, but the description plus the `view` param description cover the response shape, and pagination is covered by the cursor/max_pages schema descriptions. For a read-only search tool the description is complete enough to invoke correctly; it only omits result ordering/limits and error behavior.

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 baseline would be 3, but the description meaningfully enriches the `query` parameter beyond the schema's single example by enumerating operators (true/false/null/notnull/=/!=/</>/<=/>=, match/notmatch, range, in/orig_or_dest/...), value-list syntax, and key semantics. It adds real syntax knowledge the schema does not carry.

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+resource (search flights) and immediately differentiates from the sibling by calling out the full structured query language as 'more expressive than fa_search_flights'. An agent can pick this apart from fa_search_flights without opening either 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?

The comparison to fa_search_flights gives clear context for when this tool is the right choice (complex/expressive predicates). It stops short of an explicit 'use fa_search_flights for simple text searches' routing statement or any exclusion, so it is context without full when/when-not guidance.

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 declare destructiveHint=true, idempotentHint=true and openWorldHint=true, but the description adds genuinely new behavioral facts: the first call makes NO network call and returns a preview plus confirmToken, the repeat call is required to proceed, the elicitation toggle (MCP_CONFIRM_ELICITATION/MCP_CONFIRM_MODE) changes the flow, and the 401 tier gate. This is context the structured fields cannot convey.

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 purpose is front-loaded in the first clause, followed by the confirmation mechanics and the tier constraint in a logical order. The confirmation sentence is dense and parenthetical-heavy, but every clause carries actionable information rather than 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 no output schema, the description compensates by describing the phase-1 response contents (method, path, body, confirmToken) and the conditions under which it is returned. Auth/tier requirements and the mutation's confirmation gate are both covered, leaving nothing essential an agent needs to call it safely.

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 required `url`, the `format` enum, and the `confirmToken` contract are already fully documented in the schema. The description restates the token's purpose ('only a repeat call with that token proceeds') but adds no format, constraint, or default information beyond it. 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?

The opening sentence names a specific verb and resource: 'Set the delivery (webhook) endpoint AeroAPI POSTs alert notifications to.' This clearly separates it from the sibling getter fa_get_alerts_endpoint and the alert CRUD tools (fa_create_alert, fa_update_alert), so an agent can route without opening any 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?

It gives strong conditional guidance on the confirmation path (elicitation-capable client vs two-step confirmToken fallback) and states the tier prerequisite (Standard/Premium; free Personal returns 401). It never explicitly names an alternative tool to use instead, so it stops short of the 5-level when/when-not/alternatives triangle.

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?

Despite annotations covering the safety profile (destructive/idempotent/openWorld), the description adds substantial context the structured fields cannot: the two-phase confirmation flow, the elicitation-vs-confirmToken fallback, the fact that the first call makes NO network call and only returns a preview, and the Standard/Premium tier requirement (401 on free tier). This is exactly the behavioral disclosure that helps an agent call it safely.

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 core purpose is front-loaded and no sentence is truly wasted given the confirmation complexity, but the single dense paragraph with nested parentheticals (MCP_CONFIRM_ELICITATION, MCP_CONFIRM_MODE) is heavier than it needs to be and could be broken into shorter statements.

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 destructive 16-parameter mutation with no output schema, the description covers the confirmation protocol, no-op first call, tier gate, and replacement semantics. It is close to complete; it could be slightly clearer on how unspecified fields are handled on replacement, but 'replaces its configuration' largely covers that.

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% across all 16 parameters, so the schema already documents id, confirmToken, filters, and notification flags in detail. The description adds framing for confirmToken's lifecycle but no per-parameter meaning beyond what the schema provides, so 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?

States a specific verb+resource ('Update an existing flight alert') and adds a semantic qualifier ('replaces its configuration') that distinguishes full-replacement behavior from a partial edit. An agent can separate it from fa_create_alert, fa_delete_alert, fa_get_alert, and fa_list_alerts on the action alone.

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 establishes that the target must be an existing alert and adds tier/prerequisite context, but it never names an alternative sibling or states when NOT to use it (e.g. create vs update vs delete). Usage is implied by the verb rather than explicitly routed.

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