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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is partly covered. The description adds value beyond that: the environment write-gate flag and the candid warnings 'Not live-validated' / 'Mutation behavior has not been live-tested', which materially affect an agent's willingness to call it. It does not describe the side effects on the invite or friend relationship, so a 4 rather than 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?

It is short and front-loads the endpoint, which is good. However the two warnings 'Not live-validated' and 'Mutation behavior has not been live-tested' say the same thing twice, and the telegraphic fragments make it denser than it needs to be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the annotations cover the safety/idempotency profile. The remaining gaps are the semantics of 'query' and 'confirm_destructive' and what the accept does to the underlying invite state, which keeps it out of 5 territory.

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 0%, so the description must compensate, and it does for two of four params: it names the path key ('invite_id') and points the payload at get_schema('ConnectedFriendsInviteLinkAcceptRequestProto'). That is a useful, actionable pointer, but 'query' and especially 'confirm_destructive' are left completely unexplained for a mutation tool.

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 ('accept' an invite link) and maps it to a concrete endpoint (POST /v1/connected-friends/invite-links/{invite_id}/accept), so an agent can distinguish it from create_friend_invite and get_friend_invite. It doesn't explicitly name those siblings, 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?

It states a hard prerequisite ('requires FLIGHTY_ALLOW_WRITES=true') which is genuinely useful for invocation, but gives no guidance on when to prefer this over checking the invite with get_friend_invite first, nor any exclusions. Usage is implied by the verb rather than spelled out.

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 destructiveHint=true and non-idempotent behavior, and the description adds substantive context beyond them: no automatic retries, no implicit empty changes, and the warning that omitted fields may clear values. The writes-enabled and confirm_destructive gates are exactly the kind of operational detail 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?

The description is front-loaded with the core purpose and then stacks safety-critical facts; every sentence carries information. It is slightly dense and the phrase 'Advanced sync editor supporting all 43 supported actions' is more marketing than specification, which is the only real slack.

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 batch-mutation tool with an output schema (so return values need no explanation), the description covers the essentials: preconditions, the destructive confirmation gate, idempotency/retry behavior, and the risk of partial field clearing. Nothing an agent needs to call it safely appears to be 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 coverage is 0% and the schema itself is an opaque array of free-form objects, so the description has to carry the burden — and it does, explaining that each item holds exactly one action plus an optional RFC3339 timestamp that is generated if omitted, and tying confirm_destructive to destructive action types. It sensibly defers enumeration of the 43 actions to get_schema rather than inlining them.

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 establishes a specific verb (apply a batch of sync change objects) and resource (sync changes with protobuf validation), and it clarifies that each array element is a single-action object. It does not differentiate itself from plausible siblings such as sync_account, import_calendar, or request_bulk_import, so an agent must still infer which tool owns which write path.

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 real prerequisites ('Requires writes enabled', 'Inspect get_schema('SyncChangeRequestProto') and the action's schema first') and a conditional gate ('Delete/remove/revoke/bulk actions additionally require confirm_destructive=true'). It never explicitly says when to choose this over the sibling write tools, so it lands just short of top marks.

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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds meaningful behavioral context beyond that: it is mutating, gated by FLIGHTY_ALLOW_WRITES=true, not live-validated, and the mutation behavior has not been live-tested. This is valuable for an agent assessing risk.

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 front-loaded with the operation and endpoint, which is good. However, 'Not live-validated' and 'Mutation behavior has not been live-tested' repeat the same caveat, so not 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?

An output schema exists, so return values need not be explained. The description covers the write gate, payload schema reference, and validation caveats, but with 0% schema coverage it leaves the query and confirm_destructive parameters unexplained and does not fully describe the invitation creation 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 description coverage is 0% across four parameters, so the description must carry the burden. It helps by naming the required payload schema via get_schema('ConnectedFriendsInviteLinkAcceptRequestProto') and stating that no path parameters are needed, but it does not explain the query or confirm_destructive parameters at all.

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 identifies a specific verb and resource via the tool name and the POST endpoint '/v1/connected-friends/invite-links'. It is clear this creates a friend invite link, but it does not explicitly distinguish itself from sibling tools such as get_friend_invite or accept_friend_invite.

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 provides a clear prerequisite by stating the tool is mutating and requires FLIGHTY_ALLOW_WRITES=true. However, it gives no explicit guidance on when to use this versus sibling tools like get_friend_invite or accept_friend_invite.

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=false, destructiveHint=false and openWorldHint=true; the description adds meaningful context beyond that by disclosing the write-flag prerequisite and warning twice that the endpoint is not live-validated. It still omits what the share link contains, whether it expires, or who can use it, which would be the highest-value behavioral detail for a share operation.

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 short and front-loads the endpoint and mutation flag, but 'Not live-validated' and 'Mutation behavior has not been live-tested' say the same thing twice, wasting one of only five sentences. The external doc reference is also not actionable on its own.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values needn't be explained, but for a four-parameter write endpoint with zero schema coverage the description leaves payload shape, query usage, and the confirm_destructive flag entirely undefined. An agent could not construct a correct call from this definition alone.

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 0% for four parameters, so the description must compensate and largely does not. Saying payload is 'documented in docs/api.md' pushes semantics to an external document, and query and confirm_destructive are never mentioned; 'No path parameters' is the only real parameter guidance, though it usefully signals that the schema's path field should be left null.

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 names the endpoint (POST /v1/share) and the tool name implies creating a share link, so the resource is identifiable. However it never plainly states what a share link is or what it grants, and gives no differentiation from siblings like create_friend_invite or subscribe_shared_flights.

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 usage-relevant information is the prerequisite that FLIGHTY_ALLOW_WRITES=true is required. There is no guidance on when to use this tool versus alternatives, no mention of when-not to use it, and no reference to any sibling tool.

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/non-idempotent, but the description adds critical context beyond them: two required environment gates, an identity match constraint, irreversibility, and the warning that live behavior is deliberately untested. That last point is exactly the kind of risk disclosure annotations cannot carry.

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 short lines: what it does, what it requires, when not to use it. The destructive scope is front-loaded and no sentence is redundant.

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?

Covers purpose, preconditions, identity verification, misuse cases, and testing caveats; an output schema exists so return values need no explanation. Nothing an agent needs to invoke this destructive tool safely 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 coverage is 0%, so the description must compensate — and it does, explaining that confirmation_user_id must exactly match the authenticated token's subject. That is the only parameter and its full semantic constraint is stated.

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 ("Permanently delete this Flighty account") and explicitly disambiguates from the closest sibling by noting it is "separate from removing a flight" (delete_flight). An agent can distinguish it without inspecting 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?

Gives explicit exclusions ("Never use for cleanup or testing") and prerequisites, which is strong when-not-to-use guidance. It does not name an alternative for less destructive account operations (e.g., request_export, get_account_records), so it falls short of the full 5.

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/non-idempotent, but the description adds real behavioral context beyond them: a write-permission prerequisite, a mandatory confirmation-equals-flight_id safeguard, the fact that manual=true swaps in a different deletion action, and that the authenticated account is the implicit owner. That is a meaningful safety and mechanics disclosure for a destructive tool.

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 action and hard prerequisite, which is the right order for a destructive tool. The final sentence about implicit owner omits ownerUserId is somewhat implementation-flavored, and the mid-sentence line break is slightly awkward, but 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?

Output schema exists, so return values need not be described, and annotations plus description together cover the safety profile, prerequisites, and the manual variant. Only minor gaps remain, such as what happens to related subscriptions or tickets when a flight is removed.

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 0%, so the description must carry the param burden and largely does: confirmation must equal flight_id, manual selects deleteManualFlightAction, and ownerUserId is deliberately omitted in favor of the authenticated account. Flight ID format and the consequence of a mismatch are still unspecified, keeping it short of a 5.

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 ('Remove a flight') plus scope ('from this account'), and explicitly rules out the most confusable sibling ('This is not archive'). An agent can distinguish delete_flight from set_flight_archived without consulting 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?

Gives explicit prerequisites ('Requires writes enabled and confirmation equal to flight_id') and disambiguates from archive deletion, plus the manual=true routing rule. It never names the archive sibling tool directly, but the exclusion is unambiguous enough to guide selection.

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 readOnly/idempotent/non-destructive, and the description adds real behavioral detail beyond them: deletion markers are excluded, flight categories are restricted to this account, and token/secret/receipt fields are redacted. These are exactly the caveats an agent needs before trusting returned data, and 'no outgoing account changes are sent' reinforces the safe-read profile without contradicting it.

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?

Four short lines, all doing work, with the core action front-loaded and the caveats and limit following. The category list is slightly padded by 'etc.', but there is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return shape needn't be described, and the description still covers the redaction policy, category discovery, and limit bounds. The remaining gap is the semantics of offset and refresh, which leaves an agent guessing about pagination and cache-bypass 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 description coverage is 0%, so the description must carry parameter meaning; it covers 'kind' via the category enumeration plus the get_schema pointer and bounds 'limit' to 1..200, but says nothing about 'offset' or 'refresh'. With two of four parameters still opaque, the compensation is real but incomplete.

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 ('Read') and resource ('a sync category') and enumerates the categories (tickets, notes, subscriptions, profile, friends, favorites, settings), which clearly separates it from flight-specific siblings like get_flight or list_flights. It falls short of a 5 only because it doesn't explicitly name which sibling to use instead for overlapping 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?

Gives concrete onboarding guidance by telling the agent to discover category names via get_schema('SyncResponseData'), which is the key prerequisite for calling it. It also states the 1..200 limit. It does not state when-not to use this tool or name a direct alternative for account-scoped data, so it stays below 5.

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=true and destructiveHint=false, but the description says 'Mutation behavior has not been live-tested,' which implies this endpoint may mutate state—directly contradicting the read-only annotation. This conflicting signal is more harmful than no signal at all.

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 text is short and front-loads the route, but the final sentence about untested mutation is wasteful and confusing rather than informative. Useful detail about the board's content is missing while misleading text is included.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be spelled out, but with 0% schema description coverage on four parameters and an annotation-contradicting mutation note, the description leaves too much for an agent to infer 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 0%, so the description must carry parameter meaning. It only names the path keys airport_id and direction, leaving query, payload, and confirm_destructive unexplained—especially problematic since confirm_destructive appears on an allegedly read-only tool.

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 names a specific endpoint (GET /v1/airport-board/{airport_id}/{direction}) and labels it a read-only lookup, so the action and resource are identifiable. However, it never explains in plain language what an 'airport board' returns (departures/arrivals, live status, etc.), and it does nothing to distinguish this from siblings like get_airport_status or get_airport_mini_status.

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 get_airport_status, get_airport_mini_status, get_airports_home, or search_airports. The only usage-adjacent statement is 'Read-only lookup,' which describes safety, not selection criteria.

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, idempotentHint=true, destructiveHint=false, so 'Read-only lookup' adds nothing. The trailing note 'Mutation behavior has not been live-tested' is boilerplate that is actively confusing on a GET endpoint and says nothing about response shape, payload size, or error 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?

Very short and front-loaded, but telegraphic rather than efficient – the endpoint string substitutes for a purpose statement and the mutation caveat is wasted words. Nothing is padded, yet little of it 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?

An output schema exists, so return values need not be described, but the description still leaves the 'mini' variant's relationship to its sibling undefined and the non-path parameters undocumented. For a tool whose schema provides almost no guidance, this is under-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?

Schema description coverage is 0%, so the description carries the full burden. It only names one path key (airport_id) and says nothing about the query, payload, or confirm_destructive parameters, leaving three of four inputs unexplained in both schema and description.

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 is essentially the tool name plus its raw HTTP route (GET /v1/airport-status/{airport_id}/mini), which does convey a read of airport status. But it never explains what 'mini' means relative to the sibling get_airport_status, so the agent must infer the distinction from a URL suffix 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?

No statement of when to use this instead of get_airport_status, get_airport_board, or get_airports_home, which are the obvious alternatives. 'Read-only lookup' is the only hint, and it doesn't establish a selection condition.

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, destructiveHint=false and idempotentHint=true, so safety is covered structurally. The description's one added behavioral claim — 'Mutation behavior has not been live-tested' — is confusing next to a read-only tool and a readOnlyHint, and it never explains auth, rate limits, or response shape.

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?

It is short and front-loads the route and read-only note, but the sentences are telegraphic fragments rather than purposeful statements, and the final caveat sentence adds noise more than signal.

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 four parameters at 0% schema coverage, an output schema present, and no annotation gaps to excuse it, the description leaves too much unsaid: two of the four parameters are undocumented and no return-value or pagination context is offered beyond the existence of an output 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 coverage is 0%, so the description must compensate and it only partially does: it constrains 'path' ('No path parameters') and points payload to a proto schema. It says nothing about 'query', nothing about the purpose of 'confirm_destructive' on a read-only tool, and gives no format details.

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 text mostly restates the name plus an HTTP route ('POST /v1/airport-status') and says 'Read-only lookup', but never states what data the tool actually returns or how 'home' airports differ from the many sibling airport tools (get_airport_status, get_airport_board, get_airport_mini_status, get_airports_map). An agent cannot distinguish it from those siblings without trial.

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 and no comparison to alternatives; the only actionable hint is that the payload must match get_schema('AirportsHomeRequestProto'). That is a prerequisite pointer, not usage context, and it leaves the sibling-selection question entirely unanswered.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description mostly repeats read-only status and adds a confusing note that "Mutation behavior has not been live-tested," without clarifying return behavior, auth needs, rate limits, or other useful operational context.

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 short and front-loads the endpoint path, but it repeats the tool name, spends text on an ambiguous mutation caveat, and does not structure the payload guidance clearly. Some content does not earn 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 four parameters, no schema descriptions, and multiple airport-related siblings, the description is not complete enough. It references get_schema for payload but omits what the map contains, how to choose this tool over alternatives, and how query or confirmation parameters work.

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?

With 0% schema description coverage, the description must compensate, but it only covers payload via get_schema('AirportsHomeMapRequestProto') and says there are no path parameters. It leaves query and confirm_destructive unexplained, so two of four parameters remain undocumented.

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 identifies the endpoint and says it is a read-only lookup, but it never explains what an "airports map" actually returns or how it differs from siblings like get_airports_home or get_airport_status. The name/endpoint restatement provides only a vague sense of purpose.

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 the many airport-related siblings. The description only gives endpoint and payload-schema mechanics, not selection criteria 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a confusing hedge — 'Mutation behavior has not been live-tested' — on a tool declared read-only, and a confirm_destructive parameter sits in the schema unexplained, leaving the agent unsure whether the operation is truly safe.

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?

It is short and front-loads the route, but the fragments are cryptic ('path keys: airport_id') and the trailing mutation-tested note spends a sentence without adding usable 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?

An output schema exists, so return values need no explanation, but with 0% parameter coverage, no usage guidance, and a self-undermining mutation caveat, the description does not give an agent enough to invoke the tool confidently.

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 0% across 4 parameters, so the description carries the full burden. It documents only the 'airport_id' path key and says nothing about the query, payload, or confirm_destructive parameters, leaving most inputs undefined.

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 names the HTTP route and labels it a 'Read-only lookup', which conveys that it retrieves status for an airport_id. However, it is largely a mechanical restatement of the endpoint rather than a plain-language statement of purpose, and it offers no differentiation from close siblings like get_airport_board and get_airport_mini_status.

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 statement of when to use this tool, when not to, or which sibling to prefer for airport status variants. The only hint is 'Read-only lookup', which an agent could also infer from annotations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds a live-testing caveat, but the phrasing 'Mutation behavior has not been live-tested' is confusing for a declared read-only endpoint and does not clarify what actually happens on call. With annotations doing the heavy lifting, this is adequate but muddled.

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?

It is short and front-loaded with the endpoint identity, which is good. However, the final sentence about untested mutation behavior is boilerplate that adds confusion rather than value for a read-only GET.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the read-only annotations remove the need for extensive risk disclosure. Still, three of four parameters are undocumented and the agent is not told what the path object shape must be beyond one key, leaving meaningful holes for an endpoint tool.

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 0% and the schema exposes only generic path/query/payload/confirm_destructive objects. The description documents just one binding ('path keys: user_id'), leaving query, payload, and confirm_destructive entirely unexplained in both schema and description. For a 4-parameter tool that is a real gap.

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 names a specific verb and resource ('get_avatar: GET /v1/user/{user_id}/avatar'), so an agent knows it retrieves the avatar for a given user. No sibling tool covers avatars, so differentiation is not required. It is essentially the name plus the endpoint path, but that combination 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?

'Read-only lookup' hints at the mode but does not say when to call this versus anything else, nor what preconditions exist (e.g., the user must exist, whether the avatar may be absent). There are no real alternatives among siblings, but no usage context is given either.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds valuable context beyond that: it discloses that app-only TripIt browser flow and websocket protocol metadata are included, and that core flight edits are live-tested with coverage documented in docs/testing.md. That reliability caveat is genuine behavioral information, though it does not describe output shape or catalog size.

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 definition is three sentences and front-loads the core purpose before adding scope and testing notes. Each sentence contributes something, though the docs/testing.md pointer is somewhat tangential and could be trimmed without losing agent-critical 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?

An output schema exists, so the description need not explain return values. For a zero-parameter discovery tool, the description covers what content the catalog includes and notes coverage limitations, which is sufficient to call it correctly. It could be stronger by clarifying its role relative to get_schema, but the essential context is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, and the input schema is empty with 100% description coverage, so there is nothing for the description to compensate for. Baseline 4 is appropriate for a parameterless definition.

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 clear verb and resource: 'List every supported HTTP operation, request/response schema and read/write classification.' It also names specific content areas (TripIt browser flow, websocket metadata), so an agent knows this is a catalog/discovery endpoint. However, it never distinguishes itself from the sibling get_schema, which likely overlaps, 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?

There is no explicit when-to-use guidance, no mention of prerequisites, and no comparison to alternatives such as get_schema. The opening 'List every supported...' implies discovery usage, but nothing tells the agent when this catalog is the right choice versus other schema/introspection tools. This matches the 'no guidance' severity level.

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 (readOnly, idempotent, non-destructive, open-world), so the description earns credit for going further: it discloses that the payload may include allFlights, traveler profiles, manualFlights and airport-status data, and that account tokens are redacted. It omits any error/not-found or partial-response behavior, keeping it below the top mark.

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, front-loaded with the action and the key scope constraint, with no filler. The secondary sentence is reserved for payload/redaction facts an agent cannot get from structured fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with full annotations and an output schema, the description covers purpose, identifier type, non-mutation guarantee and payload sensitivity. Nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries the burden; it does add that the identifier is a UUID tied to GET /v1/flight/{id}, which is more than the bare 'Flight Id' string title. It still doesn't state the expected format (canonical UUID string) or what happens with a malformed/unknown id.

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 (fetch) and resource (a flight, by UUID) and pins the source endpoint, so an agent can distinguish it from list_flights, search_flights, poll_flight and subscribe_flight without opening a schema. The clause 'Does not add the flight' explicitly separates it from the create/upsert siblings.

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?

'Fetch a flight by UUID' tells the agent the precondition (an existing flight_id) and 'Does not add the flight' names one when-not case. No sibling alternative is named for the case where the agent has no UUID (e.g. search_flights), so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description's "Read-only lookup" merely repeats structured data. The added note that "mutation behavior has not been live-tested" is boilerplate that is confusing for a GET endpoint, contributing little real behavioral context.

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 and short, but the leading "get_friend_invite:" merely repeats the tool name, and the trailing "Mutation behavior has not been live-tested" is boilerplate of questionable value here.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values needn't be explained, but the generic wrapper schema at 0% description coverage leaves query/payload/confirm_destructive unexplained, and the description compensates for only one of the four parameters.

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 0% and all four parameters (path, query, payload, confirm_destructive) are undocumented generics. The description usefully clarifies that the path object should carry invite_id, but says nothing about query, payload, or why confirm_destructive exists on a read-only tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (GET the invite link for a given invite_id) and the HTTP endpoint, which makes it clearly a retrieval operation versus siblings like create_friend_invite or accept_friend_invite. It doesn't explicitly name those siblings, 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?

"Read-only lookup" implies the tool is for fetching an existing invite rather than mutating it, which implicitly routes the agent away from create/accept siblings. But there's no explicit when-to-use guidance, prerequisitives, or named 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, idempotentHint=true and destructiveHint=false, so "Read-only lookup" adds nothing. The trailing caveat "Mutation behavior has not been live-tested" is boilerplate that is confusing on a read-only endpoint and gives no real behavioral detail (no rate limits, auth needs, or pagination).

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?

It is short and front-loaded with the route, which is good. But the three sentences are boilerplate scaffolding rather than substantive content, so brevity comes at the cost of usefulness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. However, with a generic path/query/payload envelope and zero schema coverage, the agent has no idea what to put in query to actually retrieve radar layers—the core thing this definition needed to supply.

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 0% across four parameters, so the description must compensate and does not. It only says path is unused; the query, payload, and confirm_destructive parameters—including what query keys the /radar/layers endpoint accepts—are left entirely undocumented.

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 essentially restates the tool name and its HTTP route ("get_radar_layers: GET /v1/radar/layers"). It never says what a radar layer is or what data the caller gets back, so it cannot be distinguished from sibling lookups like get_avatar or get_schema beyond the URL string.

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 call this versus the many other GET-style siblings, and no prerequisites or conditions. The only usable cue is "No path parameters," which constrains invocation but not tool selection.

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 read-only, idempotent, non-destructive, and non-open-world behavior. The description adds useful behavioral detail about empty/partial name matching, full-name contracts, ProtoJSON conventions, and explicitly states that no network requests are performed.

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 front-loaded with the tool's purpose, followed by name semantics, an example, ProtoJSON context, and the no-network boundary. The sentences are dense but every one adds useful 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?

Given that an output schema exists and annotations already describe safety properties, the description provides enough context to call the tool correctly and interpret the relevant payload conventions. No critical information is missing for this schema-introspection tool.

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 for the single name parameter is 0%, so the description must compensate. It does so by explaining that empty/partial names list matching definitions, full names show the complete field contract, and it provides a concrete fully qualified example. Exact matching details such as case sensitivity remain unstated.

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 and resource: inspect supported protobuf fields, numbers, types, enum values, and oneof groups. It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools like get_endpoint_catalog.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains how empty, partial, and full names behave, which implies usage. However, it does not explicitly say when to use this tool versus alternatives or name any 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=true and idempotentHint=true, so restating 'Read-only lookup' adds nothing. The line 'Mutation behavior has not been live-tested' is confusing on a tool annotated read-only and does not clarify permissions, rate limits, or response 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?

Short and front-loaded, which is good, but the brevity comes from omission rather than efficiency and one sentence (the mutation note) is wasted or misleading.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, but the description leaves the generic path/query/payload parameters undocumented and never states what the endpoint actually returns. For a four-parameter open-world tool this is incomplete.

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 0%, so the description must compensate, and it only partially does by stating 'No path parameters'. That claim sits awkwardly against the schema's explicit 'path' property, and the query and payload fields are left entirely unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives an HTTP verb and endpoint path ('GET /v1/static_assets') plus a vague gloss ('read-only lookup'). It names a resource but does not explain what static assets are or how this differs from any sibling, so an agent cannot tell it apart from get_schema or get_endpoint_catalog.

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 exclusions, and no named alternative among the many sibling retrieval tools. The only constraint offered is 'No path parameters', which is a parameter note rather than usage 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 already declare destructiveHint=true and idempotentHint=false, and the description usefully adds that the operation requires FLIGHTY_ALLOW_WRITES=true and has not been live-validated. It does not contradict the annotations, though it stops short of describing exactly what gets destroyed or how the mutation affects existing calendar 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?

The description is short and mostly front-loaded, but "Not live-validated" and "Mutation behavior has not been live-tested" duplicate the same warning. The endpoint and path-parameter details are useful but not maximally 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 destructive import tool with four undocumented parameters and a required write flag, the description is too thin. The output schema exists so return values need not be explained, but the description still omits what is imported and how query/confirm_destructive affect 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 description coverage is 0%, so the description must carry the full burden for four parameters. It only addresses payload via a schema reference and says there are no path parameters, leaving query and confirm_destructive unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description mostly restates the tool name and HTTP endpoint ("import_calendar: POST /v1/sync/calendar") without explaining what importing a calendar actually does. It does not distinguish this from siblings like request_bulk_import or sync_account, and the only added meaning is that the operation is mutating.

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 a prerequisite (FLIGHTY_ALLOW_WRITES=true) but no guidance on when to use this tool versus alternatives such as request_bulk_import or sync_account. There are no exclusions or contextual cues for selecting import_calendar.

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?

Adds real context beyond the annotations: it states the write flag requirement, warns 'Not live-validated', and flags that initiator token issuance/merge semantics are unverified — exactly the kind of caveat an agent needs before a destructive write. It stays consistent with destructiveHint=true and idempotentHint=false, though it never says what state is overwritten or what a merge does.

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-loads the endpoint and mutating/write-flag status, then adds caveats — every sentence carries signal. The closing 'merge semantics remain unverified' is slightly terse/cryptic, but it is not padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained; the description instead covers the risky parts — mutability, required write flag, auth model, validation status. The main residual gap is that it never explains how confirm_destructive should be used on this destructive call.

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?

With 0% schema coverage across 4 params, the description does useful work: it explicitly negates the path parameter and points payload at get_schema('UserLinkRequestProto'), and explains the body token's role. It says nothing about 'query' or, more importantly, 'confirm_destructive', which is a notable omission for a destructive operation.

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?

Names a specific verb+resource ('link_account') and pins it to a concrete endpoint (POST /v1/user/link), plus clarifies the auth/approval-token mechanic. It does not differentiate from nearby siblings like accept_friend_invite or register_anonymous_user, so an agent still has to infer the boundary.

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 a hard precondition (FLIGHTY_ALLOW_WRITES=true) and distinguishes the approving account from the body token, which is genuine usage context. However, it never says when to prefer this over sibling flows such as accept_friend_invite or sync_account, and offers no 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description still adds real value beyond them: result ordering (departure time, earliest first), local pagination over a cached sync, the 1..200 limit bound, timezone semantics for date filters, and that details=true returns the full decoded record.

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-loads the resource and scope, then layers filtering, ordering, pagination and detail behavior in short declarative sentences. Dense but every sentence contributes; the final 'details=true' clause could have been folded in more cleanly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the read-only annotations cover safety. However, for an 11-parameter tool with zero schema descriptions, three parameters ('when', 'archived', 'refresh') get no explanation at all, and the dependency on a prior account sync is only hinted at.

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?

With 0% schema description coverage, the description carries the burden and does so for most parameters: mine_only semantics, date format and timezone, airport text-matching rules, limit range, offset-as-pagination, and details. It leaves 'when', 'archived' and 'refresh' unexplained, so it is strong but incomplete across all 11 params.

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: 'List this account's current flights, including archived history and manual flights', plus explicit exclusions (server deletion markers, other owners' records). It does not name the adjacent siblings (search_flights, get_flight, get_account_records), so an agent must infer the boundary, which keeps it below 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?

Usage context is implied rather than stated: the mention of a 'complete, cached, bodyless account sync' hints that a sync precedes this call but never says so or names sync_account/wait_for_sync. There is no explicit when-not or alternative-selection guidance versus search_flights or get_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, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds useful details (payload must match get_schema('AutocompleteAircraftTypeRequestProto'), no path parameters) but the final sentence 'Mutation behavior has not been live-tested' is confusing given the read-only claim and annotations, without providing actionable clarity.

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 short and front-loaded with the tool name and endpoint, but the sentences are disjointed and the closing mutation note undermines clarity without adding useful context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be covered. However, with 4 parameters, 0% schema coverage, and no usage guidance, the definition is incomplete for an agent to invoke it correctly without extra discovery (e.g., calling get_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 0%, so the description must carry the full burden. It partially addresses 'payload' (referencing get_schema) and 'path' (says none required), but leaves 'query' and 'confirm_destructive' entirely unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Read-only lookup') and the endpoint path ('autocomplete/aircraftTypeFromTail') implies looking up aircraft type by tail number. It does not, however, differentiate this tool from sibling search_aircraft_types, so an agent could confuse the two.

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 or alternative tools are named. The agent is left to infer that this is for tail-number-based lookup versus other aircraft-search siblings, with no exclusions or context.

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 readOnly=false, idempotent=false, destructive=false. The description usefully adds that the operation is mutating, gated behind FLIGHTY_ALLOW_WRITES, and not live-validated — real value beyond the annotations. It stops short of saying what state changes, whether repeat calls are harmless, or what the response contains (though an output schema exists).

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 text is short and front-loads the endpoint, but 'Not live-validated' and 'Mutation behavior has not been live-tested' are redundant restatements of the same caveat. The parameter guidance is squeezed into one run-on sentence rather than structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema and annotations present, the missing piece is the semantic core: what the mutation does, what payload fields the external docs require, and what confirm_destructive means here. Pointing to docs/api.md off-tool leaves an agent unable to construct a correct call.

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 0% for four parameters, so the description must compensate and largely fails. It only says payload is 'the JSON object documented in docs/api.md' (an external pointer) and that there are no path parameters; query and confirm_destructive are never explained, and the confirm_destructive flag on a claimed non-destructive call is left ambiguous.

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 mostly restates the tool name plus the raw HTTP endpoint (POST /v1/user/settings/viewedYearInReview) without explaining what marking the year-in-review as viewed actually accomplishes or affects. An agent gains no more understanding than it would from the name alone, and nothing distinguishes it from the many other user-settings mutation siblings.

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 a precondition (FLIGHTY_ALLOW_WRITES=true), which is an environment gate rather than a when-to-use rule. There is no indication of when an agent should call this versus other account/settings tools, nor any exclusion criteria.

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?

Adds substantive behavior beyond annotations: bodyless content-sync POST, X-Sync-Priority 0 or 10, optional If-None-Match, and 304 mapped to not_modified=true. These details are not present in the annotations or schema and materially affect correct invocation.

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 short sentences, front-loaded with the core distinction and followed by protocol and result details. No sentence is 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?

The tool has annotations covering safety properties and an output schema, so the description need not explain returns or side effects. It covers the key polling semantics, non-subscription behavior, and the routine-read alternative.

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 0%, so the description must carry parameter meaning. It explains etag as If-None-Match and priority as X-Sync-Priority 0 or 10, but flight_id gets no explicit semantic explanation, leaving one required parameter to inference.

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 ('Poll changing flight content') and immediately distinguishes it from subscription/addition. The sibling set contains subscribe_flight and get_flight, and the description makes clear this is neither.

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?

Clearly says it does not subscribe/add a flight and recommends cached list_flights for routine reads, giving a practical alternative. It does not explicitly contrast with get_flight or subscribe_flight, but the usage context is strong.

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 a non-read-only, non-idempotent, open-world operation, and the description adds real context beyond that: an environment write gate and the fact the mutation is not live-tested, which warns the agent of possible surprises. It stops short of saying what is granted on success or what errors surface for an invalid code.

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 first two clauses are front-loaded and waste-free. However, 'Not live-validated' and 'Mutation behavior has not been live-tested' say the same thing twice, costing a third of the sentences for no added signal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. Still, for a four-parameter mutation tool with zero schema descriptions, the definition should explain what confirm_destructive does and what an invalid or already-redeemed code produces; 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 0%, so the description must carry parameter meaning, and it does the single most important thing: it maps the promo code to the path key 'code'. The remaining three parameters (query, payload, confirm_destructive) are left entirely uninterpreted, so the compensation is partial.

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 names a specific verb (redeem) and resource (promo code) and pins it to the exact endpoint POST /v1/user/promocode/{code}/redeem, so the agent knows precisely what the call does. It does not distinguish from any sibling, but no sibling plausibly overlaps with redemption, so the risk of misfire is low.

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 usage guidance is the gating prerequisite FLIGHTY_ALLOW_WRITES=true, which is genuinely useful for deciding whether the call can succeed. There is no statement of when redemption is appropriate versus retrieving the code first (e.g. get_endpoint_catalog), and no failure conditions are listed.

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 the tool as non-readonly, non-destructive, non-idempotent, and open-world. The description adds genuinely new behavioral context: a write-gate environment flag and an explicit warning that the mutation has not been live-tested, which an agent needs before invoking it.

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?

Telegraphic and front-loaded: endpoint, mutation gate, and validation caveat all appear in the opening lines with no filler. The final sentence repeats the 'not live-tested' caveat already implied earlier, which is minor redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is far more complete than the schema alone: it names the exact request proto, the API path, the write gate, and the untested-mutation risk, all before an agent commits. The warning about FLIGHTY_ALLOW_WRITES alone prevents a likely failed call, and the proto reference tells the agent exactly where to look for the body shape.

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?

With 0% schema description coverage, the description must carry the parameter burden. It usefully ties payload to get_schema('CreateUserRequestProto') and rules out path parameters, but says nothing about the query object or the confirm_destructive flag, leaving half the parameters undocumented.

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 concrete verb and endpoint (POST /v1/user) for registering an anonymous user, so the action is identifiable. However, it offers no differentiation from nearby siblings such as register_device or link_account, and the first clause largely restates the tool name.

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 the precondition that FLIGHTY_ALLOW_WRITES=true must be set. There is no statement of when to prefer this tool over alternatives or what situation calls for an anonymous registration rather than an account-linked 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?

Goes beyond annotations by disclosing the write-gate env flag, that the payload schema comes from a separate get_schema call, that there are no path parameters, and that behavior is not live-validated. It does not explain the confirm_destructive flag or what the registration actually does on the server.

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 and short, but the 'Not live-validated' and 'Mutation behavior has not been live-tested' sentences are redundant, and telegraphic fragments ('No path parameters') add noise rather than meaning.

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?

Output schema exists so returns needn't be explained, and the write gate plus payload schema pointer are the key facts. However, for a 4-param mutation with zero schema coverage, the unexplained confirm_destructive flag and absent guidance on payload construction leave real 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 0%, so the description must compensate; it covers payload (defer to get_schema) and rules out path parameters, but leaves query and confirm_destructive completely unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb+resource ('register_device: POST /v1/device'), so an agent knows this registers a device via that endpoint. It does not distinguish itself from other write siblings like register_anonymous_user or link_account, leaving scope ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage through prerequisites (FLIGHTY_ALLOW_WRITES=true, payload must follow CreateDeviceRequestProto) but never says when to choose this over sibling account/device tools, nor when not to call it.

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?

Goes beyond annotations by flagging that writes require an environment flag, that the mutation is not live-validated, and that behavior has not been live-tested — material caveats an agent cannot get from readOnlyHint/destructiveHint. It stops short of saying what happens on partial failure or whether the import can be undone, which matters for a non-idempotent write.

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 and endpoint, then caveats, with no filler sentences. The one flaw is redundancy: 'Not live-validated' and 'Mutation behavior has not been live-tested' say the same thing twice in a five-clause description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the write-flag caveat is present. What is missing for a non-idempotent bulk mutation is basically what a bulk import of and how confirm_destructive interacts with the flagged destructiveHint=false.

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 0% for four parameters, and the description only covers payload (by referencing get_schema) and the absence of path parameters. query and especially confirm_destructive — the safety flag for a mutation whose destructiveHint is false — are left entirely unexplained, forcing the agent to guess.

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-plus-endpoint ('POST /v1/user/triggerBulkImport') and that it is mutating, so an agent knows exactly which operation it is. However, it never says what is being imported (flights? calendar records?) or how it differs from the sibling import_calendar, 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?

Gives a hard prerequisite (FLIGHTY_ALLOW_WRITES=true) and points to get_schema('TriggerBulkImportRequestProto') for payload shape, which is actionable. But there is no guidance on when to choose this over import_calendar or how to handle batching/retries, so usage context 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?

Goes beyond the annotations by disclosing the write-flag gate and, importantly, that the mutation is not live-validated or live-tested — genuinely useful risk context an agent cannot infer from readOnlyHint/destructiveHint alone. It repeats 'mutating' but does not contradict destructiveHint=false, since requesting an export is a non-destructive write.

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?

Terse, front-loaded, and scannable, with the endpoint and write gate stated first. The only waste is near-duplication between 'Not live-validated' and 'Mutation behavior has not been live-tested.'

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 annotations covering safety hints and an output schema covering returns, the description supplies what is missing: the endpoint, write gate, schema lookup path, and validation status. The uncovered 'query' and 'confirm_destructive' parameters are the only notable 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 0%, so the description must carry the load; it usefully rules out path parameters and tells the agent the payload shape comes from get_schema('TriggerExportRequestProto'). However, 'query' and 'confirm_destructive' — the latter non-obvious for an untested mutation — are never explained.

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?

Names the operation and pins it to a concrete endpoint (POST /v1/user/export), so an agent knows this triggers a user-data export rather than any of the flight/airport siblings. What the export actually contains or produces is left implicit from the path, so it falls short of full specificity.

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 write-gate requirement (FLIGHTY_ALLOW_WRITES=true) and the pointer to get_schema for the payload give practical preconditions. But there is no statement of when to prefer this over related tools or what the after-effects are (async job? email? poll with wait_for_sync?), so 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?

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds two things those annotations do not: the 1..100 limit range (the schema declares no min/max) and the purpose of the returned equipment IDs. Matching semantics (exact vs. partial code match) remain undisclosed.

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 short sentences with the core purpose front-loaded, followed by return semantics, then the range constraint. Nothing is redundant and nothing important 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?

With annotations covering behavior and an output schema covering return shape, the description only needs to convey purpose, query modes, and limits, and it does. The remaining gap is the lack of differentiation from lookup_aircraft, which is a nearby sibling an agent could easily pick by mistake.

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 0%, so the description must carry the parameter burden, and it does: 'query' is defined as IATA/ICAO code or model name, and 'limit' is constrained to 1..100 even though the schema only shows a default of 20. It does not state what happens on out-of-range or zero values, so it is not fully compensating.

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 ('Search aircraft type reference data') plus the matching modes ('by IATA/ICAO code or model name'), which is concrete and actionable. It stops short of distinguishing itself from the sibling lookup_aircraft or search_airports, so sibling disambiguation 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?

'Returns equipment IDs for manual flights' implies the downstream use case (manual flight entry), which gives some contextual guidance. However, it never says when to prefer this over lookup_aircraft or the other search_* reference tools, and no exclusions or prerequisites are stated.

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 readOnly/idempotent/non-destructive/openWorld; the description adds that data comes from a cached read-only account reference set and that limit is bounded to 1..100. That is real value beyond the structured fields, though it says nothing about result ordering or truncation 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?

Three short sentences, zero filler, with the core purpose and the important return-value caveat 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?

Output schema exists, so return shape need not be described; the description still surfaces the one returned field an agent must carry forward (airlineId). For a two-parameter read-only search, nothing needed for correct invocation 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 coverage is 0%, so the description must compensate, and it does: it explains the accepted query forms (IATA/ICAO code or name) and the limit range 1..100 that the schema omits. Remainder is minimal for a 2-parameter tool, so this is close to complete for a lightweight search.

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 airlines) plus the accepted inputs (IATA/ICAO code or name) and the key output (airlineId). This distinguishes it cleanly from sibling lookups like search_flights, search_airports, and search_aircraft_types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies when to call it by noting the returned airlineId is required for flight-number searches, i.e. use this as a prerequisite step. It does not name an explicit alternative or exclusion, but the usage context is clear enough to route correctly.

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 readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description still adds non-obvious context: results come from 'cached reference data from a read-only sync' (implying possible staleness) and returns IDs that feed downstream calls. It does not discuss match semantics (prefix vs substring) or ordering.

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 short sentences, front-loaded with what it searches and what it returns. No filler and every sentence carries distinct information (capability, downstream use, data source, bound).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return-value detail is unnecessary, and the description covers matching fields, data source, limit bounds and downstream ID usage. The remaining gap is how query matching works and result ordering/tie-breaking, which matters for a search tool.

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 0% and neither parameter has bounds documented in the schema, so the description carries the load. It defines what 'query' accepts (code, name, city, country) and supplies the missing 'limit 1..100' range constraint, which is genuinely additive.

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 ('Search') plus resource ('airports') and enumerates the exact match fields (IATA/ICAO code, name, city, country). The resource-level differentiation from siblings like search_airlines, search_aircraft_types and search_flights is unambiguous 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?

Explicitly tells the agent what the results are for: 'Returns IDs needed by route searches, airport status and manual-flight edits', which establishes when to call it. It stops short of naming a specific alternative tool or stating exclusions, so it falls short of a 5.

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 carry readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: search is non-mutating with respect to subscriptions, and identifiers must come from lookup tools rather than being guessed. Return shape is covered by the output schema, so nothing is missing there.

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?

Four short sentences, front-loaded with the two search modes, then constraints, then prerequisites. No filler and no repetition of what the schema already states.

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 an 8-parameter tool with zero schema descriptions, the definition leaves real gaps: 'via' is undocumented, and it never states which parameter combinations form a valid call or what happens when both modes' parameters are supplied. The output schema relieves it of return-value explanation, which keeps this at an adequate rather than failing level.

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?

With 0% schema description coverage, the description must carry the params, and it only partly does: it clarifies flight_number is numeric without an airline prefix, that departure_date is YYYY-MM-DD, and that route IDs may be airport or metro (backing origin_kind/destination_kind). The 'via' parameter is never explained, and the relationship between airline_id+flight_number and origin_id+destination_id is only implied by the word 'OR'.

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 (search) and resource (flights), and enumerates the two supported search modes (airline+number vs. origin+destination) plus the date qualifier. It also explicitly separates itself from subscribe_flight by saying search alone does not add or subscribe to a flight.

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 a clear prerequisite workflow: resolve IDs with the airport/airline/metro lookup tools before calling, and warns that searching is not subscribing. It stops short of naming the concrete siblings (get_flight, list_flights, subscribe_flight) as alternatives for non-search intents, so the routing is implied rather than spelled out.

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 read-only, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds only the 'limit 1..100' constraint and says little about result ordering, truncation, or search matching 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 short sentences, front-loaded with purpose and followed by the limit constraint. It is efficient, though the terse 'limit 1..100' phrasing could be slightly clearer about which parameter it constrains.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and annotations are rich, reducing what the description must explain. Still, for a search tool with a required, undocumented 'query' parameter, the description is minimally adequate but does not fully specify search 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 0%, so the description must compensate for both parameters. It usefully documents the 'limit' range as 1..100, which is absent from the schema, but leaves the required 'query' parameter's meaning and matching behavior unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search metro-area reference data') and scopes it to 'multi-airport route searches,' which distinguishes it from airport or airline searches. It is clear enough to identify the tool, though it does not explicitly contrast with search_airports.

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 'for multi-airport route searches' gives a clear usage context that tells the agent when this tool is relevant. It stops short of naming exclusions or pointing to alternatives such as search_airports.

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?

Goes beyond the annotations by disclosing the write-gating requirement ('Requires writes enabled') and clarifying that the operation is a reversible, history-preserving state toggle rather than a removal — context the annotations (readOnlyHint=false, destructiveHint=false) don't convey on their own. Minor gap: no statement about what happens if the flight isn't tracked or is already in the requested state.

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, front-loaded with the action and effect, then the precondition. 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?

For a two-parameter state-toggle mutation with an output schema present and annotations covering the safety profile, the description supplies the essential missing pieces: reversibility, history retention, and the write-gating prerequisite. Nothing critical to correct invocation is absent.

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 0%, so the description carries the burden. It does explain the semantics of the `archived` boolean via 'Archive/unarchive', but says nothing about `flight_id` beyond 'tracked flight' — an agent must assume it is the same ID returned by get_flight/list_flights.

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?

Specific verb pair (archive/unarchive) applied to a named resource (a tracked flight), plus the scope qualifier 'preserving it in account history' that separates it from destructive siblings like delete_flight. It stops short of naming delete_flight explicitly, so the differentiation is implied rather than stated.

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?

'Preserving it in account history' hints that this is the non-destructive alternative to delete_flight, and 'Requires writes enabled' states a precondition. But there is no explicit when-to-use/when-not-to-use statement or named alternative, leaving the agent to infer the routing.

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 one fact beyond the annotations: the write-gate precondition ("Requires writes enabled"), which is meaningful context for a mutation tool. Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered; the description does not explain failure behavior (e.g., what happens for an untracked flight_id) or the tension between the boolean set-state semantics and idempotentHint=false.

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 the action front-loaded and the precondition trailing; no filler. It is efficient, though the brevity edges toward under-specification rather than maximal conciseness.

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 only two simple non-nested parameters and an output schema already present, the tool is low-complexity and the description need not explain return values. It is nonetheless thin for a mutation operation: it omits what "tracked" means, error conditions, and how toggling interacts with existing flight state.

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 0%, so both parameters are bare titles ("Is Mine", "Flight Id") with no documentation. The description's phrase "mark/unmark a tracked flight" only loosely implies that is_mine=true marks and false unmarks, and it says nothing about the expected format or provenance of flight_id. The description therefore fails to compensate for the coverage gap.

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 pair (mark/unmark) and a specific resource attribute (My Flight status on a tracked flight), which is distinguishable from siblings like set_flight_archived or set_flight_note. It stops short of naming those siblings explicitly, so an agent must infer the distinction from the attribute 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?

"Requires writes enabled" gives a concrete precondition for calling the tool, which is real guidance. However, there is no explicit statement of when to prefer this over set_flight_archived or what qualifies as a "tracked" flight, so the agent must infer the rest.

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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so safety is largely covered. The description adds useful context that writes must be enabled and that an empty note clears the field, but does not mention whether changes must be committed via the sibling apply_changes or what error surfaces when writes are disabled.

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 clauses with zero filler, and the core action is front-loaded before the clearing behavior and precondition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists and annotations cover the safety profile, but for a mutation tool the description omits whether the write is immediate or staged (the sibling apply_changes suggests batching) and does not document flight_id at all.

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 0%, so the description carries the burden. It meaningfully explains the 'note' parameter's empty-string semantics, but 'flight_id' is left entirely undefined beyond its name.

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+resource ('Set a flight note') that an agent can map directly to intent. It does not explicitly distinguish itself from siblings like update_ticket, but the resource and verb are 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?

It provides a precondition ('Requires writes enabled') and a behavioral cue ('an empty note explicitly clears it'), which implies how to use it. However, there is no guidance on when to prefer this over siblings such as update_ticket, nor any exclusion or alternative.

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 annotations, it discloses that this is mutating, requires a specific write-enable environment variable, and has not been live-validated. That is useful operational context for a write tool, though it does not describe side effects or confirmation requirements.

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 short and front-loads the endpoint and mutation warning. It has minor redundancy between 'Not live-validated' and 'Mutation behavior has not been live-tested', but is otherwise 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?

An output schema exists, so return values need not be explained, and annotations cover safety hints. However, for a four-parameter mutating endpoint with 0% schema coverage, the description is incomplete on query/confirm_destructive semantics and usage context.

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 0%, so the description must carry the burden. It documents 'flight_id' and points to get_schema('StartLiveActivityRequest') for payload, but leaves the 'query' and 'confirm_destructive' parameters unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies a specific HTTP action and resource: POST /v1/flight/{flight_id}/liveActivity, and the name makes the intended operation fairly clear. It does not explain what a 'live activity' is or differentiate from siblings, but no sibling is obviously confusable.

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 states a prerequisite (FLIGHTY_ALLOW_WRITES=true) but gives no guidance on when to use this tool versus alternatives, nor when not to use it. The only usage constraint is the write-mode gate.

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 annotations, the description discloses that writes must be enabled via an environment flag and that the mutation is neither live-validated nor live-tested — genuinely useful risk context for a non-idempotent, open-world write. It is consistent with readOnlyHint=false, though it never explains the confirm_destructive switch or what the side effects actually are.

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 and short, with the endpoint and mutation warning first. Minor waste: 'Not live-validated' and 'Mutation behavior has not been live-tested' restate the same caveat twice.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema means return values need not be described, but for a mutating, open-world, non-idempotent tool with an entirely undocumented parameter set, the definition leaves the agent guessing about the payload shape and the confirmation flag. Pointing at docs/api.md is not enough 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 0% across four parameters, so the description must carry the load. It covers only two: 'payload' is deferred to external docs and 'path' is explicitly ruled out; 'query' and especially 'confirm_destructive' (the safety-relevant one) are never mentioned.

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?

It names a verb, resource and HTTP endpoint (POST /v1/user/attribute), which tells the agent this submits user attribution data. However, 'attribution' is never defined and the actual effect is delegated entirely to 'docs/api.md', so the agent cannot distinguish the operation from siblings like update_ticket or sync_account without outside reading.

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 conditional stated is a technical prerequisite (FLIGHTY_ALLOW_WRITES=true), not a when-to-use rule. Nothing says which situations call for submitting attribution versus other write tools in the sibling list, and no exclusions are given.

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=false, non-idempotent, openWorld and non-destructive, so much of the mutation profile is structured data. The description adds useful context the annotations do not: the 'writes enabled' account capability requirement and the downstream effect of is_passenger. It does not say what happens on re-subscribing an already-tracked flight, which matters given idempotentHint=false.

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 short lines, front-loaded with the action and the discovery source, then prerequisites, then parameter semantics. No filler, though the trailing 'Sends the app's is_passenger query string' is low-value implementation detail for an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the description covers action, prerequisites, and both parameters. The remaining gap is lifecycle behavior: no mention of how tracking is later removed or changed (set_flight_mine, delete_flight) or what a duplicate subscribe yields.

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 0%, so the description carries the burden, and it does explain the non-obvious boolean: true marks it as your flight, false tracks someone else's, plus the note that it is forwarded as a query string. flight_id is only characterized as a 'known flight UUID' from search_flights, which is adequate but slightly thin on format.

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 concrete verb+resource ('Add/track a known flight') and pins the scope to a flight UUID that already exists, explicitly routing discovery to search_flights. This separates it from subscribe_random_flight and upsert_manual_flight without the agent needing 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?

Gives the entry condition (a known UUID, normally obtained via search_flights) and the operational prerequisite ('requires writes enabled'), which is exactly the gating information an agent needs before calling. It stops short of naming alternatives such as subscribe_random_flight or set_flight_mine or explaining when tracking is preferable to those.

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=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by stating the side effect explicitly ('changes tracked flights') and flagging the prerequisite that writes must be enabled, which annotations cannot express.

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, no redundancy, with the effect and the precondition front-loaded. Nothing could be cut 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?

An output schema exists, so return values need not be described, and the mutation effect plus write prerequisite are covered. However, the description says nothing about how the 'random' flight is selected (scope, duplicate behavior) or what is_passenger does, leaving meaningful gaps for an open-world mutation tool.

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 0% and the single parameter is_passenger is never mentioned in the description, so an agent gets no explanation of what marking a flight as a passenger versus non-passenger means. The only parameter's semantics are left entirely to a bare boolean with a default.

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 ('Add a random flight to the account'), and the word 'random' distinguishes it from the sibling subscribe_flight. It does not explicitly name subscribe_flight as the deterministic counterpart, so the differentiation is implicit rather than stated.

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 write-mode prerequisite ('writes must be enabled') is stated, which is useful, but there is no guidance on when to use this versus subscribe_flight or subscribe_shared_flights, and no exclusions or when-not conditions. Usage is only implied by the tool name and purpose.

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?

It usefully discloses beyond the annotations that the call is mutating, gated behind an environment flag, and not live-validated/tested - a genuine safety signal consistent with readOnlyHint=false and destructiveHint=false. However, it never says what state changes on subscribe (new record created? subscription list entry?), nor anything about error behavior or side effects, which is the key gap for a mutation tool.

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 endpoint and write-gate are front-loaded, but the description wastes a sentence repeating itself: 'Not live-validated' and 'Mutation behavior has not been live-tested' say the same thing twice.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values needn't be described, but for a non-idempotent mutation with zero parameter documentation and no explanation of effect or sibling routing, the description falls short of what an agent needs to invoke 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 0% across 4 parameters, and the description only notes that share_id goes under path. The generic path/query/payload envelopes and the confirm_destructive flag are left entirely unexplained, so calling this correctly requires guesswork.

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 verb and resource via the endpoint mapping (subscribe to a shared flight at /v1/flight/sharing/{share_id}/subscribe), but it mostly restates the tool name as a REST path rather than explaining what subscribing actually does for the user's account. It also fails to distinguish this from close siblings like subscribe_flight and subscribe_random_flight.

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 a prerequisite (FLIGHTY_ALLOW_WRITES=true). There is no statement of when to choose this over subscribe_flight, subscribe_random_flight, or create_share_link, and no when-not-to-use conditions.

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 readOnly/idempotent/non-destructive, and the description adds real behavior beyond them: the underlying POST /v1/sync/full call with no body on every page, and the fact that read refreshes within 60 seconds reuse the last complete snapshot. The cache-window detail is the kind of operational trait an agent cannot infer from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then the endpoint mechanics, then the sibling pointers — a sound ordering with no filler. The capitalized 'NO body' is a stylistic quirk but does carry an instruction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't detail return values, and it still names 'counts and cache metadata'. Combined with sibling routing and cache semantics it is largely complete; the undocumented refresh parameter is the one remaining 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 0% and the single 'refresh' parameter is never named or explained in the description. The 60-second snapshot-reuse sentence only indirectly implies what refresh toggles, so an agent must guess whether refresh=false forces cache use.

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 ('Download all account pages'), plus the scope constraint 'without submitting changes' and the return payload ('counts and cache metadata'). It explicitly disambiguates from apply_changes and get_account_records, so an agent can pick it without opening another 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 negation ('Not the apply_changes tool') and the pointer that get_account_records exposes individual record categories after the download give clear routing context. What's missing is a positive statement of when to prefer this over the sibling wait_for_sync, which also appears in the tool list.

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 readOnly=false, destructive=false and non-idempotent, so the bar is lower, and the description adds genuine context beyond them: it reads fresh ticket data before merging, preserves existing known fields rather than replacing them, and disclaims server-side patch semantics. The "requires writes enabled" note supplies an authorization precondition annotations do not express. It still does not say what happens on a field conflict or the failure mode when writes are disabled.

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 mutation and its field list are front-loaded in the first two sentences, and the read-before-merge caveat follows logically. Almost every sentence earns its place, though "does not claim server patch semantics" is meta-commentary about documentation rather than about the tool's behavior and is the weakest line.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the description covers the hard part: an opaque nested free-form `fields` object, the enum source, merge-vs-replace semantics, and the writes-enabled precondition. What remains missing is guidance on invalid keys or partial failures, which matters for a non-idempotent mutation.

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 0% and `fields` is a bare free-form object with additionalProperties=true and no documented keys, so the description carries the full burden. It discharges that well by listing the five accepted keys (pnr, seatNumber, seatPosition, cabinClass, flightReason) and pointing to get_schema for the enum value sets. It loses a point for leaving per-field value formats and `flight_id` unaddressed.

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 ("Update") with a named resource (ticket) and enumerates the mutated fields (booking reference, seat, cabin, reason), so the agent knows exactly what changes. It stops short of naming a sibling it is not — apply_changes and upsert_manual_flight overlap in scope and are never mentioned — so it misses the 5 mark.

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 two concrete preconditions: inspect RemoteTicket enums via get_schema first, and writes must be enabled. That is real routing guidance toward a sibling tool. However, there is no statement of when to prefer this over apply_changes, upsert_manual_flight, or set_flight_note, so the when-to-use decision 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and non-idempotency, but the description adds meaningful caveats beyond them: the write-flag requirement and the repeated warning that the mutation is not live-tested/validated. Those risk disclosures are genuinely useful, though it doesn't say what the operation returns or what side effects beyond 'mutating' occur.

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?

Telegraphic and front-loaded with the endpoint, mutation flag, and payload requirement in order of importance. However, 'Not live-validated' and 'Mutation behavior has not been live-tested' are redundant and could be a single caveat.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values needn't be described, and the write-flag and payload-schema references are present. Yet with 0% parameter coverage, the undefined query and confirm_destructive parameters leave real gaps for a mutation tool.

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?

With 0% schema description coverage, the description must compensate for four params. It addresses payload (via get_schema('ReceiptRequestProto')) and clarifies 'No path parameters', but leaves query and confirm_destructive entirely unexplained, so compensation is only partial.

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 definition gives a verb and resource ('upload_receipt: POST /v1/receipt') but a receipt of what, for which workflow, is never explained. Beyond the endpoint path and the ReceiptRequestProto reference, it largely restates the tool name rather than clarifying intent.

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 offers a prerequisite ('requires FLIGHTY_ALLOW_WRITES=true') but no guidance on when to use this versus other mutation tools or what a valid call scenario looks like. No alternatives or exclusions are named.

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 annotations declare destructiveHint: false, but the description explicitly warns that 'Omitted fields may clear existing values', which is a destructive update contradicting the annotation. Although the description adds useful context such as write prerequisites and timestamp semantics, the contradiction is a serious behavioral transparency failure.

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 front-loaded with the action and then each sentence adds a necessary prerequisite, identifier, schema pointer, disambiguation, or caveat. There is no filler, and the warning about omitted fields is appropriately highlighted.

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 opaque nested input schema and the presence of an output schema, the description supplies enough context to invoke the tool: writes-enabled requirement, required local IDs, get_schema pointer, timestamp clarification, and the omitted-fields clearing warning. It does not fully document the complete payload, but that is reasonably delegated to get_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?

The schema has 0% description coverage and exposes only an opaque flight object, so the description carries the burden. It lists required local identifiers, disambiguates gateOriginal/Actual and runwayOriginal/Actual as timestamps rather than names, and points to get_schema for remaining fields. It adds substantial meaning, though it does not document every nested field.

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 and resource: create/edit a manual flight using a complete ManualFlightChangeAction payload. It also names key required identifiers, so the agent understands the scope. However, it does not explicitly distinguish this tool from siblings such as apply_changes or other flight mutation tools.

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 provides clear usage context by stating 'Requires writes enabled', listing required local identifiers, and directing the agent to get_schema for additional time/equipment/airline fields. It does not name alternatives or when-not conditions, but the operational 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?

Beyond the annotations, it discloses that the tool registers the bearer with Flighty's websocket session, waits a bounded interval, and invalidates the local account cache if an update arrives. It also warns about unknown rate limits and confirms it does not return the bearer or create subscriptions.

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 short, front-loads the core action, and each sentence adds distinct value: purpose, mechanics/side effect, exclusions, and caution. There is no redundant or filler text.

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 one-parameter wait tool with an output schema and read-only annotations, the description covers purpose, side effects, constraints, and return behavior sufficiently. The only missing comparative routing detail belongs more to usage guidelines than to completeness.

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 0%, and the single timeout_seconds parameter has no schema description. The description supplies a useful wait range ('1..30 seconds'), but it does not explicitly bind that range to timeout_seconds or explain default/overflow behavior.

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 and resource: 'Wait once for a websocket requestSync notification.' It also scopes the tool by saying it does not change account data or subscribe/add flights, which separates it from sibling mutation and subscription tools.

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 clear usage context ('Wait once') and when-not guidance ('Avoid loops; rate limits are unknown', 'does not subscribe/add any flight'). However it does not explicitly name alternatives such as sync_account or poll_flight or state when one should be chosen instead.

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