Sorted Travel

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description correctly focuses on other traits: alias normalization behavior and a citation constraint restricting domains to sorted.travel's place_url/source_url. This is meaningful added context beyond the 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?

Purpose is front-loaded in the first sentence, followed by naming convention, disclaimer, and citation rule. Every sentence adds a usable instruction, though the trailing citation rule reads more like response-handling guidance than tool selection and slightly pads the entry.

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 naming, disclaimers, and citation sourcing. For a low-complexity read-only lookup this is nearly complete; only the user_visas code semantics live solely in the schema.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds value by stating that common aliases are accepted and normalized, which is not conveyed by the schema's per-field descriptions. The naming example overlaps the schema's own 'Use USA, not United States' notes.

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') and resource ('visa requirements') plus the two defining inputs (passport country and destination country). No sibling covers visas, so an agent can select this tool unambiguously from the destination/weather/profile family.

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

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

Provides clear usage context: how to phrase country inputs and an explicit caveat that output is 'planning context, not official immigration advice.' It does not name any alternative tool, but there is no competing visa sibling, so the caveat plus naming guidance is sufficient.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, but the description adds behavior they cannot express: the tool returns data only and a successful call must be followed by render_destination_info so the place card renders. It also sets expectations about output content and redirects to place_url for the full page, which is real orchestration context.

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 default-tool statement and the render follow-up are front-loaded and easy to scan. There is mild redundancy: the generic-info examples are restated in 'Do not use get_destination_weather for those generic info asks', which partially repeats the weather boundary that follows. Cost is small relative to the routing value.

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, and annotations cover the safety profile. For a single-param read tool the remaining burden is routing and post-call choreography, both of which are addressed, including the mandatory render step and the resolve_destination prerequisite.

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 handle format is already documented, so the baseline would be 3. The description earns extra credit by adding meaning beyond the type: it names concrete handles (hanoi, paris, tokyo) and, more importantly, tells the agent to call resolve_destination first when only a city, country, or airport name is available — a constraint the schema does not encode.

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 immediately enumerates what comes back: brief, safety, currency, phone code, eSIM notes, taxi apps. It explicitly distinguishes itself from the closest siblings, get_destination_weather and resolve_destination, so an agent can route without opening any schema.

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

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

Gives explicit when-to-use triggers with example utterances, a prerequisite routing rule ('if you only have a city, country, or airport name, call resolve_destination first'), and named exclusions for both get_destination_weather and bookings. The weather boundary is spelled out in both directions (generic info vs. explicit forecast/climate asks).

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 this as read-only, idempotent, non-destructive, and closed-world, while the description adds important workflow behavior: the tool returns data only and must be followed by render_destination_weather. It also discloses the Foreca source, credit requirement, and place_url handoff, which are not in 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?

The description is front-loaded with purpose and then structured as routing rules, exclusions, prerequisites, and post-call requirements. It is longer than typical but mostly information-dense, with minor repetition around when-to-visit behavior.

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

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

Given the tool's one-parameter schema, existing output schema, and read-only annotations, the description covers the remaining decision-critical context: correct input format, fallback resolution, sibling alternative, attribution, and required rendering follow-up. Nothing essential for correct selection or 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 coverage is 100% and the single destination_handle parameter is already documented with examples. The description adds meaningful routing semantics by saying to use a sitemap handle and to call resolve_destination first when only a city, country, or airport name is available, though its examples partly repeat the schema.

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

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

The description states a specific verb and resource set: current weather, forecast, climate, and when-to-visit notes for one place. It also distinguishes the tool from get_destination_info by naming generic-info queries such as "info on Dubai" and "what is Tokyo like."

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 explicitly lists when to use the tool, when not to use it, and the correct alternative for generic destination information. It also gives prerequisites: use a sitemap handle or call resolve_destination first, then call render_destination_weather afterward.

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?

Going well beyond the annotations (which already mark this readOnly, idempotent, non-destructive), the description discloses the required OAuth scope (profile.read), the exact data returned, and what is deliberately excluded. It also surfaces the non-obvious host-visibility behavior around should_list_profile_preference_tools, which an agent could not infer from structured fields.

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

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

Front-loaded with purpose in the first sentence, then auth/return details, which is good ordering. The closing paragraph about OpenAI/ChatGPT tools/list gating is host-implementation metadata rather than something the calling agent acts on, so it is the one piece that does not fully earn its space.

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?

Auth requirement, returned field set, and explicit exclusions are all covered, and an output schema exists so return structure need not be restated. For a zero-parameter read tool, there is no meaningful gap left for an agent to guess at.

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 no parameters, so the schema has nothing to explain and the baseline of 4 applies. The description correctly implies a no-argument call by framing this as a read of the signed-in traveler's own preferences.

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 pairs a precise verb ('Read') with a scoped resource ('the signed-in traveler's saved Sorted profile preferences'), and the body enumerates exactly which preference categories come back. This cleanly separates it from the sibling update_profile_preferences, which mutates the same resource.

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

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

Usage is implied rather than stated: an agent can infer this is the read path for profile data, and the negative boundary ('Does not return chat history or account-deletion controls') helps. But it never explicitly says when to reach for this versus update_profile_preferences or which sibling to prefer for adjacent destination data.

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 readOnly/idempotent/non-destructive. The description adds real behavioral context beyond them: 'This tool returns data only' plus the mandatory follow-up render call, and that ANYWHERE 'skips flight prices and direct-route filters'. It does not disclose pagination/result-limit behavior, so not a full 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?

Dense but well front-loaded, leading with purpose then usage rules. A few instructions restate schema/enum content (e.g. supported origin list), which is minor redundancy given the flat paragraph structure.

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 tool with an output schema, the description covers the risky decision points (source_location_code selection, tag mapping, filter defaults, downstream render call) and omits return-value explanation that the output schema already handles.

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 baseline is 3, but the description adds semantics beyond the schema: 'Never set a filter to false just because they did not mention it', the explicit continent→tag mapping (Africa→africa, etc.), passport alias normalization, and ANYWHERE constraint rules. These meaningfully shape correct invocation.

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 ('Recommend destinations from a departure airport') that unambiguously distinguishes it from siblings like resolve_destination and get_destination_info. An agent can tell immediately what this tool produces.

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 when-to-use ('whenever the traveler asks where to go'), when-not ('Do not use this for live flight tickets'), and alternatives/next-steps (call render_recommended_destinations). It also routes the ANYWHERE vs supported-airport decision and the direct/cheap/flight-time cases.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral value beyond them: the mandatory upstream dependency on get_destination_info and the requirement to pass structuredContent unchanged, which prevents the agent from synthesizing its own input.

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, then the precondition, then the guardrail. Nothing extraneous; every sentence carries a distinct instruction.

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?

Output schema exists so return values need no explanation, annotations cover the safety profile, and the single parameter is fully documented. The remaining thing an agent needs — the required call ordering and no-fabrication rule — is present in the description.

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 schema already states the parameter is the full structuredContent from get_destination_info, so the baseline is 3. The description reinforces the provenance constraint and adds the 'pass it through unchanged' rule, giving semantics beyond the type definition.

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 ('Render the destination facts card'), which cleanly separates it from the sibling render_* tools (weather, recommended destinations). An agent can identify the tool's job 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 an explicit precondition ('Always call get_destination_info first') and an explicit prohibition ('Do not invent destination facts'), which tells the agent exactly when this tool applies and when its input is invalid. This is a complete usage contract, not just implied context.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the bar is lower. The description adds the non-obvious behavioral constraint that the payload must be the verbatim structuredContent from another tool rather than fabricated data, which is genuinely useful. It stops short of describing rendering side effects or failure modes when the payload is malformed.

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, zero filler, with the purpose front-loaded and the dependency instruction immediately after. Everything 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?

An output schema exists so return values need no explanation, annotations cover the safety profile, and the one parameter plus its required provenance are both documented. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the schema already says 'Pass it through unchanged', so the baseline would be 3. The description adds value by telling the agent where the payload must come from (get_destination_weather's structuredContent), which the schema does not state, resolving the provenance of the opaque nested object.

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 ('Render the destination weather card') and is easily distinguished from the sibling get_destination_weather (fetch) and render_destination_info (different card). An agent can pick it out of the sibling list 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 an explicit prerequisite and sequencing rule ('Always call get_destination_weather first, then pass its structuredContent here') plus an exclusions rule ('Do not invent weather data'), naming the sibling that supplies the data. This is about as prescriptive as a rendering tool can be.

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 safety (readOnlyHint, idempotentHint, destructiveHint), so the description only needs to add behavior beyond that. It adds the critical constraint that destination data must come from get_recommended_destinations, and that filtering is allowed. This is useful context, though it doesn't describe the rendering mechanics or error behavior. Since annotations carry the safety profile, a 4 is appropriate.

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 concise sentences with zero waste. The purpose is front-loaded, then usage guidance, then a clear prohibition. Every sentence earns its place 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 render tool with 9 parameters but only 1 required, and an output schema present, the description covers the key flow: when to call, what to pass, and that filtered subsets are acceptable for follow-ups. It doesn't explain return values, but the output schema likely covers that. The prerequisite call and data-source constraint are clearly stated, making it sufficiently complete for correct invocation.

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 each parameter already has a clear description (e.g., 'Months from the recommendation result'). The description adds little beyond the schema—only the flow note about passing 'related fields' from the previous call, which is already implied by the schema descriptions. Baseline 3 is correct because 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?

The description clearly states the tool's purpose: 'Render the destination recommendations carousel.' It also clarifies the relationship with get_recommended_destinations, distinguishing it from sibling render tools like render_destination_info and render_destination_weather. The verb 'render' plus the specific resource is unambiguous.

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

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

Explicitly instructs when to use this tool: 'Always call get_recommended_destinations first for a new search, then pass its destinations... For a follow-up that narrows an existing list, call only this tool.' It also states a negative constraint: 'Do not invent destination cards.' This gives clear routing vs. 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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine context beyond that: it returns a few live matches, resolves one place per call, and warns 'do not invent a handle', disclosing the fuzzy/lookup nature and a hallucination guard. Minor gap: it doesn't say what happens when no match is found.

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, followed by a compact usage clause and then imperative routing instructions. Every sentence carries actionable content; nothing is repeated from the schema or annotations.

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 needn't be explained in depth, and annotations cover safety semantics; the description still names the key returned fields and the follow-up tool chain. For a two-parameter lookup tool, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so both query and page_size are already documented, and the description adds only marginal meaning via examples of accepted query forms (city, country, region, IATA). The 'one place per call' constraint is a useful clarification of query semantics, but page_size is left entirely to the schema — correct baseline of 3.

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

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

States a specific verb ('Resolve') and target resource ('Sorted destinations') with concrete input shapes (city, country, region, airport) and examples (paris, hanoi, IATA code). An agent can immediately distinguish it from siblings like get_destination_info or get_destination_weather.

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 trigger condition: 'when the traveler names a place and you do not already have a sitemap handle'. It also routes post-resolution behavior precisely — get_destination_info for generic info, get_destination_weather only for weather/forecast/climate, get_recommended_destinations with airport_code for ranking — including an explicit 'not weather' exclusion.

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 context beyond annotations: required auth scope, the full allow-list of editable fields, explicit non-actions (no account deletion, no unlinking, no email change), and the conditional tools/list visibility for OpenAI/ChatGPT hosts. The mutation semantics match annotations (readOnly=false, destructive=false), so nothing conflicts.

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 action and scope in the first sentence, then layers auth, allowed fields, and boundaries efficiently. The closing paragraph about ChatGPT tools/list visibility is somewhat meta but short and does explain a host-specific behavior.

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 no explanation, and the description covers auth, allowed fields, and mutation boundaries well. It could say a bit more about per-field value formats or failure behavior, but for a 3-parameter preference updater it is nearly complete.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns an extra point by enumerating the permitted field_name values (currency, units, passports, visas, lists.bookmarked, etc.), which the schema only vaguely describes as 'Only traveler profile fields are allowed'.

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 (Update), resource (saved traveler profile preference), and scope (one field, signed-in user). This clearly reads as the write counterpart to the sibling get_profile_preferences, so an agent can route between them without opening either schema.

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

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

Gives clear preconditions (OAuth 2.0 token with profile.write scope) and explicit scope exclusions (cannot delete the account, unlink messengers, or change email). It stops short of naming when to prefer an alternative tool, but the context needed to invoke it correctly is present.

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