TripLedger

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

Annotations already declare readOnlyHint and non-destructive, so the description focuses on behavior the annotations can't express: the rolling-window semantics, extrapolation for future dates, and the hard failure mode where open journey gaps block the calculation. That failure mode is genuinely useful pre-call context. It doesn't describe output shape, but an output schema exists.

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

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

Front-loaded with the resource and its outputs, then constraints, with the guide prerequisite last. Sentences are dense but each carries information; nothing is padding. Slightly compressed syntax ("90-in-180-day") costs a little readability.

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 calculation tool with an output schema and fully described parameters, the description covers the non-obvious parts: window interpretation, future-date extrapolation, and the gap blocker. What's missing is a pointer to the sibling that answers the closest adjacent question (residency status).

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, and the description's asOf text largely restates the schema's own wording. personId is never mentioned in the description. Baseline 3 is appropriate 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 domain (Schengen 90-in-180-day compliance over a rolling window) and enumerates the outputs: days used/remaining, per-country breakdown, per-trip detail. An agent can tell this is a calculation/report tool rather than a mutation. It does not explicitly contrast with the nearby get_residency_status, which is the main source of residual ambiguity.

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

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

Gives concrete invocation rules: omit asOf for today, future dates honor logged journeys then continue presence in the last destination, and open journey gaps block the calculation. It also routes an unfamiliar agent to get_tripledger_guide first. It stops short of saying when to prefer this over get_residency_status or detect_journey_gaps.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent behavior, so the safety bar is lower. The description still adds non-obvious behavior beyond them: account numbers are masked in all output. It omits the duplicate-handling consequence implied by idempotentHint=false and any auth/permission requirements.

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

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

Three short sentences with the verb and subject front-loaded and no padding; each sentence contributes something. Minor slack in 'for one of the user's TripLedger people,' which restates the personId concept.

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 five-parameter creation tool with no output schema and no schema descriptions, the description leaves too much unexplained: it never states whether accountNumber is required or auto-generated, what status defaults to, or what the tool returns. The masking note is helpful but does not fill the parameter 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?

With 0% schema description coverage across 5 parameters, the description must carry the whole load. It only clarifies personId ('one of the user's TripLedger people') and programId ('choose programId'); nickname, status, and accountNumber are left entirely undocumented, and it never says which fields are actually required despite the schema declaring none.

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 ('Create a loyalty account') and ties it to a domain object ('one of the user's TripLedger people'). It does not explicitly name its sibling update_loyalty_account, but the create-vs-update distinction is clear from the verb alone.

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

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

Gives an explicit prerequisite and ordering: 'Use list_loyalty_programs first to choose programId.' That is real routing guidance an agent would otherwise miss. It stops short of saying when not to use it (e.g., account already exists) or naming update_loyalty_account as the alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is present. The description adds meaningful behavioral context beyond the annotations by emphasizing permanence and requiring explicit user confirmation before invocation. It does not discuss invalid/nonexistent IDs, but that is a minor gap given the simple operation and annotations.

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

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

Two short sentences with zero waste. The destructive permanence is front-loaded, and the confirmation requirement follows immediately as the key operational 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?

For a one-parameter destructive delete with rich annotations and no output schema, the description covers the essential agent concerns: what is deleted, that it is permanent, and that explicit confirmation is required. Nothing necessary 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%, and the single id parameter is already documented in the schema. The description only repeats that deletion is by id, adding no syntax or format meaning beyond the structured field.

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

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

The description states a specific verb and resource ('delete an expense') and clarifies the deletion is by id. It is immediately distinguishable from sibling deletions like delete_journey or delete_stay by resource, and from update_expense by operation.

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

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

It gives an explicit precondition: call only after the user has explicitly confirmed the deletion. It does not name alternatives such as update_expense, but the destructive nature makes the usage condition clear and the correct sibling selection obvious.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description still adds substantive behavior not in the annotations: attached expenses are cascade-deleted because an expense cannot outlive its journey, and it restates permanence plus the confirmation requirement. That is real added value beyond structured data.

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

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

Three short sentences, front-loaded with the action and its cascade consequence, ending on the confirmation constraint. Minor redundancy: permanence is asserted twice ("Permanently delete" and "This permanently deletes the record"), which costs a few words but does not bury the important 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 one-parameter destructive tool with no output schema and full annotation coverage, this covers everything an agent needs: what is removed, that related expenses go with it, that it cannot be undone, and that confirmation must precede the call.

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

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

There is a single required parameter with 100% schema description coverage ("ID of the journey to delete"), so the schema already does the work. The description only echoes "by id" without adding format, source, or lookup guidance — the baseline 3 fits.

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 ("Permanently delete a journey by id"), naming the lookup key. Siblings like delete_expense and delete_stay operate on different resources, so the target of this deletion is unambiguous 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?

It supplies a clear gating condition — call only after explicit user confirmation of deletion — which is exactly the kind of usage constraint an agent needs before an irreversible action. It stops short of pointing at alternatives (e.g. update_journey if the user only wants changes), so it is not a full when/when-not map.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is structured data; the description adds the confirmation requirement and reinforces irreversibility, which is genuinely beyond the annotations. It stops short of disclosing downstream consequences (whether related transactions/stays/loyalty data are cascaded) or behavior when the id does not exist.

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

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

Two short sentences with the operation and the safety precondition front-loaded; nothing extraneous. Minor waste in repeating 'permanently' twice across the two sentences.

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

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

For a one-parameter destructive tool with annotations covering destructiveness and idempotency, the definition supplies the one thing annotations cannot: the human-confirmation gate. Missing only cascade/not-found behavior, which is a modest omission given no output schema exists.

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 id parameter is fully documented in the schema. The description only restates 'by id' and adds no format, source, or validation meaning beyond what is already structured.

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 ('Permanently delete a loyalty account') plus the lookup key ('by id'). It is trivially distinguishable from siblings such as update_loyalty_account, list_loyalty_accounts, and the other delete_* tools, which act on 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?

Gives an explicit precondition: call only after the user has explicitly confirmed the deletion. This is real when-to-use guidance, but it never names the alternative action (e.g. update_loyalty_account for modification, or list_loyalty_accounts to verify the id before deleting).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered; the description still earns credit by disclosing the cascade side effect on attached expenses and the mandatory user-confirmation gate, neither of which is in the annotations. It omits behavior on a nonexistent id (error vs. silent no-op), which would have completed the picture.

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

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

Three short sentences, front-loaded with the destructive action, then the cascade consequence, then the confirmation precondition — each sentence carries distinct decision-relevant information 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?

Covers the essential facts for a one-parameter irreversible delete: what it destroys, the ripple effect on expenses, and the confirmation requirement, and no output schema exists to explain. Minor gap is the lack of stated behavior for an invalid or already-deleted id.

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 single 'id' parameter is documented in the schema as 'ID of the stay to delete.' The description only restates 'by id' and adds no format, source, or lookup guidance, so the schema carries the load and 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 ('Permanently delete a stay by id') and immediately distinguishes its blast radius from the sibling delete_expense by explaining that expenses are cascade-deleted rather than independently removable.

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 for invocation ('call this tool only after the user has explicitly confirmed the deletion'), which is exactly the guidance an agent needs for an irreversible operation. It stops short of explicitly naming alternatives such as delete_expense for removing only an expense without removing the stay.

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, non-destructive, closed-world). The description adds genuine operational context beyond that: the definition of a gap, what each gap result contains (likely origin/destination, unaccounted day count), and the date format convention. It stops short of describing edge cases such as gaps at the beginning/end of the ledger.

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 detection rule, followed by the output shape and the usage motivation. Every sentence earns its place with no filler or restatement of the name.

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 fully spelled out, yet the description still summarizes the useful fields. For a one-parameter read-only analysis 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 coverage is 100% for the single personId parameter, so baseline is a 3. The description adds meaning by restating the defaulting behavior ('Omit personId for the ledger's self person'), which clarifies the implicit default rather than merely repeating 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 ('Finds gaps between consecutive journeys') plus the precise detection rule (arrival-to-departure span exceeding a day in a different location), which clearly separates it from sibling list/get tools. An agent can tell that this is an analysis tool, not a CRUD operation on 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?

Gives a concrete when-to-use context: spotting missing journeys before they skew residency/Schengen counts, which implicitly ties it to check_schengen_status and get_residency_status. It does not explicitly say when not to use it or name the alternative tools outright, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real behavioral context: gap-blocking, future-date resolution order, and the null return when nothing has arrived. The only missing context is whether failures due to gaps surface as errors or as null.

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

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

Short, front-loaded sentences with no filler, and the default behavior (omit asOf) appears early. Minor redundancy between the description and the asOf schema text keeps it from a 5.

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 and full parameter coverage, the description only needs the edge-case semantics, which it supplies (gap blocking, future dates, null result). Sufficient to call correctly, though the failure mode for blocked gaps remains 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 both parameters are documented in-schema, including the self-person default for personId. The description's notes on asOf largely restate the schema's own wording rather than adding new meaning, so baseline 3 applies.

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

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

States a specific computation (country inferred from the latest journey arrival) with a time scope, which is clearly distinct from list/get siblings. It does not explicitly name the close alternatives (get_residency_status, check_schengen_status), so an agent must infer the boundary itself.

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 usage rules: omit asOf for today, how future dates are resolved, and that open journey gaps block the result. It even routes unfamiliar agents to get_tripledger_guide. It stops short of saying when to prefer get_residency_status or check_schengen_status instead.

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 establish the read-only, closed-world, non-destructive profile, and the description adds real value on top: the departureAt/arrivalAt vs departureDate/arrivalDate output/input naming mismatch is a concrete error-avoidance detail. It stops short of disclosing anything about failure modes (e.g., not-found or ownership scoping behavior), 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?

Purpose is front-loaded in the first sentence, followed by workflow guidance, with domain rules last. It is slightly overloaded with journey-splitting rules (airside connections, immigration) that arguably belong in the guide tool rather than a getter definition.

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

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

With an output schema present, return values needn't be enumerated, yet the description usefully flags the leg time field names. Nothing blocking is missing, though domain semantics around journey splitting could be deferred to the referenced guide.

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?

Single required parameter at 100% schema coverage, so the schema already carries the semantics. The description only implies 'one owned journey' scoping and adds no syntax or format guidance for id beyond what the schema provides.

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

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

States a specific verb and resource ('Get one owned journey by id') plus the returned shape (presence stamps, ordered legs), which cleanly separates it from list_journeys and get_journey_review. 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?

Explicitly names the downstream use case ('call this before update_journey so a replace-all route update preserves per-leg details') and names an alternative entry point (get_tripledger_guide) for unfamiliar callers. That is when-to-use plus routing in one place.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely non-derivable behavior: these journeys stay counted in presence calculations and gaps until resolved, which explains why the read matters. It stops short of describing ordering, paging, or volume of returned items.

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 doing distinct work: trigger, return payload + side effect, then the follow-up action policy. Front-loaded with the trigger. Slightly dense with workflow instruction, but no sentence is redundant.

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

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

With an output schema present, the description does not need to enumerate return fields, yet it still characterizes them (awaiting-confirmation journeys + preference flag). Combined with zero parameters and full annotation coverage, an agent has everything needed to call it correctly and act on the result.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for an empty schema is 4. The description correctly avoids inventing inputs and instead spends its words on workflow.

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) and specific resources (past booked journeys awaiting confirmation plus the owner's automatic-completion preference), which clearly separates it from list_journeys and get_journey. The phrase 'Call on entry to the ledger' also frames it as a review/queue tool rather than a generic fetch.

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 an explicit invocation trigger ('Call on entry to the ledger') and names the downstream alternative with its precondition: 'use update_journey with status completed only after confirmation, or correct/delete changed travel.' That is when-to-use plus what-to-do-next plus named siblings, not inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine value by characterizing the payload as explanatory content (counting rules, windows, uncertainty, limits) rather than raw data, which tells the agent what kind of answer to expect.

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

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

Two short sentences with the subject (what the numbers mean and how they are derived) front-loaded and the optional-parameter behavior trailing. Nothing is redundant or padded.

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 and full annotation coverage, return values and safety need no explanation, so the description is nearly complete for a single optional-enum documentation tool. The only residual gap is whether the methodology is static reference text or personalized to the user's data, which could affect how the agent frames the result.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does explain that the topic argument is optional and that omitting it defaults to all — a default the schema does not state. The enum values themselves are self-describing and need no further gloss.

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 resource and scope: it explains how residency, Schengen, and travel-summary figures are derived, including counting rules, windows, uncertainty, and limits. This clearly separates it from data-returning siblings like get_residency_status or check_schengen_status, though it never names those siblings explicitly to make the contrast unmistakable.

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

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

The description implies the tool is for understanding methodology rather than fetching current numbers, but it never says when to prefer it over get_residency_status/get_travel_summary, nor any exclusion. The only explicit usage instruction ('Pass an optional topic; omitted topic defaults to all') is about invocation, not selection.

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

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

The annotations already establish that this is a non-destructive, read-only, closed-world operation. The description adds useful behavioral context beyond that: the returned opaque ID remains stable across reconnections, scope upgrades, and ledger renames, and it explicitly notes that no user email is returned. It does not cover authentication needs or response shape, but the output schema handles the latter.

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

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

Three short sentences, front-loaded with the core action, followed by stability guarantees and a notable return-value caveat. Every sentence adds distinct information without 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?

For a zero-parameter read-only identity lookup with an output schema and full annotations, the description is complete enough to call correctly. It explains what is identified, the stability property of the returned ID, and an important negative return fact (no email), leaving no material ambiguity.

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

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

The tool takes zero parameters, so there is no parameter semantics burden. The schema description coverage is 100% and the baseline for no params is 4; the description does not need to explain parameters and appropriately does not try.

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

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

The description states a specific verb and resource: 'Identify this connection's bound ledger.' It clearly sets the tool apart from the travel, expense, loyalty, and journey siblings by framing it as a connection-level identity lookup, not a domain data operation.

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

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

Usage is implied by the purpose ('identify this connection's bound ledger'), but there is no explicit guidance such as when to call it versus relying on another tool or when it should not be used. The context is clear enough for an agent to infer, but no exclusions or alternatives are stated.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed world), and the description still adds substantial behavioral context: future dates honor logged journeys then continue presence in the last destination, open journey gaps block the calculation, and the result includes uncertain/unowned days plus the countingMethod per country. The "informational, not tax advice" caveat is exactly the kind of non-obvious framing an agent needs before relaying output.

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?

Six short, front-loaded sentences that each carry real information, with the core computation stated first and caveats after. The one redundancy is the enumeration of returned fields ("status, presence blocks, unowned uncertain days, countingMethod"), which duplicates the output schema and 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?

For a two-parameter, zero-required, read-only calculation tool with an output schema and full annotation coverage, the description supplies everything an agent needs: the computation, the default date behavior, future-date semantics, the blocking condition (open journey gaps), and a fallback guide tool for unfamiliar callers.

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 both parameters already carry their own semantics, including the future-date and open-journey-gap behavior for asOf. The description restates the asOf default ("Omit asOf for today") and adds nothing about personId's omission default beyond what the schema says, 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 first sentence names a concrete computation (days of presence per country vs. that country's residency threshold and window), which is far more specific than a restated title. It implicitly separates itself from check_schengen_status by tying the result to tax-residency thresholds rather than a Schengen day limit, but it never names that sibling, so the differentiation is left to inference.

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

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

It gives a clear default rule ("Omit asOf for today") and an explicit prerequisite path ("If unfamiliar with TripLedger semantics, call get_tripledger_guide first"). What it lacks is any statement of when NOT to use this tool or an explicit pointer to check_schengen_status when the user actually wants Schengen days rather than tax residency.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds only the "owned" access-scoping nuance; it says nothing about behavior on missing or non-owned ids, though an output schema exists so return shape need not be explained.

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, the core action leading and the precondition following. Every clause carries information and nothing is padded.

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

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

For a single-parameter read with full annotations and an output schema, the description covers what is needed plus a guide pointer. A brief note on what happens for unknown or non-owned ids would close the 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 description coverage is 100% and the single id parameter is documented there. The description's "by id" restates the schema rather than adding format hints or failure semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ("Get one ... accommodation stay") and scopes it with "by id" and "owned", which separates it from the multi-record list_stays sibling. It stops short of explicitly naming list_stays as the alternative, so it is clear but not fully differentiated.

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

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

Explicitly routes agents who lack TripLedger context to get_tripledger_guide before calling, which is a real usage precondition. It gives no guidance on when to prefer list_stays or what to do when the id is unknown, so exclusions are missing.

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 annotations: explains how future asOf values are projected (logged journeys first, then assumed continued presence), that open journey gaps block the calculation, and that transit and uncertain days are included. These are exactly the non-obvious behaviors an agent needs before trusting the numbers.

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 metric and window scope, then edge-case behavior, then the guide pointer — sensible ordering with little waste. The future-date clause is duplicated almost verbatim from the asOf schema description, which is the only real 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?

An output schema exists, so return shape needn't be explained; what remains — window definitions, default date, gap-blocking, transit inclusion, and the guide prerequisite — is fully covered. Nothing needed to invoke 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% and the asOf description already carries the future-date and gap-blocking semantics, so the description largely restates the schema. The personId default (self person) is covered in the schema but not in the description; 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 resource and metric (days spent per country) with two explicit window types (rolling-365, calendar-year) — clearly not the same output as check_schengen_status or get_residency_status. It stops short of naming those siblings, so differentiation relies on the reader already knowing what they return.

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 usage instructions for the optional parameter ("Omit asOf for today") and an explicit prerequisite route to get_tripledger_guide when the semantics are unfamiliar. It does not state when to prefer this over the other status/summary siblings, so selection between those still takes 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 establish that this is a safe read-only, closed-world operation. The description adds that output is portable and normal and that the tool is optional per request, which is useful, but it does not add much deeper behavioral detail beyond that.

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 three short, front-loaded sentences with no wasted text. Purpose, optionality, and the main alternative are all communicated efficiently.

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

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

The simple schema, annotations, and output schema reduce what the description needs to cover, and it explains purpose and the get_methodology alternative. However, the key parameter's enum values are left unexplained, which is a meaningful gap for a topic-selection tool.

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

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

Schema description coverage is 0%, and the description only says guidance is topic-scoped. It does not explain the meaning or appropriate use of the enum values overview, journeys, writes, residency, or schengen, so the agent must infer topic selection from the enum names alone.

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: retrieve topic-scoped operating guidance for TripLedger. It also explicitly distinguishes itself from get_methodology, so an agent can identify its role 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?

The description gives clear usage context: use when unfamiliar with TripLedger and not on every request, and it names get_methodology as the alternative for detailed calculation rules. It stops short of explaining which topic to choose for which situation.

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/openWorld=false/destructive=false, but the description adds real context: newest-first ordering, the cursor-to-nextCursor pagination contract, and how date-only vs timestamp `to` bounds are interpreted in UTC.

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 purpose in the first clause, then layers filters, date semantics, and pagination without redundant restatement of schema fields.

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

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

With 7 optional params, an output schema present, and read-only annotations, the description covers ordering, filtering, date interpretation, and pagination—everything an agent needs to call and iterate correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds value by defining the UTC interpretation of dates, the inclusive whole-day behavior of a date-only `to`, cursor provenance, and minor-unit currency amounts—semantics not fully captured by the schema property descriptions.

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 ('List the user's travel expenses') plus ordering, and is clearly distinguishable from the sibling mutation tools (log_expense, update_expense, delete_expense) and from get_travel_summary.

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 filtering levers (date-range, currency, journey/stay attachment) and the pagination flow with `cursor`/`nextCursor`. It does not explicitly route against alternatives like get_travel_summary, which keeps it just below a 5.

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

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

Annotations already declare readOnly/openWorld=false, and the description adds substantial behavior beyond them: newest-first ordering, pagination via cursor/nextCursor with null terminator, UTC interpretation of offsetless dates, inclusive date-only `to` versus exact timestamp `to`, and even the domain rule that airside connections stay one journey while airport exits split journeys. The output-field naming difference between read (`departureAt`) and write (`departureDate`) inputs is exactly the kind of non-obvious detail an agent would otherwise get wrong.

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, ordering and filters are front-loaded, and most sentences carry non-obvious information. A couple of clauses (the leg-time versus write-input naming, the domestic-journey day-count note) are only tangentially needed to invoke this read tool, which keeps it from a 5.

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-field enumeration is unnecessary — yet the description still explains pagination contract and the newest-first ordering an agent needs to page correctly. Combined with the date-semantics and guide pointer, nothing material for a correct call 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, but the description adds real semantics on top: the cursor must come from a prior response's `nextCursor`, and `to`/`from` interpretation differs for date-only versus full-timestamp values (whole UTC day versus exact instant). It also defines what a journey is for filtering purposes (airside vs split journeys, domestic journeys valid but excluded from day counts).

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 ("List the user's journeys") and immediately qualifies the domain object ("movements between countries") plus what is returned (presence stamps, ordered legs, newest-first). This clearly distinguishes it from get_journey (single journey), list_stays, and detect_journey_gaps without needing the schema.

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

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

Gives a concrete routing hint: "If unfamiliar with TripLedger semantics, call get_tripledger_guide first," and explains that filters are optional. It does not state when to prefer this over siblings like list_stays or get_travel_summary, so an explicit exclusion is missing, but the context is clear.

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

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

Annotations already establish read-only, non-destructive, closed-world behavior. The description adds useful privacy context beyond annotations: account numbers are partially masked in both text and structured output.

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

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

The description is two short sentences, front-loads the core action, and includes only useful information. Nothing 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?

For a no-parameter, read-only list tool with an output schema and clear annotations, the description is complete. It states what is returned and discloses the masking behavior, so an agent can invoke it correctly without additional context.

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

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

The tool has zero parameters, so the baseline is 4. The description's 'No input' statement confirms this and aligns with the empty schema, though it adds no further parameter detail because none 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?

The description states a specific verb and resource: listing the user's loyalty accounts. This clearly distinguishes it from sibling tools such as create_loyalty_account, update_loyalty_account, delete_loyalty_account, and list_loyalty_programs.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives like list_loyalty_programs or get_profile. It implies usage through its purpose but gives no context, prerequisites, 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 cover read-only, non-destructive, closed-world safety, so the description only needs to add context. "Seeded" is genuinely informative — it tells the agent this is a static reference catalog rather than user-owned data — and "No input" confirms there is no filtering or pagination knob to worry about. Return format is left to the output schema.

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

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

Two short sentences, both front-loaded with the essential information (what is listed, then that it takes no input). No filler, no redundancy.

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

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

This is a trivial no-parameter list tool with an output schema that documents the return shape and annotations that document safety. The description covers purpose, scope, data provenance, and the absence of inputs — 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?

Zero parameters, so the baseline is 4, and the description explicitly says "No input" so the agent won't hunt for optional filters. Nothing further is needed.

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

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

Specific verb ("List") plus a precise resource ("seeded airline, hotel, and rail loyalty programs"), scoped further by "that loyalty accounts can point to", which implicitly separates it from list_loyalty_accounts. It stops just short of naming the sibling outright, so an agent still has to infer the catalog-vs-user-records split.

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 clause "that loyalty accounts can point to" hints this is the lookup you do before creating/updating a loyalty account, but the description never states when to use this versus list_loyalty_accounts, nor any exclusion or prerequisite. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful behavioral context that the result includes the self person and that the IDs are meant for participant fields, though it does not discuss ordering or pagination.

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

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

Two sentences, front-loaded with the core action and immediately followed by the practical use of the returned IDs. 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?

With no parameters, read-only annotations, and an output schema available, the description is nearly complete. It could say more about result shape or whether the list is paginated, but the output schema likely covers those details.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly adds no parameter details, and the empty schema is self-explanatory.

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: list the travelers in this ledger, explicitly including the self person. The resource is clearly distinct from sibling tools like list_journeys, list_stays, and list_expenses, so 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?

Gives clear downstream usage context: use these IDs for person-aware reads and journey/stay participant fields. It does not name when-not-to-use or an alternative, but there is no obvious sibling alternative for listing people.

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 only cover read-only/non-destructive safety; the description adds substantial behavior beyond that: UTC interpretation of offset-less dates, the special rule that a date-only `to` covers the whole UTC day while a full-timestamp `to` stays exact, newest-first ordering, and the pagination contract with `nextCursor` null on the last page.

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, ordered by importance: scope and ordering first, then filters, then the subtlest semantics, then pagination. No filler or restated field names.

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

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

An output schema exists so return values need not be described, yet the description still usefully explains `nextCursor`. Filters, ordering, date edge cases, and paging are all covered; the only gap is guidance on when to use this versus sibling read tools like get_stay.

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; the description earns an extra point by explaining timezone handling and the inclusive-day semantics of `to`, details the schema does not convey. It does not, however, cover the `personId`/`country` semantics, which remain schema-only.

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 ('List the user's accommodation stays') and adds the ordering guarantee ('newest-first by check-in'), which cleanly separates it from get_stay (single item), log_stay, and delete_stay.

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 optional date-range and country filters frame the intended usage, and the pagination sentence tells the agent exactly how to continue. It stops short of naming when to prefer a sibling such as get_stay for a single record or search_locations for lookups, so it is clear context without explicit alternatives.

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

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

Annotations only say non-read-only, non-destructive, non-idempotent; the description adds the real behavioral facts an agent needs — the duplicate guard returns a warning naming the existing record's ID rather than inserting, and allowDuplicate:true overrides it. It also discloses the currency/amount representation contract and the fixed category vocabulary per parent type.

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, then constraints, then the cross-tool tip, then the duplicate behavior, then the onboarding pointer — a deliberate ordering where each sentence carries a rule an agent would otherwise get wrong. No marketing filler or restatement of the name.

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

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

Adequate for the risky parts of an 11-parameter mutation with no output schema, but several inputs (fxRate, spentAt, feesMinor, payerPersonId) are left entirely to an almost undocumented schema, and the linked-currency/FX semantics are never explained. The duplicate-warning return is described only insofar as it differs from a normal insert.

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 only 9% schema description coverage across 11 parameters, the description must carry the load, and it does for the highest-risk ones: amountMinor is defined as integer minor units, currency as ISO-4217, journeyId/stayId as a mutually exclusive one-of, and category as a preset enum conditioned on parent type. However fxRate, spentAt, feesMinor, description, and payerPersonId are never mentioned, so coverage is strong but incomplete.

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

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

States a specific verb and resource ('Log a new travel expense') and immediately scopes it to the authenticated user. The tip naming log_journey/log_stay as the combined alternative makes it unambiguously distinguishable from the record-creation siblings.

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

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

Explicitly specifies the mandatory parent relationship (exactly one of journeyId or stayId, not both, no standalone expenses), routes the agent to log_journey/log_stay when logging a record plus its price, and points unfamiliar agents at get_tripledger_guide first. Positive and negative conditions are both stated.

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

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

Annotations only tell the agent this is a non-destructive, non-idempotent write. The description goes far beyond: a duplicate guard returns a warning with the existing ID unless allowDuplicate is set, costs each become expenses tied to the record (Pro-gated), domestic journeys are accepted but ignored for day counts, and resolved country names are echoed in the result.

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, then rules, then parameters – a sensible order, and nearly every sentence carries operational value. The one flaw is the verbatim repetition of 'If unfamiliar with TripLedger semantics, call get_tripledger_guide first' at both the start and the end, which wastes space in an already long description.

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

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

With no output schema, the description still covers return behavior (resolved country names echoed, duplicate warning with ID), the write semantics, cost side effects, and the default status derivation. For a 6-parameter creation tool with nested leg objects, 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 only 50%, and the description compensates thoroughly: legs[] is required and defines route/timing/transport/country stamps, dates need ISO 8601 with explicit offset, timezones must be IANA names, country accepts alpha-2 or English name, and status accepts booked/completed with a stated default. It even disambiguates the output naming (departureAt/arrivalAt) from the input naming (departureDate/arrivalDate).

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 ('Log a new journey') and immediately defines the domain concept ('a precise movement between countries') for the authenticated user. This clearly separates creation from the sibling mutation tools like update_journey and delete_journey, and the multi-leg framing tells an agent exactly what unit is being created.

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

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

Gives explicit decision rules: airside connections stay one journey with multiple legs, but leaving the airport or clearing immigration requires splitting into separate journeys. It also specifies status selection (booked vs completed), tells the agent to ask when ambiguous, and points to get_tripledger_guide when semantics are unfamiliar.

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

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

Adds substantial behavior beyond the annotations: the duplicate-detection returns a warning naming the existing ID rather than inserting, costs become expenses tied to the record (Pro-gated), country is resolved and echoed back, and check-out must be after check-in. These are non-obvious mutation semantics the structured fields 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?

Front-loads the core purpose and stays dense, but it is a long block and the costs/duplicate guidance runs together. Each clause mostly earns its place, though some of the cost-model explanation could be tightened.

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 helpfully discloses the key return cues (warning with existing ID, echoed resolved country). For a 9-param mutation it covers the critical behaviors, though a few parameters (participantIds, notes, fxRate) remain opaque.

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 only 11%, so the description carries real weight and does: ISO 8601 with offset for dates, alpha-2/English for country, the costs item shape (amountMinor, currency, category) and the one-line-per-charge rule, plus allowDuplicate intent. Uncovered in either place: city, name, notes, participantIds, spentAt, fxRate, feesMinor.

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 ('Log a new stay') for the authenticated user, and immediately frames its role relative to journeys ('optional accommodation/cost overlay — journeys remain the presence spine'). An agent can distinguish it from log_journey and log_expense from the text alone.

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

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

Gives concrete when-to guidance: pass costs as one line per charge (fare plus addons/upgrade), use allowDuplicate to override the duplicate guard, and call get_tripledger_guide if unfamiliar. It stops short of naming update_stay as the edit alternative, so no explicit sibling routing for modifications.

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/openWorld/destructive annotations: coverage is partial, a miss is not proof of invalidity, and results do not establish immigration entry or country presence. These caveats are exactly the kind of expectation-setting an agent needs to avoid false negatives on a lookup.

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?

Dense but front-loaded: purpose first, then return shape, then disambiguation, then caveats and the sibling handoff. Each sentence carries distinct guidance, though the disambiguation and handoff sentences could be tightened slightly without losing meaning.

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

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

Single-parameter lookup with an output schema, so return shape needs no prose — yet the description still flags the extra matchedAirport fields that appear only on code matches. Combined with the coverage caveat, an agent has everything needed to call this and interpret a miss correctly.

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

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

Schema description coverage is 0%, so the description carries the load, and it does: it defines the query's accepted forms (city name, country name, exact three-letter IATA code) and the exactness requirement on codes. Minor gap — it doesn't mention the 2–100 character bounds that the schema enforces.

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

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

States a specific verb and resource (search reference cities) plus the accepted key forms (city/country name, exact three-letter IATA code), and the payload (ISO country, IANA timezone, and matchedAirport* fields). Nothing here could be confused with a journey/stay/loyalty sibling.

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 an explicit ordering rule ('use it before log_journey when location/timezone details are unknown'), a disambiguation policy for ambiguous codes (EWR → Newark vs New York), and a downstream handoff (retain matchedAirportCode in originIata/destinationIata). It even states what the tool does not do ('plain city searches do not infer airports').

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

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

Beyond the annotations it discloses deferred activation ('on the next app/MCP access'), default state ('Off by default'), scope ('whole ledger'), and non-retroactivity ('do not undo previous completions'), plus the owner-only authorization requirement. That is substantial context an agent cannot get from destructiveHint/idempotentHint 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?

Short declarative sentences, authorization and precondition front-loaded, and every sentence adds a fact (scope, default, timing, non-retroactivity) rather than restating the title.

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 a single required boolean, rich annotations, and no output schema, the definition covers nearly everything needed to call it safely. It does not say what the response returns or how to confirm the new state took effect, which is a minor but real gap for a mutation.

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

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

Schema coverage is 0%, so the description carries the burden; it explains that the boolean toggles automatic booked-to-completed conversion and that the default is off, which gives the flag real domain meaning. It never names the parameter or states explicitly what true vs. false produce, so it stops just short of full coverage.

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

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

The description uses a specific verb pair (enable/disable) against a precisely defined setting: automatic booked-to-completed conversion after arrival. No sibling tool in the list covers journey preference settings, so the risk of confusion is negligible.

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

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

It states a hard precondition: 'Only call after the owner explicitly requests this preference change,' plus an 'Owner only' restriction. No alternative tool exists for this action, so there is nothing to route against, but the when-to-use gate is 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?

Goes well beyond the annotations (destructiveHint=true, idempotentHint=true): it discloses that re-attaching re-checks ownership of the new parent, that a null parent without a replacement is rejected as unassignment, and that cross-kind moves require a matching category in the same call. These are non-obvious failure modes an agent cannot get from the schema or hints; only return/response behavior is left unstated.

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?

Dense but front-loaded: partial-update contract first, then prerequisites, then parent-move rules, then category presets. Every sentence carries a rule, though the final category sentence is long and could be split for scanability.

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 11-param mutation with no output schema and near-zero schema descriptions, the description covers the risky dimensions: exclusivity of the journey/stay parent, ownership validation, rejection of bare nulls, and category validity. Only the remaining numeric/currency params and the returned shape are untouched.

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 only 9% (only id is described), so the description carries the burden and does explain the highest-risk params: journeyId/stayId parent semantics and category presets. But fxRate, feesMinor, amountMinor, currency, spentAt, payerPersonId and description remain uninterpreted in both places, leaving a substantial gap.

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

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

Opens with a specific verb+resource scoped by id: "Update fields on an existing expense by id." It immediately distinguishes itself from log_expense (creation) and delete_expense by defining partial-update semantics, which no sibling does.

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 conditions for the tricky paths: call get_tripledger_guide first if unfamiliar, set the new parent (optionally nulling the old wire field) to move an expense, and include a category valid for the new kind when switching journey/stay. It stops short of naming sibling alternatives explicitly (e.g., use log_expense to create), so not a full 5.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description earns its credit by explaining exactly what is destroyed: a route/timing/transport change 'replaces ALL existing legs' rather than merging. It also discloses non-obvious state behavior — omitted status stays unchanged even after date edits, and notes/status-only updates leave legs untouched — which the annotations alone could 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?

Front-loaded with the operation modes and the most consequential constraint (legs[] replacement) before the domain guidance. It is dense but mostly earns its length; the airside-connection and day-count rules are useful for constructing valid legs but push the description toward the long side for a single update call.

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

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

No output schema exists, and the description still covers the return-side contract sufficiently ('Journey output leg times are departureAt/arrivalAt') plus the get_journey prerequisite. For a 5-parameter mutation tool with destructive and replacement semantics, it supplies the preconditions, mutation scope, and domain rules an agent needs 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 schema coverage at 60%, the description compensates well: it defines legs as an ordered replace-all route, explains why get_journey precedes it, and resolves the naming trap between read-side departureAt/arrivalAt and write-side departureDate/arrivalDate. It leaves a gap on notes null semantics (whether null clears the field) and does not discuss participantIds beyond what the schema already documents.

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 plus resource and enumerates the three modes of operation (status, notes, route replacement by id), which lets an agent distinguish it from log_journey, get_journey, and delete_journey immediately. The scope statement 'Status/notes-only updates leave every leg unchanged' further sharpens what the tool does and does not touch.

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

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

Gives explicit when-to guidance and prerequisites: 'Prefer get_journey first so per-leg details are preserved' and 'If unfamiliar with TripLedger semantics, call get_tripledger_guide first'. It also states a domain condition that gates a value ('Set status completed only after the user confirms travel happened') and the condition that forces the full legs[] array, so an agent knows which path to take rather than inferring 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 destructiveHint=true and idempotentHint=true, yet the description adds real context beyond them: partial-update semantics (omitted fields preserved), null as the clearing mechanism, and a critical warning that output is masked so a masked value must never be written back. That last point is behavioral information an agent could not infer from any structured field.

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, front-loaded with the core action and partial-update rule, followed by the guide pointer, null semantics, and the masking warning. No filler or restated name/title.

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

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

For a destructive mutation with no output schema, the definition covers the essentials: partial semantics, how to clear values, and the masking pitfall. It omits what changing personId/programId implies and any validation or failure behavior, which would be the remaining gaps.

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

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

Schema coverage is only 17% (just id documented), so the description must compensate. It does so for three of the five optional fields by explaining null clears accountNumber, nickname, and status, and it establishes the partial-update rule for all fields. personId and programId still get no semantic explanation, keeping it from a 5.

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

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

States a specific verb and resource ('Update fields on an existing loyalty account by id') and clarifies it is a partial update, which distinguishes it from create_loyalty_account and delete_loyalty_account. It does not name a sibling explicitly, so it lands just 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 clear usage conditions: call get_tripledger_guide first if unfamiliar with semantics, and use null specifically to clear accountNumber, nickname, or status. Lacks explicit exclusions (e.g., when to prefer delete_loyalty_account), but the operative guidance is concrete.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description is not obligated to restate safety. What it does add is the partial-update contract ("only the fields you provide are changed; omitted fields keep their current value"), which materially reduces the risk of an accidental full overwrite. It never explains what "destructive" means here, e.g. that supplying participantIds replaces the traveler set outright.

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

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

Three short sentences, front-loaded with what the tool does and immediately followed by the behavioral rule that matters most. No filler and no 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?

An 8-parameter destructive mutation with no output schema needs a bit more: the deferred country rules and date-format expectations are left unresolved, and the destructive semantics of replacing participants are not surfaced. The partial-update rule and the guide pointer cover the essentials, but not the full 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?

With only 25% schema description coverage, the description needs to carry parameter meaning, but it addresses only the omit-to-keep rule generically. Parameters like countryCode (whose rules are merely deferred to log_stay), checkInDate/checkOutDate format, and the max-length constraints on city/name/notes get no explanation here. The one genuinely useful element, participantIds being a complete replacement, lives in the schema rather than the description.

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

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

"Update fields on an existing stay by id" gives a specific verb, resource, and targeting key, which cleanly separates it from update_expense, update_journey, and update_loyalty_account as well as from get_stay/delete_stay/log_stay. The scope of the mutation (a subset of stay fields) is stated in the same breath.

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 tells the agent to call get_tripledger_guide first when unfamiliar with TripLedger semantics, and that country rules mirror log_stay — both explicit routing cues. It stops short of naming when to use this instead of delete_stay plus log_stay (full replacement) or 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.