SOS Flights

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

Annotations already declare readOnly/idempotent/non-destructive, so those are free. The description still adds real value by clarifying the output is informational links with no booking side effect, and by disclosing the ~100-airport geographic coverage so the agent knows the failure mode when an airport is unsupported.

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

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

Three sentences, front-loaded with the primary capability and closing with scope limits. Dense but readable; the EU/UK compensation clause is a distinct capability packed into the same sentence, which cost a little clarity.

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 need no explanation, and the description covers scope, no-booking behavior and geographic limits. The one gap is that sibling routing against sos_find_alternatives and sos_check_rights is left for the agent to infer.

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

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

Schema coverage is 100%, and the description names the exact need categories (hotel, lounge, transfer) that map to the enum values and states the tool is airport-scoped. It corroborates rather than repeats, so it slightly exceeds the baseline 3.

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 (Lists) and concrete resources (hotel/lounge/transfer links, alternative airports, EU/UK compensation rules) for a clearly scoped subject (an airport). It distinguishes itself from the case/message siblings, but the overlap with sos_find_alternatives on 'nearby alternative airports with directions' is never acknowledged or resolved.

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 context is implied: use it when a traveller is stuck at an airport and needs accommodation, lounge or transfer options. 'Links only, nothing is booked' usefully bounds expectations, but there is no explicit when-to-use versus sos_find_alternatives or sos_check_rights, despite the description touching both of their domains.

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, closed-world), so this is a safe deterministic lookup. The description adds real value by disclosing the shape of the answer — applicable law, up to three remedy options, care owed, a compensation range with conditions, warnings — plus the 'not legal advice' limitation, which the annotations cannot convey.

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

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

Two sentences, front-loaded with the core purpose, followed by a compact inventory of the return contents. The output enumeration is slightly list-heavy but each item (law, options, care, compensation, warnings, disclaimer) carries distinct information.

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

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

With 13 parameters fully described in the schema, complete annotations, and an output schema present, everything the agent needs is available. The description still front-loads scope and the legal-advice caveat, so nothing material is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented with format hints (IATA codes, minutes, enum meanings). The description only echoes the disruption categories (cancellation, delay, overbooked, missed connection) that map to the type enum, adding no new parameter-level meaning. Baseline 3 is appropriate.

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

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

States a specific verb (checks) and resource (a flight disruption) and names the three legal regimes it evaluates against. It is clearly distinguishable from the sibling tools, which are case/message/alternatives utilities rather than rule-evaluation.

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

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

Usage is implied by the framing (check rights first, then presumably prepare a case or message), and the 'advice only, not legal advice' note sets expectations. However, it never says when to call this instead of sos_prepare_case or sos_desk_script, nor what prerequisites (e.g. an open case) may apply.

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 behaviour, so the safety profile is covered. The description adds genuinely useful context beyond that: output length (1-3 sentences), tone (short, polite), localisation (traveller's language) and that the output cites the applicable regulation.

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

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

Two tight sentences, front-loaded with the artifact produced and immediately followed by its scope and constraints. No filler or repetition of the schema.

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

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

Given an output schema exists and the 14 parameters are fully documented, the description covers what the agent needs to know about the product. It could say slightly more about available script variants (re-routing vs care vs refund) to help routing, but nothing essential is missing.

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

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

Schema description coverage is 100% across all 14 parameters, including clear descriptions and enums for type, cause and lang. The description only loosely echoes these (language, the regulation context) without adding syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+artifact ('writes 1 to 3 short, polite sentences') and the scenario it serves ('for a traveller to say to the airline agent'), which is clear and concrete. It doesn't explicitly differentiate itself from siblings like sos_prepare_message or sos_check_rights, so an agent must infer the boundary, but the purpose itself is unambiguous.

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

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

The desk-facing framing ('to say to the airline agent') implies when to use it, and the mention of 're-routing, care or a refund' hints at the situations covered. However, there is no explicit statement of when to pick this over sos_prepare_message or when to call sos_check_rights first.

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, open-world, non-destructive, so the safety bar is low. The description still adds real behavioral detail beyond them: results ordered by earliest arrival, prices in EUR, local times per airport, 10-per-page paging, rail links only under 1,200 km, and the explicit 'Nothing is booked' reassurance.

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 resource, then two short sentences for paging/timezone and the no-booking guarantee. Every clause carries information an agent needs; there is no filler.

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

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

An output schema exists, so return values need not be explained, and the description covers scope, ordering, units, paging, geography and safety. Only the missing explicit usage trigger keeps it from being fully complete.

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

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

Schema description coverage is 100%, so all six parameters are already documented (date window, limit range and default, cursor, IATA patterns, nearby-airport default). The description only echoes a few of these (300 km radius, 10 per page) and adds no new syntax or format meaning, so the baseline 3 applies.

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

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

States a precise verb and resource (searches live one-way flights) plus scope: origin, nearby airports within 300 km, a single date. The ordering rule and output fields are named, so an agent can distinguish this from the case/message siblings without opening any schema.

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

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

Usage is implied through the scenario framing ('from the traveller's airport', 'one date', one-way), which tells the agent the context in which the tool applies. However, there is no explicit when-to-use statement, no prerequisites, and no named alternative or when-not 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 the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description need not re-explain safety. It does add behavioral value by disclosing the exact payload: active state, team's recommended solution, last 10 chat messages, and case page link. With an output schema present, this is useful but not essential context, so a 3 fits.

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 a single front-loaded sentence with no redundant preamble. The clause structure is slightly dense but each element earns its place by naming a distinct returned field.

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

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

For a read-only lookup tool with a complete annotation safety profile and a return schema, the definition is essentially complete: it names the input selector and summarizes the key return fields. Only the absence of explicit sibling routing keeps it from a 5.

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

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

Schema description coverage is 100%, so the schema already documents both case_code (with pattern and example) and lang (with enum and default). The description only restates that lookup is 'by its case code' and adds no format or syntax detail beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Returns the status of an SOS Flights case by its case code.' It clearly enumerates what status encompasses (active state, recommended solution, last 10 chat messages, case page link). It does not explicitly distinguish itself from siblings like sos_open_case or sos_prepare_case, so it stops 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?

Usage is implied rather than stated: the tool looks up an existing case by case code. There is no explicit when-to-use, no when-not, and no routing to alternatives such as sos_open_case for creating a case or sos_find_alternatives. The agent can infer the context but gets no direct 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?

Beyond the annotations (which already declare non-read-only, idempotent, non-destructive, open-world), the description discloses the two distinct outcome paths: a payment link where the case only becomes active after payment, versus an access-code path yielding an active case. That is real behavioral context 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?

Two sentences, front-loaded with the action and its prerequisite. The second sentence is dense with return-value detail but every clause carries information about the divergent outcomes.

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 the prerequisite step, the human confirmation gate, and both post-call states. Return values are additionally explained despite an output schema existing, so nothing critical 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 description coverage is 100%, so both parameters (confirmation_token, idempotency_key) are already fully documented, including the 15-minute validity and retry semantics. The description only restates that the token comes from the prepare step, which the schema already conveys.

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 ('Opens the case') and ties it to the artifact produced by a named sibling step ('prepared with a confirmation_token'), so an agent can distinguish it from sos_prepare_case and sos_get_case without opening any schema.

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

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

Gives a clear precondition sequence: the case must have been prepared and the traveller must have confirmed it before this call. It does not explicitly name an alternative or a when-not case, but the ordering against sos_prepare_case is unambiguous.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), and the description adds genuinely new behavior: nothing is created or charged, no account is required, the token expires in 15 minutes, and pricing is a one-time fee or waived by a valid access 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?

Three dense sentences that front-load the operation, then the return payload, then the non-side-effect guarantees. No filler or redundancy.

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

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

With an output schema present, the description need not detail return structure, yet it still summarizes the returned payload (submission preview, price, confirmation_token). The one gap is not routing the agent to the sibling that actually opens the case after the token is obtained.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by tying access_code to the price outcome (fee vs covered) and lang to the payment/case pages. It still does not clarify channel, phone, or email semantics beyond what the schema already states.

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

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

The description gives a specific verb and resource ('Checks the details for a case handled by the SOS Flights team') and enumerates the scope (rebooking help, hotel, evidence, follow-up). It implies a dry-run/preview distinct from sos_open_case via 'Nothing is created or charged', but never names the sibling that actually creates the case.

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?

Clear context for when this applies: a pre-submission check with no account needed and no charge, which tells the agent this is the step before committing. It stops short of explicitly naming the alternative (sos_open_case) or stating when not to use 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?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely non-structured behavior: the returned confirmation_token is valid for 15 minutes, and the tool operates only on an 'active chat case.' The 15-minute expiry is a material operational constraint an agent could not infer.

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 tight sentences with no filler; the core behavior (check, return token, send nothing) is front-loaded and the WhatsApp exclusion is a brief trailing 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-value documentation is unnecessary, yet the description still explains the sole meaningful output artifact (the token and its lifetime). Combined with annotations and full schema coverage, nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema itself. The description reinforces that the message is the traveller's own words and implies the case must be an active chat case, but adds no format or validation detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('checks a message ... and returns it with a confirmation_token') and immediately scopes it against the implicit write sibling with 'Nothing is sent.' An agent can distinguish this from sos_send_message without opening either schema.

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

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

'Nothing is sent' clearly frames this as a preparatory step preceding an actual send, and 'WhatsApp cases continue in WhatsApp' provides an explicit when-not condition. It stops short of naming the follow-up tool, leaving the agent to infer that sos_send_message is the next call.

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 write, idempotent, open-world, and non-destructive behavior. The description adds useful outcome context: the team's reply appears in the case status and on the case page, which helps the agent understand what happens after 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?

Two sentences with zero waste, front-loading the action and recipient before the outcome. Every sentence earns its place.

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

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

Given rich schema descriptions, annotations, and an output schema, the description covers the essential workflow and outcome. It could mention what happens if the confirmation token is invalid or expired, but the schema already documents validity, so this is a minor gap.

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

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

Schema coverage is 100%, so the schema already documents both parameters, including the idempotency key's retry behavior and the confirmation token's 15-minute validity. The description adds no parameter syntax or meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb ('Sends'), the resource ('the message prepared with a confirmation_token'), the recipient ('SOS Flights team'), and the precondition ('after the traveller confirmed it'). This clearly distinguishes it from sibling sos_prepare_message, which produces the message and token.

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?

Provides clear workflow context: use after the traveller has confirmed the message prepared in an earlier step. It does not explicitly name sos_prepare_message as the alternative or state when not to use this tool, so it falls short of 5.

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