Sorted Travel

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description still adds value by disclosing the payload contents and the handoff to place_url for the full page. It doesn't address auth, rate limits, or error behavior, so it's not exhaustive.

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

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

Front-loads the purpose, then routes alternatives in priority order, ending with an explicit exclusion. Every sentence carries a distinct instruction; there is 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 spelled out here. For a single-handle read tool with rich annotations, the description supplies the payload gist, the prerequisite tool, and the sibling routing — 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% and the parameter already documents itself as a 'Sorted sitemap handle such as paris, hanoi, or tokyo' with examples. The description's 'Use a sitemap handle such as hanoi, paris, or tokyo' largely repeats that, adding no format or validation nuance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get Sorted on-the-ground facts for one destination handle') and then enumerates exactly what comes back (brief, safety, currency, phone code, eSIM notes, taxi apps). It clearly separates itself from destinations.weather and destinations.resolve by name, so an agent can pick 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?

Explicit routing: use destinations.resolve first if you only have a city/country/airport name, use destinations.weather for weather/climate/best-time, and a hard exclusion ('Do not use this for bookings'). Both the when and the when-not are stated, with named alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that: omitted filters fall back to Sorted's defaults rather than being disabled, passport values are normalized against the visa table (aliases like United States accepted), and destination lists must never be invented. It does not discuss result ordering or pagination, but with an output schema present that omission is minor.

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

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

The purpose is front-loaded in one line, followed by a compact block of imperative rules that are each actionable. It is slightly long and mildly repetitive (both 'Never invent a destination list' and 'Do not use this for live flight tickets' guard against the same failure mode), but every sentence carries operational 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?

For a 25-parameter, zero-required tool with rich annotations and an output schema, the description covers the highest-risk failure modes: accidental filter setting, implicit false values, and passport value formats. The main residual gap is that the dependent flag pairs (e.g. max_price paired with is_price_filter_enabled) are only implied in the schema rather than explained here, but that is a narrow miss given the schema already documents each field.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the omit-don't-set-false convention that governs all 25 optional arguments, and the passport naming normalization rule (visa-table names, aliases normalized) that prevents enum-mismatch failures. That is real semantic content beyond the field-level 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 ('Recommend') and resource ('destinations') with a scoping constraint ('from a departure airport'). It also draws a boundary against out-of-scope use ('Do not use this for live flight tickets'), so an agent can separate it from destinations.info, destinations.resolve, and visa.check 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?

Explicitly says when to use it ('Use this whenever the traveler asks where to go') and when not to, plus a concrete rule set for filter handling: only set filters the traveler explicitly asked for, omit everything else so defaults apply, never set a filter false by implication, and don't enable direct flights unprompted. This is exactly the when/when-not/alternative guidance the dimension asks for.

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 (read-only, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real value beyond them: it discloses the 'few live matches' nature of the result, the one-place-per-call constraint, and the 'do not invent a handle' guard against hallucination.

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 core action is front-loaded in the first sentence, followed by the when-to-use condition and the chaining instructions. Every sentence carries distinct information with no filler, and the multi-line formatting makes the call sequence scannable.

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?

Even though an output schema exists and return values need not be described, the description summarizes the returned fields (handle, name, country, airport_code, place_url) specifically to enable tool chaining, which is exactly what an agent needs here. Nothing required 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 both parameters (query, page_size) are documented there with ranges and defaults, so the schema carries the load. The description adds only the 'one place per call' framing, which is closer to behavioral guidance than parameter semantics; baseline 3 is appropriate.

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

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

Specific verb (resolve) plus resource scope (city, country, region, or airport onto Sorted destinations). It clearly positions itself as the entry point that produces the handles/airport codes the sibling tools consume, so an agent can place it relative to destinations.info, destinations.recommend, and destinations.weather without opening a schema.

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

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

Gives an explicit trigger condition ('when the traveler names a place and you do not already have a sitemap handle or IATA code') plus the inverse case of just going straight to a handle. It also routes the next call explicitly: handle to destinations.info/weather, airport_code to destinations.recommend. Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds non-schema behavior: the Foreca data source with a citation obligation, direction to place_url for the full page, and a hard exclusion for bookings. It does not describe pagination or rate limits, so it is strong but not exhaustive.

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

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

Front-loaded with the capability list, then routing rules. Every sentence carries actionable content, though the Foreca citation policy and place_url instruction make it longer than strictly needed given the title is absent.

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

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

With an output schema present, the description need not explain returns, and annotations cover the safety profile. Given one required parameter and a rich output schema, the description supplies everything an agent needs: capability scope, prerequisites, alternatives, and exclusions.

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 parameter is fully documented there, including the same handle examples the description repeats. The description adds the resolve-first prerequisite, which is useful but is usage guidance rather than parameter meaning, so the baseline 3 holds.

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 ('Get current weather, forecast, climate, and best time') and enumerates the covered sub-capabilities. It explicitly distinguishes itself from a hypothetical separate best-time tool and from generic weather APIs, so the agent can identify it without cross-referencing 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?

Gives explicit when-to-use ('current weather, a 7-day forecast, monthly climate averages, or "when should I go"'), a prerequisite ('If you only have a city, country, or airport name, call destinations.resolve first'), a preference signal ('Prefer this over generic weather APIs'), and an exclusion ('Do not use this for bookings'). This is close to complete routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the OAuth 2.0 profile.read scope requirement and an explicit negative scope (no chat history, no account-deletion controls).

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

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

Three tight sentences: what it does, what it requires, what it returns, and what it excludes. Front-loaded and 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 zero-parameter read with an output schema, an auth requirement, and annotations covering the safety profile, 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. The description correctly implies a no-argument call on the signed-in user and adds no parameter confusion.

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

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

States a specific verb (Read) and resource (signed-in traveler's saved Sorted profile preferences), and enumerates the exact fields returned (passports, home airport, currency, units, interests, airlines, bookmark/ignore lists). The read framing clearly contrasts with the profile.preferences.update 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?

Usage is implied by the resource (fetch the caller's own preferences) and the auth scope is stated, but the description never says when to prefer this over alternatives or that no arguments are accepted. Adequate but with a clear gap in routing guidance.

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

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

Annotations already declare the write/idempotency/destructive profile, and the description adds genuinely new context: the required auth scope, the exhaustive set of writable fields, and the operations that are explicitly out of reach. It reinforces rather than contradicts destructiveHint=false. It does not describe failure behavior or partial-update semantics.

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

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

Front-loaded with the core action, then auth requirement, then allowed fields, then boundary exclusions. Every sentence carries information an agent needs, with no filler or repetition of 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 an output schema present, annotations covering the safety profile, and 100% schema description coverage, the description fills the remaining gaps: auth scope, permitted fields, and destructive boundaries. 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 description coverage is 100%, so the baseline is 3, but the description adds value by enumerating the concrete allowed field names (currency, units, sourceAirportCode, passports, visas, lists.bookmarked, etc.) that the schema only gestures at with 'Only traveler profile fields are allowed.' It still leaves the operation enum semantics to the schema.

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

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

The description names a specific verb and resource ('Update one saved traveler profile preference for the signed-in user') with a clear single-item scope. It is unambiguous and easily separated from the read-only sibling profile.preferences.get, though it never explicitly names or contrasts 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?

It gives clear preconditions (OAuth 2.0 token with profile.write scope) and explicit exclusions ('cannot delete the account, unlink messengers, or change email'), which is strong when/when-not guidance. It stops short of pointing to an alternative tool for those excluded operations.

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=true, idempotent=true, openWorld=false, destructive=false, so safety is covered. The description adds genuine context beyond that: alias normalization behavior, the non-authoritative nature of the result ('not official immigration advice'), and conditional linking of place_url. It stops short of describing the response shape, but the output schema exists for 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?

Four short sentences, front-loaded with purpose, then naming rules, then the disclaimer. Each line carries usable information with no filler, though the naming-convention sentence and the disclaimer 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 an output schema present, return values need not be explained, and the description covers the key agent-facing caveats: input naming conventions, alias tolerance, non-authoritative status, and conditional URL linking. Adequate for a 4-param, well-documented read tool.

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

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

Schema description coverage is 100% and two params are enums, so the schema does the heavy lifting — baseline 3. The description's note about naming conventions and alias normalization is largely redundant with the enum constraints, though it mildly reinforces the format and mentions handle-based linking for destination_handle.

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 ('Check') plus the resource ('visa hassle for a passport country and destination country'), which is unambiguous about what the tool returns. No visa sibling exists among the destinations.*/profile.* tools, so sibling differentiation is not required. The phrasing 'visa hassle' is slightly informal but the required params make the intent obvious.

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?

Offers input-format guidance ('Use visa-table country names... Common aliases are accepted') and a scope caveat ('planning context, not official immigration advice'), which imply when it applies. However, it never states when to reach for this tool versus alternatives or prerequisites (e.g., needing user_visas to be meaningful). Usage is implied rather than explicit.

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