Untap

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description discloses rich behavioral details: it returns a verdict and claim link, performs AeroDataBox lookups for past flights, handles optional status/delay/arrival fields, flags airport mismatches, defines compensation eligibility (3+ hour delays or cancellations), and requires authentication.

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

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

The description is a single dense paragraph with no wasted words; it front-loads the core purpose and then layers necessary operational details. It could be slightly more structured for readability, but every sentence earns its place.

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

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

For a 12-parameter write tool with no output schema and open-world lookups, the description covers all essential aspects: the mutation side effect, the returned verdict/amount/link, fallback lookup behavior, compensation rules, and authentication. 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 the baseline is 3; the description adds extra meaning by clarifying that the optional status, delay, and actual arrival fields are all looked up when omitted (the schema only mentions lookup for status). It also reinforces IATA code formats, though most parameter details are already in the schema.

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

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

The description states a specific verb ('Adds') and resource ('a flight to the person's Untap account'), plus the outcome ('returns the UK261 or EU261 verdict, the amount and the airline's claim link'). It clearly distinguishes itself from siblings like add_train_journey and check_flight_compensation by combining an add operation with an immediate eligibility verdict.

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

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

The description implies usage through the verb and resource, and gives some context (e.g., 'For past flights Untap checks AeroDataBox flight-status records') plus a prerequisite ('Requires sign-in to Untap'). However, it never explicitly states when to choose this tool over alternatives such as check_flight_compensation, nor does it name any alternatives or exclusions.

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

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

Annotations already declare a non-idempotent, non-read-only, closed-world mutation. The description adds real value on top: auth requirement, the fact that it returns grounds/confidence/route/deadline, and the conditional behavior that empty observed_notes yields only general grounds and a 'possible appeal' rather than money owed. It does not contradict any annotation, though duplicate/idempotency handling is left unaddressed.

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, each carrying distinct information (action, return payload, matching logic/caveat). It is front-loaded onto the core action and avoids padding, though the middle sentence packs several return fields into one dense clause.

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 17 required parameters, no output schema and no nested objects, the description does the necessary work: it discloses the authentication requirement, summarizes the return payload, and explains the conditional outcome when observed_notes is empty. Only edge cases such as duplicate submissions are left uncovered.

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

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

Schema description coverage is 100%, so the schema already documents all 17 parameters thoroughly, making 3 the baseline. The description does add one meaningful point of semantics — that grounds are matched against contravention, location and observed_notes — which explains how the inputs are consumed, but it does not otherwise elaborate on parameter syntax or formats.

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 (adds) and a precisely scoped resource (a UK council PCN or private parking charge) and names the secondary effect (runs the appeal-grounds engine). This cleanly separates it from the other add_* record tools, which cover flights, trains and TfL journeys.

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: an agent can infer this is for recording a parking ticket someone received. The description adds a useful prerequisite (Untap sign-in) and a conditional caveat about missing observed_notes, but it names no alternative tool or explicit when-not case.

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 (readOnlyHint=false), idempotentHint=true and destructiveHint=false; the description earns credit for the extra behavioural detail behind those flags — duplicate rows are skipped, up to 500 rows per call, and authentication is required. It stops short of describing failure/partial-import behaviour, so it is strong but not exhaustive.

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

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

A single dense paragraph that front-loads the core action, then layers limits, flag semantics and refund rules in a logical order. Every sentence carries information, though the refund-rule sentence is intricate enough that it reads more like documentation than a quick scan.

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 4-param, fully-documented write tool with no output schema, the description covers the essentials: what is written, the batch ceiling, dedupe behaviour, auth and how refunds are computed. Only the outcome/response behaviour after a partial or rejected import is left unstated.

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 would be 3, but the description goes further by naming the meaning of the per-row flags (revenue-inspection max fare, free Hopper fare, TfL correction, daily/weekly cap) and by restating the intended_destination refund rule as an estimate versus an upper limit. That is meaningful added interpretation, not a repeat of the schema.

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

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

Opens with a specific verb+resource ("Adds TfL contactless journeys to the person's Untap account"), which cleanly separates it from add_flight, add_train_journey and add_parking_fine. It also ties itself to the sibling check_tfl_journeys by referencing "the same rule as the TfL check", so the agent can place it in the family without opening a schema.

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

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

The context of use is clear (ingesting statement rows, with journeys already saved being skipped and a 500-row-per-call ceiling), and the sign-in requirement is stated. It does not, however, explicitly tell the agent when to prefer this over, or run it alongside, check_tfl_journeys — the relationship 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 a non-readonly, open-world, non-destructive write, and the description adds real context beyond them: Untap queries National Rail Historical Service Performance per journey, omitted delay/arrival/cancellation fields trigger lookups, and an already-saved journey is returned as-is rather than duplicated. The dedup statement sits in mild tension with idempotentHint=false, though it plausibly describes content-level dedup rather than same-argument idempotency. Auth requirement ('Requires sign-in') is a useful addition.

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

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

Purpose is front-loaded in the first sentence and the remaining clauses are dense but purposeful (leg ordering, optional-field lookups, dedup, one-claim-per-journey, auth). A few items duplicate the schema descriptions, so there is minor redundancy, but 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 mutation tool with a nested legs array, no output schema and no return-value documentation, the description covers prerequisites (sign-in), cardinality rules per claim, dedup, and the external lookup dependency. It gives a hint about result shape for season_type but does not otherwise characterize what the call returns, leaving a modest 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 description coverage is 100%, so the schema already documents ticket_type fare math, season_type proration, operator codes and every leg field. The description largely restates this (optional lookup fields, single-vs-return leg count), adding only the 'travel order' framing for legs. Correct to sit at the baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Adds a UK train booking to the person's Untap account') and adds the secondary outcome ('works out Delay Repay for it'), which separates it cleanly from siblings like add_flight, add_parking_fine and add_tfl_journeys. An agent can identify it as the UK-rail booking creator without opening the schema.

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

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

Gives concrete operating context: one booking per call, legs in travel order (one single / two return), and the rule that operators accept one journey per claim form so a late return means two claims. It also states the sign-in prerequisite. It stops short of naming an alternative sibling (e.g. check_train_delay vs this add path), so it is not a full when/when-not routing statement.

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

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

Annotations already declare readOnly, idempotent and non-destructive, but the description adds real context beyond them: 'Nothing is saved or filed', sign-in to Untap is required, and a saved route does not prove travel (with the result stating so). It still doesn't cover rate limits or error modes, so not a 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?

Four compact sentences, front-loaded with what is computed before the caveats and auth note. Each sentence carries distinct information (output, multi-match handling, limitation, side effects/auth) with no 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?

With no output schema, the description compensates by enumerating the return contents (matched train, delay, amount, deadline, claim pack, service_id per match) and stating the read-only, sign-in-gated behavior. Nothing an agent needs 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 100%, so the schema already documents all three parameters; baseline is 3. The description adds operational meaning by tying service_id to the multi-match flow ('When several trains match, the result lists them, each with a service_id'), which explains why that optional parameter exists.

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 ('checks') and resource ('a saved train route') against a named data source (National Rail running records) for 'one travel date', and its output scope (Delay Repay amount, deadline, claim pack). 'Saved' distinguishes it from sibling check_train_delay, which operates on a one-off journey.

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 use: a saved commute (requiring commute_id) checked for a single date, with the service_id path described for disambiguating multiple matches. It does not explicitly say when to prefer check_train_delay or add_train_journey instead, so it falls short of stating 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?

Goes well beyond the readOnly/idempotent annotations: no sign-in required, nothing saved to an account, an anonymous record retained for a year, flight-status history limited to roughly the last year, and reconciliation behavior when supplied airports disagree with the record. These are exactly the operational traits an agent needs before calling.

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 purpose and inputs, then the return payload. The long enumeration of returned fields is justified because there is no output schema, though it makes the description denser than strictly necessary.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly: matched route, arrival delay, distance band, per-passenger amount, extraordinary-circumstances caveat, airline claim page, dispute body, deadline guidance, and claim pack. Privacy/retention and mismatch handling complete the picture.

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 every parameter (baseline 3). The description adds genuine meaning beyond it by explaining data-source selection: what_happened/arrival_delay_minutes are used when given, otherwise the flight-status record is consulted, and it reiterates that price_paid feeds account-saving rather than the amount.

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 ('Works out compensation for a delayed or cancelled flight'), names the governing regimes (UK261/EU261), and scopes it to flights, which separates it from siblings like check_train_delay or scan_for_claims. An agent can identify what this tool produces without opening the schema.

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

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

Gives clear context: it takes a flight number and date, and explains that the incident is either looked up in flight-status records or supplied via what_happened/arrival_delay_minutes. It does not name or exclude alternatives (e.g. save_claim, get_claim_instructions), so selection guidance is contextual rather than explicit.

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

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

Annotations already cover read-only/idempotent/non-destructive, but the description adds substantial context beyond them: the refund calculation logic (max fare minus actual fare), upper-limit vs estimate depending on intended_destination, the 8-week TfL window, and a year-long anonymised verification record. This is rich behavioral disclosure.

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

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

Front-loaded with the core purpose, then layers inputs, refund logic, returns, exclusions and privacy. Every sentence carries real information, though the single dense paragraph is longer than strictly necessary.

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

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

With no output schema, the description fully carries the return burden (refundable journeys, total, out-of-window journeys, claim pack, not_checked list) and annotates safety. For a 2-parameter, no-required-input tool, nothing an agent needs 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 description coverage is 100% — both csv_text priority and intended_destination's refund effect are already fully documented in the schema. The description restates these accurately but adds no syntax or semantics not already in the structured fields, so the 3 baseline 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 (checks) and resource (TfL contactless/Oyster journeys) with named overcharge classes — incomplete journeys and missed Hopper fares. It also distinguishes itself from siblings like add_tfl_journeys by scoping itself to checking rather than saving, and enumerates what it does not check.

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 clear input guidance: accepts journey rows or CSV text, rejects PDFs and images, and states 'no sign-in needed, nothing saved'. It doesn't explicitly route to sibling alternatives (e.g. add_tfl_journeys, check_commute), so it stops short of a full when/when-not with 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?

Despite annotations already covering the safety profile (readOnly, idempotent, openWorld), the description adds substantial behavioral detail: data coverage (last year, next-day, direct trains only), the data_not_available status shape with retryable/retry_after_seconds, background lookup with cached retries, and the privacy/retention note. This is rich context beyond the 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?

The purpose and inputs lead, with the return/error behavior following, so it is front-loaded. It is dense and runs long, but most sentences (retry semantics, coverage limits, retention) carry real information for a 9-parameter tool.

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?

There is no output schema, so the description carries the full burden and delivers: it enumerates the returned fields (times, delay, operator, amount, deadline, claim pack, save details) and the multi-match service_id behavior. An agent has everything needed to call and interpret it.

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 every parameter including formats and the amount-vs-percentage behavior. The description's parameter recap largely restates the schema, so the baseline of 3 is appropriate rather than a higher score.

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 (checks a late or cancelled train) and resource (Great Britain National Rail running records), and states the outcome (works out Delay Repay). This clearly separates it from siblings like check_flight_compensation and get_delay_repay_rules.

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

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

It gives strong context: stations accept names/partial/codes, service_id lets you check a specific train, changes must be checked one train at a time, and no sign-in is needed. It never explicitly names an alternative tool or a when-not-to-use condition, so it falls short of full routing 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 non-idempotency, but the description adds substantial context beyond them: data is deleted permanently, a preview deletes nothing, tokens last 5 minutes and are single-use, and the account itself survives. The auth requirement is also disclosed. This is exactly the behavioral burden a destructive tool's description should 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?

Four compact sentences, front-loaded with what is destroyed before the mechanics. Every sentence carries needed information (scope, two-step protocol, permanence, account retention, auth) with no filler.

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

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

For an irreversible delete with no output schema, the description covers everything an agent needs: preview behavior, what the preview returns, token lifetime and reuse limits, permanence, the fact the account is retained, and the sign-in requirement. 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 coverage is 100%, so the baseline is 3, and the schema already documents both parameters including the confirm/token dependency. The description adds value beyond the schema by stating the 5-minute token validity window and reinforcing the dependency, though the rest largely restates schema text.

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

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

States a specific verb (deletes) and the exact resource set (every booking, statement, saved commute and claim) scoped to the person's Untap account. It also names the multi-step nature up front, so an agent immediately understands this is not a simple one-shot delete. No sibling performs account-data deletion, so it is easily distinguished.

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 describes the two-call protocol: confirm=false for preview, confirm=true with token to actually delete, plus token expiry and single use. It also routes elsewhere for the adjacent need ('deleting the account too is done at untap.money/data') and states the sign-in prerequisite, covering when and 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, non-destructive, idempotent and closed-world, but the description adds genuinely new behavioral context: keyword matching rather than full reading, no sign-in required, nothing saved to an account, and an anonymized check record retained for a year for verification. That is exactly the kind of limitation, privacy and retention detail 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?

Five sentences, but front-loaded with what it takes and returns before the output shape, extraction, matching caveat and privacy notes. Each sentence carries distinct information, though the privacy/retention sentence adds density that could be trimmed.

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

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

With no output schema, the description fully describes the return: applicable schemes, each with its deciding fact, the relevant Untap check and the free guide. Combined with the matching caveat and privacy/retention statements, an agent has everything needed to call it correctly.

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

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

With one parameter at 100% schema coverage the baseline is 3, and the schema already supplies a definition plus examples. The description goes further by enumerating the kinds of text accepted and noting that flight numbers, dates, times and amounts are extracted from it, which adds meaning about how to phrase the input.

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+resource: takes a plain-language situation and returns the UK refund/compensation schemes that may apply, with the deciding fact, Untap check and guide. The scope enumeration (train, flight, TfL, parking, council tax, water, broadband) makes clear it spans the domains of the individual check_* siblings, though it never names a sibling to differentiate itself explicitly.

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

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

Usage is implied — describe a situation to discover applicable schemes — and it cautions that matching is keyword-based so the list is 'a starting point rather than a verdict.' However it never states when to use this discovery tool versus the specific check_train_delay / check_flight_compensation / check_tfl_journeys siblings, nor 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 cover read-only, idempotent, non-destructive behavior, but the description adds substantial context: coverage limits, that unverified facts return as unknown rather than estimated, no sign-in requirement, no account storage, and one-year anonymized retention of the check record. That is unusually rich disclosure for a read-oriented 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 purpose is front-loaded and every sentence earns its place, but the middle return-value sentence is a long unstructured run-on list. It is appropriately detailed for a no-output-schema tool, though tighter bullet-like structure would improve parseability.

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

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

With no output schema, the description does the necessary work by enumerating the returned eligibility rules, official claim page, numbered steps, form-field guidance, evidence, deadline, submitter rules, post-submission expectations, escalation routes, and sources. Coverage and verification limits are also stated, making the definition complete for this complex 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 100%, and the schema already documents every parameter, including which are required, their formats, and their claim-rule effects. The description restates the required versus optional grouping and parameter purposes without adding meaning 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?

The description opens with a specific verb and resource: returns how to submit one train, flight or TfL compensation claim on the company’s own form. It is distinguishable from check-style siblings by focusing on submission instructions rather than simply checking compensation, but it does not explicitly name or route against those alternatives.

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

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

The description explains what the tool returns but gives no when-to-use guidance, no prerequisites, and no explicit alternatives such as check_train_delay or get_delay_repay_rules. Usage is only implied by the purpose statement.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description still adds real value with 'No sign-in needed' (auth requirement) and the presence of a 'last checked' freshness field. It stops short of describing behavior for an unknown operator or matching failures.

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 before the payload enumeration, and the two trailing sentences are short and purposeful. The long field list is dense but each clause describes a distinct returned value, so little 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?

With no output schema, the description carries the return-value burden well by enumerating delay threshold, tiers, deadline, claim link, automatic scheme, and freshness date. It is complete for a single read-only lookup, missing only error/edge behavior for unrecognized operator names.

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

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

Schema description coverage is 100% and the schema already supplies examples ('Avanti', 'GWR', 'Southern', 'LNER') and the two-letter code option. The description's 'as people say it, such as Avanti, GWR or Southern' largely restates that, so the 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 (Returns) plus a precise resource (one train operator's Delay Repay rules) and enumerates the exact payload fields. No sibling tool overlaps this resource, so an agent can identify it immediately 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: the enumeration of rules, tiers, and deadlines makes clear this is a pre-claim lookup, and 'No sign-in needed' removes one barrier. However, it never states when to prefer this over check_train_delay or find_money_owed, nor any when-not condition, so guidance stays implicit.

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=false and destructiveHint=false, so the safety profile is covered. The description adds two things beyond them: the sign-in requirement (auth prerequisite) and the explicit absence of external National Rail calls, which clarifies data freshness rather than merely restating openWorldHint.

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, zero filler, with the core purpose front-loaded and constraints following. Every clause carries information.

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

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

For a simple read-only lister with no output schema and rich annotations, the description covers the essentials: what is returned, the auth requirement, and the absence of live lookups. The only omission is any mention of the include_stopped behavior, which the schema already supplies.

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

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

Schema description coverage is 100% and the single parameter include_stopped is fully documented there, so the baseline is 3. The description adds nothing about when to pass include_stopped (e.g., to surface routes stopped via stop_commute), so it does not exceed the schema.

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

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

States a specific verb and resource ('Lists the person's saved train routes') and enumerates the returned fields (ids, usual times, days, fares), which cleanly separates it from siblings like list_my_claims or list_savings. An agent can identify it without opening the schema.

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

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

'Makes no National Rail lookups' and 'Requires sign-in to Untap' tell the agent when this is the right tool (static saved data, authenticated context) rather than a live-lookup sibling such as check_commute. It stops short of naming an explicit alternative, so it is clear context but not full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. Beyond that, the description adds the meaningful status lifecycle (not sent, sent, paid, rejected, archived), the default filtering behavior, and the authentication requirement ('Requires sign-in to Untap') — useful context the annotations do not 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?

Three tight sentences with zero padding. The core behavior and returned fields come first, then the include_closed toggle, then the auth prerequisite — well front-loaded and appropriately sized.

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

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

With no output schema, the description usefully names the fields returned (amounts, deadlines, verdict, progress) and flags that sign-in is required, which is what an agent needs before calling. Minor gaps remain around result ordering or pagination beyond the limit parameter.

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

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

Schema description coverage is 100%, so all three parameters (limit, category, include_closed) are already documented in the schema; the 3 baseline applies. The description restates include_closed's effect and names the closed statuses, which slightly reinforces but does not extend the schema's own wording.

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 resource (claims in the Untap account) and enumerates the returned data fields (amounts, deadlines, verdict, progress). It is clearly distinguishable from siblings like list_savings, list_commutes and find_money_owed, which cover different resources.

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

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

Explains the default behavior (open claims only) and the exact condition that widens the set via include_closed. It gives clear usage context, but does not contrast the tool against close alternatives such as find_money_owed or update_claim_status, so no explicit when-not guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds real value beyond them: the explicit 'Requires sign-in to Untap' auth requirement and an explanation of what each returned row carries (verdict status plus user_progress).

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 the core action and filters front-loaded before the auth note. No filler, though the 'and so on' phrasing adds a slight vagueness rather than cutting it.

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

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

With no output schema, the description usefully describes the shape of returned rows and the auth requirement. It omits pagination/ordering behavior and does not reconcile the user_progress values with the status enum, but is otherwise adequate for a read-only list 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 100%, so the baseline is 3. The description clarifies what the status values mean semantically, but it also introduces a 'user_progress' value set (none/submitted/received/archived) that does not match the schema's status enum, which risks confusing rather than clarifying the parameter.

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 ('Lists the savings rows in the person's Untap account, filtered by category and status'), which is clearly distinct from siblings like list_my_claims or list_commutes. However, it never explicitly contrasts itself with those sibling tools, so the differentiation is implicit.

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 notes the sign-in prerequisite and explains what the filter values represent, which implies when the tool is useful. But it never says when to prefer this over find_money_owed or list_my_claims, nor any exclusion conditions, leaving usage to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuine context the annotations cannot: sign-in requirement, that the verdict is recomputed from the supplied facts rather than copied, that the missing price must be supplied, and that an already-saved train journey is returned unchanged. The train dedup claim sits in mild tension with idempotentHint=false, but since the hint is general and the description scopes dedup to train only, this is a nuance rather than a contradiction.

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 tight sentences with no waste; the core action and destination lead, followed by input shape, recomputation behavior, dedup, and the auth prerequisite in descending order of importance.

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 mutation tool with no output schema, the description covers the write, the auth requirement, the input provenance, and the idempotency edge case. It does not describe what the returned claim object looks like (beyond the dedup case), which is the main 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 100% with deeply documented nested objects, so the baseline is 3. The description adds value on top by explaining that the check's save_claim arguments are passed through and that ticket_price_pence must be filled in where the check omitted it, which is exactly the field the schema marks required for train/flight but not for tfl.

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 ("saves"), the resource (the result of a train, flight or TfL check) and the destination/effect (the Untap account, dashboard, deadline). It clearly positions itself downstream of a check, but never names the sibling tools (add_train_journey, add_flight, update_claim_status) it must be chosen over, so sibling differentiation is left implicit.

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 real usage context: it consumes the save_claim arguments a check returned, and it requires sign-in to Untap. It also notes the dedup case for train journeys. What is missing is an explicit "use this instead of add_train_journey/add_flight when you already ran a check" contrast against the near-identical add_* siblings.

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=true, destructiveHint=false and a closed world. The description adds genuinely non-redundant context: sign-in is required, nothing is validated automatically (validation is on request only), and only day tickets are supported, with season tickets explicitly excluded. It does not describe the response, but the behavioral profile is well covered.

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

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

Front-loads the core action and scope in the first clause, then adds constraints in compact sentences with no filler. Slightly dense as a single paragraph but every sentence carries information.

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

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

For an 8-parameter mutation tool with no output schema and no nesting, the description covers auth, idempotency, ticket-type limits and the check-on-request behavior. The main gap is what the caller gets back on save versus update, which matters more here precisely because there is no 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 description coverage is 100%, so the schema already documents every parameter including commute_id restore semantics and weekday numbering. The description only echoes the field list (stations, departure time, travel days, fare) without adding format or edge-case meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb pair (saves or updates) plus the exact resource (one direction of a usual train journey / commute) and enumerates the fields it stores. It clearly separates outward vs. homeward as two distinct routes. It does not explicitly differentiate itself from the sibling add_train_journey, 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?

Gives some routing guidance implicitly: saving the same route/time again updates rather than duplicates, and each direction is its own route. However it never says when to reach for this instead of add_train_journey, check_commute, or list_commutes, so the alternative-selection guidance is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context on top: detection is rule-based on sender domain, subject pattern and fixed phrases with 'no language model', bodies are truncated at 20,000 characters, nothing is stored and the usage record holds counts only, and unmatched emails are still listed by position.

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

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

The definition is a single dense paragraph with the core action front-loaded in the first clause, and each subsequent sentence carries distinct information (detection method, return fields, truncation, storage, auth). It is long, but little of it is filler.

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

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

With no output schema, the description must describe the return payload, and it does so thoroughly: match type, matched signals, booking reference, dates, flight number, stations/airports, times, amounts, confidence, deadline hint, and a pre-filled Untap check with missing arguments listed. An agent has everything needed to interpret results.

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 single parameter is already documented; the description nevertheless adds meaning beyond the schema by restating the email fields and clarifying the 20,000-character body read limit, which the schema's 200,000 maxLength does not convey.

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 ('Reads up to 25 emails ... and picks out the ones that point to a train, flight or TfL claim') and enumerates the claim categories it detects. This clearly separates it from the sibling add_*/check_*/list_* tools that act on already-identified claims.

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 agent can infer this is the detection step that feeds save_claim, and 'No sign-in needed' hints at its standalone nature. However, no sibling is named and there is no explicit when-to-use/when-not guidance (e.g., versus check_train_delay or list_my_claims).

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=false and idempotentHint=true, so the safety profile is partly covered. The description adds real value beyond that: it clarifies that stopping is a reversible hide ('can be restored by saving it again'), that no claims or bookings are affected, and that sign-in to Untap is required. This is meaningful behavioral context an agent could not read from the annotations alone.

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

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

Four short, front-loaded sentences with no filler. The most important point (it is a hide, not a delete) comes first, followed by restoration, side-effect scope, and auth.

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 mutation with no output schema, the description covers everything needed to invoke safely: reversibility, absence of side effects on claims/bookings, and the authentication requirement. No material gap remains.

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

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

Schema coverage is 100% and there is only one parameter, whose schema description already explains retention and restoration. The description repeats the commute_id restoration behavior but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Hides a saved train route from the active list.' The word 'hides' precisely distinguishes this from a deletion, and the follow-up sentence confirms the route is retained. It does not explicitly name a sibling it complements, so it falls short of full sibling differentiation.

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 agent can infer this pauses a commute rather than removing it, and that re-saving with the same commute_id restores it. There is no explicit when-to-use versus when-not-to-use framing or named alternative among the many commute siblings (list_commutes, save_commute, check_commute).

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 mutation (readOnlyHint=false), idempotency, and non-destructiveness. The description adds genuinely useful context beyond them: it explicitly states it does not contact the operator or airline and requires Untap sign-in. It stops short of covering error/failure behavior or partial-update semantics.

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 the core action and status list front-loaded, then the identity of claim_id, then the scope and auth caveat. No redundant or filler content.

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

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

For a mutation tool with no output schema, it covers the essential: what changes, which statuses exist, auth requirement, and the crucial limit that no external party is contacted. It does not describe the response or what happens to note/amount when status changes, 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 description coverage is 100%, so all four parameters are already documented in the schema, including the enum meanings and the pence conversion example. The description restates the status set and mentions 'paid with the amount received', adding little beyond the schema; the 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 (records/updates) and resource (claim status in the person's Untap account) and enumerates the four possible statuses. It is clearly distinguishable from siblings like save_claim and list_my_claims, which create or read claims rather than mutate 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?

Explains when this applies (recording progress on an existing claim) and where the claim_id comes from (saved or listed), and scopes the effect to Untap's record only. It does not explicitly name alternative tools or exclusion conditions, but the 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.