Trip720

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the 'Read only' line adds nothing structured data does not already say. The description does add useful provenance (NASA POWER climate data plus Trip720 research), which hints at data reliability, but says nothing about caching, coverage, or response shape.

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

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

Two tight sentences with the value proposition front-loaded. The trailing 'Read only' is redundant against the annotations and could be cut, but the description is otherwise free of padding.

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

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

For a single-parameter read tool with no output schema, the description adequately conveys what comes back (month-by-month guidance, per-place months, holiday weeks) and the data sources. It could say more about scope limits (e.g., which places are covered), but nothing essential 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?

With one parameter and 100% schema description coverage, the schema already explains that country accepts a name or two-letter code. The description adds no syntax, normalization, or fallback behavior beyond that, so the baseline 3 applies.

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

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

The description names a specific resource and enumerates what the response contains: best months overall, per-place pleasant months, and busy holiday weeks. An agent can tell this apart from destination_facts or plan_trip without opening any schema.

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

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

Usage is implied ('plan around' busy weeks) but there is no explicit when-to-use versus siblings like destination_facts or plan_trip, and no exclusions or prerequisites. The agent must infer that this is the timing-research tool.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the closing 'Read only.' merely repeats structured data and earns no credit. The one piece of added behavioral context is provenance ('source (official government pages where available)'), which tells the agent how much to trust the answer; nothing is said about coverage gaps, missing pairs, or failure behavior.

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

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

A single front-loaded sentence whose colon list previews the response fields before any caveats. Every clause carries information; the only near-redundant element is the trailing 'Read only.'

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

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

With no output schema, the description correctly takes on the job of describing return values (rule name, processing days, source) and the official-sources caveat. What is missing is the edge case: what the tool returns when no rule exists or when a passport/destination pair is unsupported.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real meaning by stating the query is evaluated 'for each passport and each destination country' — i.e. the two arrays are combined pairwise rather than interpreted as one aggregate request. The 6-item maxItems bounds are left to the schema, which is appropriate.

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

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

The description names the specific decision being answered ('whether travellers need a visa or an electronic authorisation') and enumerates what comes back ('the rule's name, the minimum processing days and its source'), which is far more than a restatement of the tool name. It does not explicitly contrast with any sibling, though no sibling in the list covers entry rules, so the differentiation is implicit in the subject matter.

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 phrasing 'for a holiday' and by the per-passport/per-destination framing, which tells an agent this is a trip-planning lookup. There is no explicit when-to-use, no prerequisites, and no mention of an alternative when the answer is unknown or the country pair is out of scope.

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

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

Annotations already cover the safety profile (readOnlyHint true, destructiveHint false, openWorldHint false), yet the description still adds real behavior: figures carry sources, values are in AUD or GBP, and uncovered places respond by saying so and listing covered places in that country. The remaining gap is response size/format, which matters for an enumeration this broad with no 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?

The resource and purpose are front-loaded in the first clause, and the long middle enumeration is dense but each item corresponds to a real returned data class. It is one block of prose rather than a list, which costs a little scannability, but there is no filler sentence.

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

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

With no output schema, the description carries the full burden of describing return values and it does so field by field, plus currency, sourcing and the not-covered fallback. For a two-parameter read-only lookup, nothing an agent needs in order to call it and interpret the result 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 enum and the AU default are already documented, giving a baseline of 3. The description adds meaning on top by tying homeCountry to concrete outcomes (the visa for that home country and the AUD/GBP currency of the figures) and by signaling that 'place' spans town, island or country.

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

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

The description names a specific resource (checked facts for one destination) and enumerates exactly what is included: daily costs, transport and taxi prices, tourist tax, best months, visa, sights and a sample trip total. That enumeration also separates it from narrower siblings such as best_time_to_visit and check_entry_requirements, which cover only slices of this bundle.

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 — fetch this when you want a consolidated cost/visa/sights picture for a place — and the closing note 'Read only; no booking or search is made' usefully rules out a booking workflow. However, no sibling is ever named, so an agent is not told when to prefer best_time_to_visit, check_entry_requirements or get_day_plan over this broader tool.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds two genuine pieces of context: the default-option resolution rule and the data-quality caveat that 'typical' times are not from a timetable. It says nothing about how large a plan can be or whether anything errors when no plan 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?

Two tight sentences, front-loaded with the resource and scope, with the default rule and the data caveat following. The nested parenthetical is slightly dense but every clause carries information.

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

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

For a two-parameter read with no output schema, the description covers the return contents (per-day times, places, prices), the default behaviour and one caveat. An agent could call it correctly, though the meaning of tripId 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 description coverage is 0%, so the description carries the burden. It explains optionId's default meaning well, but tripId is only implied ('a trip already planned') with no stated format or source, and the missing half leaves the parameter picture partial.

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

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

States a specific verb+resource: the day-by-day plan (times, places, prices) for one option of an already-planned trip. This is meaningfully narrower than get_trip, though the description never names that sibling to draw the contrast explicitly.

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

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

Gives a clear precondition (the trip must already be planned on Trip720) and explains the option-selection rule: the recommended option is used unless optionId is supplied. It does not state when an agent should prefer get_trip or trip_alternatives 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 declare readOnlyHint, destructiveHint false and closed-world, so the safety profile is covered; the description reinforces it with "Read only" and adds genuinely new context: a 30-day retention window and the fact that options only appear "when ready", meaning partial responses are possible. It stops short of describing error behavior for expired or unknown trip ids.

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

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

One sentence, front-loaded with the verb and resource, with the colon cleanly separating identity from payload. The retention clause is the only extra and it earns its place by preventing calls on expired trips.

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

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

With no output schema, the description takes on the job of describing return values and does so adequately: status plus options with labelled prices and booking links, including the conditional "when ready". Only failure cases (not found, expired beyond 30 days) are left unstated.

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

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

Schema coverage is 0% for the single required tripId, so the description must carry the meaning; it does state the id identifies a trip "already planned on Trip720", implying the value originates from plan_trip. It adds no format or validity details (e.g. id shape or how to obtain it explicitly), so the compensation is only partial.

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

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

"Reads a trip already planned on Trip720, by its trip id" names a specific verb and resource, and goes on to enumerate what comes back (status, options, prices, booking links). It does not explicitly contrast itself with siblings such as get_day_plan or trip_alternatives, so it falls short of full sibling differentiation.

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

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

The phrase "a trip already planned" implies the tool is for retrieving something created by plan_trip rather than creating it, which gives an implicit usage context. There is no explicit when-not-to-use guidance and no named alternative for related lookups like day plans or swap candidates.

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 past the annotations: discloses the persistence side effect (trip saved, kept 30 days, nothing booked or paid), hard limits (6 travellers, 60 nights, 5 places), that flight fares are estimates in this build, and the price-labelling scheme (live/estimate/official). This is exactly the context an agent needs before a non-readOnly, non-idempotent call.

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

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

A single dense paragraph, but it is front-loaded with purpose and then side effects, limits and return shape in a sensible order. Nearly every clause carries information; only the price-label taxonomy is slightly verbose.

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 compensates well by describing the return: up to six options, Safe Trip Total, route, price labels, booking link, and a 'building' status with trip id. It doesn't address repeated-call/idempotency behavior, which is the remaining gap for a write tool.

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

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

With 70% schema description coverage, the schema already carries most parameter meaning. The description reinforces constraints (budget is total home-to-home, 6 travellers, 60 nights, 5 places) but adds nothing about pace, dining, interests, tripFocus, or the 'surprise' destination semantics beyond what the schema states.

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

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

States a specific verb and resource ('Plans a whole trip, home to home, against the traveller's total budget') and enumerates the covered components (flights, stays, transfers, activities, visas, daily costs). This clearly separates it from the sibling read/lookup tools (get_trip, get_day_plan) and item-level tools (swap_trip_item).

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 opening ('For a request to plan a trip with a budget') gives a usage trigger, and the 'building' status note implies a follow-up via get_trip. However, no explicit when-not guidance or routing to siblings like best_time_to_visit or check_entry_requirements is given.

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

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

Annotations already flag destructive=true, non-idempotent and open-world, but the description goes well beyond them: it discloses that the saved trip is mutated, that the change is reversible because the previous choice can be re-selected the same way, and that nothing is booked or paid. It also notes the whole trip is re-priced, matching website behavior.

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

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

Three sentences, each doing distinct work: action and re-pricing, return payload, then side effects and reversibility. The destructive consequence is stated plainly and no sentence is padding.

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

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

With no output schema, the description usefully specifies the return value (updated option plus Safe Trip Total before and after) and covers mutation, reversibility and the absence of booking/payment. The only shortfall is not explaining how to source lineId and optionId, which matters for a four-required-parameter 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 only 25%, with just 'choice' documented in the schema; the description reinforces that it is a 1-10 numbered choice from trip_alternatives. The other three identifiers (tripId, optionId, lineId) remain unexplained, though 'one line of an option' gives a weak hint about the hierarchy. It partially compensates but leaves a real gap for a 4-parameter tool.

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

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

States a specific verb (replaces), a specific resource (one line of an option within a trip), and the re-pricing consequence, all in the first sentence. It also names the sibling tool trip_alternatives as the origin of the numbered choice, which lets an agent separate it from plan_trip and get_trip without opening any schema.

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

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

The description makes the workflow prerequisite clear: the 'choice' must be a numbered option from trip_alternatives, implying that tool should be called first. It stops short of explicit when-not guidance or stating that get_trip is the way to obtain lineId/optionId, so it is clear context rather than full routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description still adds genuine context: it re-queries the providers rather than reading the stored trip, so results may reflect current availability, and the response is numbered with each choice's price and its effect on the Safe Trip Total and budget.

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 scope ('For one line of an option in a trip already planned'), then the return content, then the id provenance, then a short behavioral note. One dense sentence plus a two-clause trailer; nothing is redundant, though the parenthetical item list makes the opening clause heavy.

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

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

With no output schema, the description carries the burden of describing return values and does so adequately: numbered alternatives, each with price and impact on Safe Trip Total and budget. It also supplies id provenance. It omits any mention of result limits, pagination, or what happens when an item has no alternatives.

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 33% — lineId has an example value but tripId and optionId are undocumented. The description partially compensates by stating that line ids and option ids originate from plan_trip or get_trip, and it implicitly ties lineId to a trip line (a stay, flight, transfer, activity), but it adds nothing about tripId or id format.

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

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

States a concrete verb and resource: returns the alternative choices providers offer for one line item (stay, flight, transfer, activity) of an already-planned Trip720 trip. The scoping phrase 'for one line of an option' plus the enumeration of item types lets an agent separate this from siblings like get_trip and swap_trip_item without reading a schema.

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

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

Gives a clear precondition — the trip must already be planned, and line/option ids must come from plan_trip or get_trip — which is exactly the routing information an agent needs. It stops short of an explicit contrast with swap_trip_item (view alternatives vs. commit a change), leaving that distinction to be inferred from 'read only'.

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