Tineo

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 burden is lower. The description adds real behavioral context beyond them: generic adapters may attach safe Tineo-owned CTA links, and a card with bookingLink=null is metadata only rather than a booking handoff or live inventory. This meaningfully clarifies what the output can and cannot do.

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

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

Four compact sentences, with the core purpose front-loaded before the exclusion and the output caveats. Each sentence carries a distinct constraint, though the phrasing ('truthful implementation status', 'validated generic adapters') is denser than needed.

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

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

There is no output schema, so the description compensates by explaining the bookingLink=null case and CTA-link behavior. With all 11 parameters optional and fully schema-documented, plus annotations covering safety, the remaining gaps are minor and an agent has enough to invoke 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?

Schema description coverage is 100%, so all 11 parameters are already documented, making 3 the baseline. The description references search intent (mapping loosely to searchTerm) and bookingLink semantics but adds no syntax, format, or default detail beyond the schema. No parameter-specific value is added.

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 ('Return') and resource ('Tineo's travel-affiliate catalog') with the qualifier 'truthful implementation status'. It distinguishes itself from booking-link siblings by saying it is 'never for a link to a specific or previously searched travel result', so an agent can separate it from flight_booking_link/ground_transfer_booking_links. Slightly muddied by the abstract phrase 'truthful implementation status'.

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

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

Gives an explicit use condition ('Use only for questions about supported affiliate programs') and an explicit exclusion ('never for a link to a specific or previously searched travel result'), which routes the agent toward the booking-link tools. It does not name the sibling tools directly, so the alternative identification is inferred 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial behavioral context beyond them: defaults are derived from the trip, location must be a city, amenity filtering is enum-only, and on an 'unavailable' status the agent must not retry but surface a prefilled fallback URL. That failure-handling guidance is genuinely non-obvious.

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, then stacks constraints in tight imperative sentences with no filler. Every clause carries a distinct operational instruction (derivation, location rule, filter limit, failure handling).

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 15-parameter, output-schema-less tool, it covers the trip-derivation model, the key input constraints, and even references return fields (structuredContent.status, fallback_search_url) that would otherwise be opaque. Not exhaustive on the less-critical numeric params, but complete enough to invoke 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 only 47%, the description compensates on the parameters that matter most: it clarifies trip-derived defaults, the city-vs-country constraint for location, and the enum-only limitation on amenities. The remaining parameters (price, room_type, min_beds, currency) are self-descriptive from their names, so the gap is modest.

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 (Search) plus resource (Airbnb listings) and scopes it to an existing Tineo trip. This cleanly distinguishes it from the sibling assistant_airbnb_search_user, which lacks the trip anchor.

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 operating context: derive location/dates from the trip unless overridden, require a city not a country, and use only the amenities enum (no free-text). It even offers fallbacks (hotel search, support ticket) on failure. It stops short of explicitly naming the sibling alternative (assistant_airbnb_search_user) and when to use that 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 readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description goes further by disclosing what it returns ('slim list of cards'), the absence of a free-text filter, and — most valuably — an explicit do-not-retry rule tied to structuredContent.status with concrete alternatives.

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 purpose and routing, then layers constraints and failure handling. Despite being several sentences, each one carries actionable information (sibling exclusion, filter limits, fallback path) 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?

No output schema exists, so the description correctly fills that gap by naming the card fields returned, and it covers the failure mode an agent would otherwise mishandle (retrying an 'unavailable' search). For a 14-parameter, read-only search tool this is 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 only 43%, so the description must compensate, and it does for the highest-risk parameter: location 'must be a city or area, not a whole country (ask the user which city).' It also constrains the amenities parameter to the enum-only surface. It adds real meaning beyond the schema, though it leaves the numeric/date parameters (price_min/max, min_beds, max_results) 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?

States a specific verb and resource ('Search Airbnb listings by location and dates') and explicitly distinguishes itself from the sibling trip-based search ('Use when the user is not asking about a specific trip in Tineo'). An agent can route between assistant_airbnb_search_user and assistant_airbnb_search_trip 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 explicit when-to-use and when-NOT-to-use (the Tineo trip case), names the supported filtering surface (amenities enum only, no keyword), and prescribes next steps when status is 'unavailable' (fallback URL, hotel search, support ticket). Nothing about selection 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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description goes beyond that by disclosing the actual classification thresholds — the 180-day window and the trip-end comparison rule — which is real behavioral context an agent cannot get from the annotations or 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?

A single tightly written sentence with the action front-loaded and the flag criteria enumerated parenthetically. 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 read-only tool with no output schema, the description conveys what is examined and the categories that will be flagged, which is enough for correct invocation. It stops short of describing the actual return shape or what happens when trip_id is omitted, which leaves a minor gap.

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

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

Schema description coverage is 100% for the single trip_id parameter, so the baseline is 3. The description only lightly reinforces the schema by tying trip_id to the 'expiring before trip end' criterion; it does not add format, default-behavior, or omission semantics beyond what the schema already says.

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 (audit), a specific resource (the user's travel documents: passports, visas, insurance), and the exact outcome criteria (expired, expiring soon <180 days, expiring before trip end). No sibling tool does document auditing, so an agent can select this without 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?

Usage is implied rather than stated: the optional trip_id and the 'expiring before trip end' criterion signal that the tool is for pre-trip document checks. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. the related travel_document_assign_trip), so guidance remains inferential.

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 declare the generic profile (not read-only, not destructive, not idempotent), while the description adds the transaction semantics that actually matter here: atomic all-or-nothing failure behavior and a hard 20-item cap. It also discloses the cross-entity validation rule that dates must sit inside the parent trip's range, which is not derivable from the 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?

Front-loaded with the action, followed by the constraints that most affect correctness (atomicity, cap, date bounds, schema lookup). Every sentence carries distinct information; nothing is restated 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?

For a multi-item write tool with no output schema and no annotations beyond generic hints, the description covers atomicity, limits, validation bounds, and prerequisite lookups/updates. The only gap is what comes back after success (e.g., created segment IDs), which an agent would have to discover empirically.

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 trip_id and segments are already documented in the schema; the baseline there is 3. The description adds real value by explaining that the shape of `fields` is type-dependent and must be looked up via segment_get_schema, which is a semantic dependency the schema only gestures at.

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+mode: 'Create multiple segments in a trip in one call,' which immediately distinguishes it from the single-segment sibling segment_create. The batch nature is stated in the title and first sentence, so an agent can pick between them without opening schemas.

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 operating conditions: max 20 segments per call, all-or-nothing validation, dates must fall within the parent trip dates, and it routes to segment_get_schema for field names and to trip_update when the trip must be extended first. This is exactly the when/when-not/alternative guidance expected.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds value beyond that by stating the return contract ('returns stored city IDs and location details') and reinforcing the non-mutating behavior, which matters because there is 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?

Three short sentences with zero filler: purpose/scope first, then the return payload, then the non-mutation caveat. Every sentence earns its place and the key constraint is front-loaded.

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

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

With no output schema, the description compensates by describing what comes back (city IDs and location details), and it covers purpose, usage stage, and side-effect posture. What remains unstated is matching behavior (exact vs. partial/alias ranking) and whether results are scoped to the user's saved data only, which keeps it from a 5.

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%: query length limits and the limit range/default are fully documented in the schema, and the description only restates 'city name or alias.' Per the baseline for fully covered schemas, this is a 3 – no extra syntax, matching, or ranking semantics are added.

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?

Names a specific verb ('Search') and resource ('the saved city catalog') and states the lookup keys (city name or alias). The 'saved catalog' scoping does implicitly distinguish it from open-ended siblings like places_search, but no sibling is named outright, so it stops short of a 5.

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

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

'...before adding a city to a trip' gives the workflow stage where this tool belongs, and 'Search results do not add or select a city' draws the boundary against trip_city_add. There is clear context, but no explicit when-not-to-use or named alternative (e.g., places_search vs. this catalog search).

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 non-destructive, so safety is covered. The description adds genuine value by enumerating the diagnostic payload (failure step, error message, likely reason, next steps), which is the only source for return semantics since no 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?

Two sentences, zero filler: the first states scope and trigger, the second lists the return contents. Purpose is front-loaded and nothing 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?

The description covers purpose, trigger, and return contents, which is sufficient for a read-only diagnostic tool with a fully documented two-parameter schema. The one gap is behavior when neither optional parameter is supplied, which is not addressed anywhere.

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 are documented in the schema, including that trip_id resolves the most recent non-clean import. The description adds no syntax or resolution detail 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?

Specific verb ('Triage') plus resource ('failed, held, or partially processed email import') and an explicit statement of what the tool returns. It is clearly distinguishable from the nearest sibling, import_parse_text_preview, though it never names that sibling to reinforce the boundary.

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 trigger condition is clear: use this when an import has failed, is held, or processed partially. It gives no explicit when-not guidance or alternatives, and does not say how to obtain an import_id when one is unknown, but the usage context itself is unambiguous.

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 safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description adds genuine context beyond them by disclosing the return shape (visual cards containing image, rating, price level, and link), which is exactly what an agent needs to decide whether the output fits the task.

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: purpose and return format first, usage condition second. Nothing is redundant and the most decision-relevant information is front-loaded.

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 8 fully documented params, a required category, and annotations covering safety, the description is complete enough to invoke correctly, and it describes the return content in lieu of an output schema. The one meaningful omission is any differentiation from the overlapping sibling search tools.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters including the category enum, dates, and coordinates. The description adds no syntax or format detail beyond echoing the category values, so the baseline 3 is appropriate.

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

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

States a specific verb (search/discover) and enumerates the resources (hotels, restaurants, attractions, activities) plus the return format (rich visual cards). It's clear what the tool does, but it never distinguishes itself from close siblings like search_hotels, search_attractions, or search_tours, so an agent has to guess which to call.

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 sentence 'Use this when the user wants suggestions or things to do/eat/stay near a place' gives real usage context, which implies when to reach for it. However, it offers no when-not guidance and does not name the overlapping alternatives (search_hotels, search_attractions, search_tours), leaving the routing decision 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/non-destructive/closed-world, so the safety profile is covered. The description adds useful behavior the annotations do not: the expected ID prefix schemes (trip:, segment:, travel-document:, document:) and the fact that it returns full text rather than a summary. It omits error behavior for invalid or stale 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?

Two sentences, no filler, front-loaded with the usage condition followed by the parameter format. Every clause earns its place.

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

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

For a one-parameter read tool with annotations covering safety and no output schema, the description supplies purpose, trigger, and ID format. It leaves minor gaps around invalid-ID handling and whether returned text is ever truncated, but nothing essential to invoking 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?

Schema coverage is 100%, so baseline is 3, but the description goes beyond the schema by enumerating the concrete ID formats (trip:{id}, segment:{id}, etc.) that the schema's single `id` string leaves open. That is genuine added meaning for the only parameter.

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

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

States a specific verb (fetch) and resource (the full text of a specific Tineo search result), and distinguishes itself from the sibling `search` tool by positioning search as the producer of the IDs it consumes. An agent can tell them apart 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?

"Use this when the user wants the full text for a specific Tineo search result" gives a clear triggering condition, and it names `search` as the source of valid IDs. It does not state any when-not case, but for a simple read tool that is a minor omission.

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 the meaningful gating condition that deep links must be enabled, implying the tool may not return a link otherwise, but it says nothing about the return shape or the disabled-feature 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 with no filler. It is efficient, though the dense jargon slightly reduces immediate comprehension.

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 3-parameter, read-only tool with a fully covered schema and annotations, most of what an agent needs is present. However, with no output schema, the description should say more about what the 'redirect card' actually contains and what happens when affiliate links are disabled.

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

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

Schema description coverage is 100%, so the schema fully documents trip_id, segment_id, and flight_number, including the optionality and the segment_id-vs-flight_number fallback. The description adds no parameter meaning beyond this, so baseline 3 is appropriate.

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

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

States a specific verb (Return) and resource (a redirect card for comparable flight search for a trip flight), and the 'flight' framing distinguishes it from siblings like train_booking_link and ground_transfer_booking_links. The jargon-heavy phrasing ('Tineo redirect card', 'comparable flight search') is less concrete than it could be, but the purpose is identifiable.

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 conditional 'when affiliate flight deep links are enabled' is a system precondition, not an agent-facing when-to-use rule. It gives no guidance on choosing this over train_booking_link, segment_booking_links, or trip_booking_links. Usage is only implied.

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/non-idempotent/open-world profile, and the description adds two pieces of genuinely non-structured context: a 2-5 second latency warning from the external flight data lookup and the trip-date constraint. It does not mention that repeat calls create duplicate segments, which matters given idempotentHint=false, keeping it below 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?

Three tight sentences; the core action and its composition are front-loaded, followed by the latency caveat and the constraint. 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 compound write tool with no output schema, the description covers purpose, composition, latency, and the date constraint, and points to the remediation tool. It omits failure behavior (what happens if the flight lookup returns no match) and non-idempotent duplicate risk, leaving minor 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 100%, so the schema already documents all five parameters including the airline-vs-airline_code fallback logic. The description adds only the departure_date/trip-date relationship, so the baseline 3 for schema-complete coverage is appropriate.

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

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

States a specific compound action (look up a real flight by number and date, then create it as a segment) and explicitly names the two sibling tools it wraps, flight_quickadd_lookup and segment_create. An agent can distinguish this from calling segment_create directly 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?

Clear context for when to use it (flight lookup + segment creation in one call) and it routes the agent to trip_update when segment dates would fall outside the parent trip dates. It does not explicitly state when to prefer the two underlying tools separately, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read-only profile is covered. The description adds workflow context by framing the call as a pre-creation/pre-edit verification step, but says nothing about lookup failure when no flight matches or the open-world nature of the query beyond the openWorldHint annotation.

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, front-loaded with the verb and resource, followed by the usage trigger. No redundant restatement of the tool name or schema fields; every clause 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 output schema, the agent can still infer the tool returns flight details, and the annotations cover the safety and idempotency profile. The main gap is unstated behavior on no-match or ambiguous airline input, but for a simple lookup this is largely adequate.

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 of the four parameters already carries its own description and example. The description only echoes the field set (airline, flight number, departure date) and omits airline_code, adding no format or disambiguation guidance beyond 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 ('Look up flight details') plus the exact inputs that identify the flight (airline, flight number, departure date). It does not differentiate itself from the closest siblings, flight_quickadd and flight_route_lookup, which an agent would likely weigh against it.

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 triggering context ('when the user gives a flight number and wants to add, preview, or verify a flight') and its sequencing relative to segment creation/editing. It names no alternatives or exclusions, so the agent must infer when flight_quickadd or flight_route_lookup is preferable.

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 and idempotency profile is fully covered. The description adds useful context that it returns matching flights with their flight numbers and feeds into flight_quickadd, but says nothing about result volume, pagination, or empty-route behavior. Given annotations carry the behavioral load, this is adequate but not rich.

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 verb and the key disambiguating condition, then the alternative in the second sentence. No filler.

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

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

For a read-only lookup with no output schema, the description supplies what an agent needs: the required inputs, the fact that it returns flight numbers, the follow-up call, and the sibling to use instead when the flight number is known. Nothing material is missing.

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

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

Schema description coverage is 100%: every parameter (origin, destination, date, airline_code) already has a format hint in the schema. The description restates the same fields at a high level (origin airport, destination, local departure date, optional airline) without adding syntax or constraints beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Find scheduled flights by route and date') and immediately scopes it with 'when the flight number is NOT known'. It distinguishes itself from the sibling flight_quickadd_lookup by naming that alternative. An agent can disambiguate from the other flight tools 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 gives the when ('flight number is NOT known') and the when-not ('use flight_quickadd_lookup instead when the user already has the full flight number'). It also names the downstream step (add via flight_quickadd), completing the workflow 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, openWorldHint and destructiveHint, so the safety and live-data profile is largely structured. The description adds only the implication of 'current' status, without disclosing freshness, refresh behavior, or what happens when status is unavailable; against annotations this is adequate but not rich.

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 capability and followed by the usage trigger. Every clause earns its place 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. The description supplies purpose and trigger together, leaving only minor gaps such as data freshness and behavior when no status is available.

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 segment_id description ('from a trip itinerary or segment details result') already tells the agent where to obtain the value; the id alias is also documented. The description adds nothing beyond the schema, so the baseline of 3 applies.

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

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

The description gives a specific verb+resource ('Get current flight status') plus scope ('for an existing flight segment in a user's trip'), which is precise and distinct from siblings like get_flight_airport_conditions or get_flight_change_history. It does not explicitly name an alternative sibling, so it stops short of a 5.

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

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

It explicitly states the trigger conditions: 'Use this when the user asks if a flight in their itinerary is delayed, canceled, on time, boarding, or has gate/terminal updates.' That is clear positive guidance, but it offers no exclusions or named alternatives for when this is the wrong 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?

With annotations provided, the description still adds real behavioral context: 'Never replaces an existing address' clarifies non-overwrite behavior (relevant given idempotentHint=false), and 'friendly name is paid-Ultra only' adds an entitlement constraint. It doesn't discuss the required 'confirmed' flag or what creation returns, so a 4 rather than 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?

Front-loads the core get-or-create purpose and follows with constraint details. The final sentence about trips@tineo.ai and mail reception is somewhat extraneous to the call decision but still relevant context; overall efficient.

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 a single required param, full schema coverage, and no output schema, the description covers purpose, creation conditions, entitlements, and non-replacement behavior. Minor gaps (the role of 'confirmed') are filled by the schema, so it is largely 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 description coverage is 100%, so the schema already documents operation, confirmed, and friendly_name (including the paid-Ultra note). The description reinforces the friendly_name entitlement but adds little beyond the schema, matching the baseline 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+resource for both modes: 'Read the authenticated user's personal Tineo forwarding address, or explicitly create one.' The dual get/create behavior is unambiguous, though no sibling tool is named or contrasted, which keeps it from 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?

'create one when none exists' and 'explicitly create' give clear conditions for triggering creation. It does not spell out when-not-to-use or name alternatives, but the get-vs-create routing is clear enough to act on.

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, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: accepting establishes a mutual connection and notifies the sender, and it advises user confirmation before the irreversible action. It does not address failure modes (e.g., stale request_id).

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, both front-loaded with the essential action and scope first, then the consequence and caution. No filler or restated title text.

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 mutation whose annotations already declare the destructive, non-idempotent profile, the description supplies the missing pieces: the source of the id, the side effects, and the confirmation requirement. Only minor gaps remain, such as behavior on an invalid or already-resolved request.

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 request_id property already states it is the incoming request id from friend_requests_pending, so the description repeats rather than extends that. Baseline 3 applies since the schema carries the parameter meaning.

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 (Accept) and resource (INCOMING pending friend request) and explicitly scopes it to incoming requests identified by request_id. It also names the sibling tool that supplies the id (friend_requests_pending), so an agent can distinguish it from friend_request_decline, friend_request_send, and friend_request_resend 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 a clear precondition and workflow cue: the request_id comes from friend_requests_pending, and it tells the agent to confirm with the user before calling. It does not state what to do if the request no longer exists or explicitly compare against the decline alternative, so it stops short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: only incoming pending requests qualify, where to source the id, and a required user-confirmation step before the destructive 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 front-loaded sentence carrying the action, the constraint, the id source, and the confirmation rule, with no filler.

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

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

For a one-parameter destructive mutation, the definition covers the action, the eligibility constraint, the parameter source, the confirmation obligation, and relies on annotations for the safety/idempotency profile. No output schema is needed for a simple acknowledge-style action.

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 100% and a single required parameter, the schema fully documents request_id and even names its source. The description restates the same provenance, adding no syntax or format detail beyond structured fields, 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 (decline) plus resource (incoming pending friend request) and constrains scope to INCOMING requests, which cleanly separates it from friend_request_accept, friend_request_send, and friend_request_resend. An agent can identify the correct tool 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 clear preconditions: the request must be an incoming pending one, and the id should come from friend_requests_pending. It also adds an operational guideline ('Confirm with the user before calling'). It does not explicitly name friend_request_accept as the alternate action, but the routing is unambiguous from 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?

On top of annotations (destructiveHint=true, idempotentHint=false, openWorldHint=true), it discloses the key behavioral facts an agent could not infer: this re-sends an email to a third party, requires confirmation first, is throttled on an escalating cadence (60s then 24h), and is capped at 2 resends total.

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 dense sentences that lead with the action and scope, then the confirmation requirement, then the rate limits. No filler and no 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?

For a two-parameter mutation with annotations and no output schema, the description covers actor scope, prerequisite lookup tool, user-confirmation gate, and rate-limit behavior. Nothing material is missing 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 both parameters are already documented in the schema, making 3 the baseline. The description only restates the confirmation requirement and the origin of request_id, adding no new syntax or format detail beyond 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 (resend) and resource (the notification email for an outgoing pending friend request), and narrows scope to YOUR OUTGOING requests identified by request_id. It also points to friend_requests_pending as the source of that id, which cleanly separates it from friend_request_send and friend_request_accept.

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 the precondition (an existing outgoing pending request, id obtained from friend_requests_pending) and a required user-confirmation workflow before calling. It does not explicitly name an alternative tool or say when NOT to use this, but the throttle cap of 2 resends supplies a practical boundary.

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 mark this destructive/openWorld, and the description goes well beyond that, disclosing that a real person is emailed, that confirmation is mandatory, that unregistered emails become invitations, and that the email path returns a deliberately neutral result for privacy. These are exactly the consequences an agent needs before invoking a non-idempotent, outward-facing action.

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 verb+resource, then the mandatory confirmation gate, then parameter constraints, then edge-case behavior. Four tight sentences, none wasted, in a sensible priority order.

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 send tool with no output schema, the description covers the action, required human confirmation, parameter constraints, and the two edge behaviors (invitation fallback, privacy-neutral response). An agent has everything needed to call it safely.

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 meaning beyond the schema: it clarifies the email path can trigger an invitation and always yields a neutral result, and reinforces the confirmation semantics of confirmed. That is genuine added semantic value over the field 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+resource ('Send a friend request') and the two targeting mechanisms (user_id or email), so the agent knows exactly what the tool does. It does not, however, differentiate itself from related siblings like friend_request_resend or friend_request_accept, leaving the routing 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?

Gives a strong, actionable precondition: confirm the recipient with the user first and pass confirmed=true only after agreement, plus the 'exactly one of user_id or email' rule. It stops short of naming alternative tools (e.g. resend for an existing request), so it lacks explicit when-not guidance.

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

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

Annotations already declare the safe read-only profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description earns credit for adding genuine behavior: the incoming/outgoing split and the privacy guarantee that only the counterpart's name is returned, never their email. It omits any note on result size or pagination, keeping it just shy of 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?

Three sentences, each doing distinct work: what is listed and how it is split, what the return contains, and which siblings consume the request_id. Front-loaded and waste-free.

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

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

With no output schema, the description carries the return-shape burden and does so by describing the incoming/outgoing structure and the request_id field. The only gap is absence of pagination or volume guidance for a potentially unbounded list, which is minor.

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 the schema has nothing to explain and the baseline is 4. Nothing in the description needs to compensate for missing parameter documentation.

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 authenticated user's pending friend requests') and immediately adds the meaningful scope distinction of incoming vs outgoing. An agent can distinguish this from friends_list and the accept/decline/resend siblings 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 routes the agent downstream ('Use the returned request_id with friend_request_accept / friend_request_decline / friend_request_resend'), which is strong when-to-use guidance. It stops short of stating when not to use this tool or contrasting with friends_list, so it is clear context without explicit exclusions.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the exact shape of what is returned per friend and an explicit privacy guarantee that other users' email addresses are never returned, which the schema does not express.

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 operation, then return contents, then the privacy constraint. No filler, no repetition of the title, and each sentence carries distinct 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?

With no output schema, the description steps in to enumerate the returned fields, and pagination parameters plus safety hints are already handled by the schema and annotations. An agent has everything needed to call this correctly and interpret the response.

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 page, search and page_size are fully documented with defaults and bounds. The description only says '(paged)' and adds no format or semantic detail 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 ('List the authenticated user's accepted friends') with scope qualifiers that separate it from sibling tools like friend_requests_pending. The parenthetical '(paged)' and the enumerated return fields make the operation 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?

The word 'accepted' implicitly distinguishes this from friend_requests_pending, but the description never names an alternative or states a condition for choosing this tool over siblings. Usage is inferable rather than stated, which is the definition of a 3.

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=false; the description adds valuable context that replace=true overwrites while preserving checked items, and that output is persisted as a pinned note. It does not state the failure behavior when the 3-segment precondition is unmet, which is the main remaining gap.

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 with the action first, then the replace caveat, then the precondition and ID source. Every clause carries information and none is wasted.

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

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

With no output schema, the description does convey the created artifact (pinned checklist note) and the guard condition. It stops short of stating what the agent should do when the precondition fails or how success is signaled, but it is largely sufficient for a 2-parameter 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 coverage is 100%, so both parameters are already documented in the schema (including the same 'preserving checked items' note for replace). The description reinforces rather than adds new syntax or format meaning, 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 (generate/regenerate) and resource (weather- and activity-aware packing checklist) plus the output artifact (pinned checklist note), so the agent immediately knows what this produces. No sibling tool overlaps with packing-list generation, so it is unmistakable in the toolset.

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 (trip must have at least 3 substantive segments) and tells the agent where the required trip_id comes from (trips_list). It lacks an explicit 'when not to use' or named alternative, but no reasonable alternative tool exists in the sibling list.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral context by stating the data is 'cached' and combines two source types, but it provides no further detail on freshness limits or failure modes.

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

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

The description is a single front-loaded sentence with no filler. The parenthetical examples are useful but could be trimmed, making it efficient though not maximally tight.

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 explained, and annotations cover the safety profile. However, the description leaves selection ambiguous against sibling tools that cover the same underlying data, and it omits freshness or parameter-precedence 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?

Schema description coverage is 100% and both parameters are fully documented in the schema. The description's phrase 'for an airport code or flight segment' confirms the two input modes but adds no precedence or mutual-exclusivity detail beyond what the schema already provides, so the baseline of 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?

The description states a specific verb ('Get') and resource ('airport day-of-travel intelligence') with clear scope ('combining cached airport conditions and ground-transportation guides ... for an airport code or flight segment'). It does not distinguish itself from siblings like get_flight_airport_conditions or ground_transfer_booking_links, which overlap in content.

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?

There is no explicit when-to-use guidance, nor are alternatives named. The phrase 'for an airport code or flight segment' hints at input scenarios but does not say when to choose this tool over get_flight_airport_conditions or ground_transfer_booking_links.

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 declare readOnlyHint, idempotentHint, non-destructive and closed-world. The description nonetheless adds a genuinely useful trait beyond them: 'Cache-only ... never triggers an external fetch', which tells the agent results may be stale and that a cache miss will not be refreshed. It stops short of saying what is returned on a miss.

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 what is returned, then the cache-only constraint. 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?

With no output schema, the description usefully enumerates the returned fields, and the annotations cover the safety profile. The remaining gap is the zero-required-parameter case: it never says what happens when no argument is supplied, or what a cold cache returns.

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 all three parameters are already documented in the schema, including route_to's role and flight_segment_id returning both departure and arrival. The description restates these relationships without adding new syntax, precedence, or combination rules (e.g. what happens if both iata_code and route_to are supplied).

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 (get) and resource (cached airport conditions) and enumerates the payload: delay indices, weather, flight rules. The airport/segment scope is clear enough to separate it from siblings like get_trip_weather or flight_status_for_segment, but no sibling is named explicitly, so the differentiation is inferred rather than asserted.

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 two accepted lookup shapes (an IATA code, or a route via route_to, or a flight_segment_id) are described, which implies usage contexts. However there is no explicit when-to-use guidance, no statement of when to prefer this over get_trip_weather / flight_status_for_segment, and no exclusion rules.

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, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds that records are historical and limited to the user's monitored trips, which is useful scoping context, but says nothing about availability, ordering, or return format.

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 well-formed sentence that front-loads the core resource and appends the scoping constraint. No filler, though it could be marginally tighter.

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 lookup with no required parameters, full schema coverage, and complete annotations, the description is adequate to invoke it correctly. Absence of return-shape detail is minor given the low-risk read nature and lack of an output schema.

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

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

Schema description coverage is 100%, so all six parameters (trip_id, since_days, flight_date, airline_code, flight_number, flight_segment_id) are already documented in the schema with formats and defaults. The description adds no filtering semantics or interaction rules beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb (Get) and resource (recorded historical timeline of flight schedule, gate changes, and delays), scoped to the user's monitored trips. The word 'historical' implicitly differentiates it from live-status siblings like flight_status_for_segment, but no sibling is named explicitly, keeping it below 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?

The scoping to 'flights monitored on the user's trips' implies when the tool applies, but there is no explicit when-to-use guidance, no mention of prerequisites, and no named alternative such as flight_status_for_segment for live status. Usage is inferable but not 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: what the response contains (duration and distance per mode, handoff buttons for Uber/Lyft/Waymo/Maps), that ground time excludes airport check-in and security, and which data classes are unavailable.

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 and scope, then layers returns, the 'home' convenience, a caveat about ground time, and an availability disclaimer. Every sentence carries information, though the final two sentences are slightly list-like and 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 must describe return values, and it does so at a summary level (duration/distance estimates plus booking handoff buttons). Combined with full schema coverage of the five parameters, an agent has what it needs, though return format details and pagination/limits remain unspecified.

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

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

Schema description coverage is 100%, so all five parameters including the enum values and the 'home' origin sentinel are already documented in the schema. The description's restatement of the 'home' behavior and the supported modes duplicates rather than extends 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?

States a specific verb (Compare) and resource (route summaries between two places) and enumerates the supported modes, which cleanly separates it from siblings like flight_route_lookup or places_search. An agent can identify this as the multi-modal ground routing tool without opening the schema.

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

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

Gives clear context for use (comparing driving/transit/walking/bicycling between two places) and effective exclusions by stating what is unavailable (fares, detailed legs, flights, ferries), which routes the agent elsewhere for those needs. It does not, however, name a specific sibling alternative or state prerequisites, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds the meaningful scope fact that shared trips are included, but says nothing about latency, rate limits, caching, or how aggregated data is refreshed.

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 sentence that front-loads the scope and then lists the returned metrics with zero filler. Every clause contributes information an agent needs.

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 the return payload and does so by naming the four metric groups. Combined with the zero-parameter schema and read-only annotations, an agent has everything needed to invoke 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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The enumeration of returned metrics is useful but belongs to output disclosure rather than parameter semantics.

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 (Get) and resource (lifetime travel summary statistics) and enumerates exactly which metrics are returned: total trips, completed trips, total segments, and segment counts by type. The scope 'across all owned and shared trips' also distinguishes it from per-trip tools like get_trip_expense_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?

The phrase 'lifetime travel summary statistics across all owned and shared trips' implies this is the global aggregate tool, as opposed to per-trip siblings, but no when-to-use or when-not-to-use condition is stated and no alternative tool is named. Usage is only inferable.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds that settlements are 'calculated' (a computed, not stored, result), which is useful context, but says nothing about authorization needs, data freshness, or edge cases. With annotations carrying the behavioral load, a 3 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?

A single sentence, front-loaded with the verb and resource, listing the concrete outputs with zero filler. Every clause earns its place.

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

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

For a read-only summary tool with no output schema, the description adequately enumerates the returned data (totals, per-currency breakdowns, balances, settlements). Annotations cover the safety profile and the schema covers both params, so nothing critical is missing; only deeper behavioral detail is absent.

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% – trip_id and include_settlements are both fully documented, including the default for include_settlements. The description's mention of 'settlement suggestions' loosely maps to include_settlements but adds no syntax or format detail beyond the schema. Baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb (Get) and resource (trip expense summary) and enumerates the outputs: spend totals, per-currency breakdowns, traveler balances, and settlement suggestions. An agent can tell it apart from siblings like get_travel_stats or trip_details, though it never names an alternative 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?

The phrase 'for a trip' and the settlement/balance focus imply when it is useful, but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage is inferred from purpose 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context: the forecast is bounded to trip dates with confidence tiers, and omitting city_id on a multi-city trip returns the available city IDs rather than failing. It still doesn't describe pagination or response shape, but that gap is minor given 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 sentences, no filler, and the detail-mode behavior is front-loaded before the prerequisite. The leading 'Get trip weather' clause is mildly redundant with the title, keeping it off 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?

For a read-only lookup with an output schema and 100% parameter coverage, the description supplies the mode semantics, the trip-scoping constraint, and the city-fallback behavior an agent needs. Nothing critical is missing, though explicit sibling routing would make it fully self-sufficient.

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 every parameter, including the hours/detail/city_id interplay, is already documented in the schema. The description restates the detail-mode mapping and the city_id fallback behavior without adding syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource ('Get trip weather') and then distinguishes the three detail modes by what each returns, so an agent can tell daily from current/hourly. It does not explicitly contrast itself against nearby weather-related siblings such as get_flight_airport_conditions, so it stops short of a 5.

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

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

It gives the required prerequisite ('Provide trip_id from trips_list') and implicitly routes detail=current/hourly to single-city near-term conditions, but never states when to prefer this tool over alternatives or any exclusion cases. Usage is implied rather than prescribed.

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 safety is covered. The description adds genuinely new behavioral context: these are affiliate handoffs and the cards do not represent live availability, prices, or confirmed bookings — an important expectation-setting detail beyond the structured fields. It does not describe the shape of the returned cards, but no output schema exists to fill that gap either.

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 tightly written sentences with no filler; the core purpose is front-loaded and the caveat follows immediately. Every clause earns its place.

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

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

For a 7-parameter, link-generation tool with full schema coverage, rich annotations, and no output schema, the description covers purpose and the key limitation that prevents misinterpreting results as live prices. It could optionally note what the response contains (e.g., link list), but nothing essential to 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% with detailed per-parameter docs (currency fallback chain, trip_id defaults, passenger limits), so the schema does the heavy lifting. The description only echoes the required route and date conceptually ('dated pickup and drop-off route') and adds no format or semantic detail beyond it — 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 ('Return') plus specific resource ('Welcome Pickups and GetTransfer affiliate cards') scoped to a 'dated pickup and drop-off route'. An agent can immediately distinguish this ground-transfer link tool from flight_booking_link, train_booking_link, and segment_booking_links 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 sets a clear usage context and a strong exclusion ('provider search or quote handoffs only, not live availability, prices, or confirmed bookings'), which tells the agent when NOT to rely on it for actual availability or pricing. It stops short of naming an alternative tool for when real prices are needed, so it falls just 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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description reinforces that nothing is saved, but adds no further behavior such as parse failure modes, whether results are cached, or rate limits; with annotations carrying the load, a 3 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?

Two tight sentences with the no-save guarantee and the workflow trigger front-loaded; zero filler and nothing 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?

For a tool with no output schema, the description tellingly names the return payload ('proposed itinerary segments'), which is the key thing an agent needs. It does not detail the structure of those previews or what happens on unparseable input, leaving a small gap.

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

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

Schema description coverage is 100%, so all four parameters (text, trip_id, user_hint, max_segments) are already documented in the schema, including the default of 10 and the 1-20 range. The description adds no syntax, format, or semantic detail 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 ('Parse pasted travel confirmation text') plus the output ('proposed itinerary segments') and the crucial scope qualifier 'without saving anything'. This cleanly separates it from write siblings such as segment_create and batch_segment_create.

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?

'Use this before creating segments from copied email, PDF, or booking text' gives an explicit trigger condition and workflow position. It stops short of naming the alternative tools (e.g., batch_segment_create) or stating when this preview is unnecessary, but the context is unambiguous.

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 a safe, idempotent, read-only, non-open-world operation, so the safety burden is covered. The description adds genuinely useful behavioral context beyond that: a consent requirement and email-confirmation step. However, it says nothing about what the search returns or matching behavior, so it adds only moderate value on top of 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?

Two tight sentences with the purpose front-loaded and the workflow guidance following. Every clause earns its place, though the second sentence bundles several instructions (sequencing, consent, email confirmation) fairly densely.

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-only search with no output schema, the description covers purpose, sequencing relative to traveler_add, and a consent precondition. The main remaining gap is that it never indicates what the search returns, which would help an agent 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?

Schema description coverage is 100% for the single 'names' parameter, and the schema documents that it is the names matched against prior participants. The description adds no syntax, format, or matching detail beyond the schema, so the baseline 3 for full coverage 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: 'Search people the authenticated user previously added to trips.' An agent can immediately tell this queries prior trip participants. It does not explicitly differentiate from similarly named siblings like trip_travelers or friends_list, but the purpose itself 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 positions the tool in a workflow: 'Use before traveler_add,' which names the alternative/next step and when to invoke it. It also adds a precondition (obtain explicit invitation consent). It stops short of stating when NOT to use it, so it is clear context rather than full routing guidance.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-open-world, non-destructive), so the description isn't burdened with disclosing safety. It adds the 'typeahead' behavioral nature and states return content (resource links to trips), which is modest added value beyond the schema 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 tight sentences, front-loaded with the core action and scope, and the return behavior. Every clause earns its place with 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?

With an output schema covering return values and annotations covering the safety profile, the description needs only to establish intent and scope, which it does. It is nearly complete, though the distinction from the generic 'search' and 'trips_list' siblings could be sharper.

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

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

Schema coverage is 100% with a single 'query' parameter already documented ('Search text; may be empty.'). The description adds no syntax, format, or matching semantics beyond what the schema provides, 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 gives a specific verb (typeahead search), resource (the user's Tineo trips), and a narrowing scope (for composer @-mentions), which is far more informative than the title 'Find Trips to Mention'. It does not explicitly name a sibling it differs from, so it falls short of a 5 despite being clear.

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 'for composer @-mentions' implies the usage context (populating a mention autocomplete), but there is no explicit when-to-use guidance, no when-not, and no alternative named among the many sibling search/list tools. 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. With no output schema, the description's enumeration of return fields (address, phone, website, map URL, coordinates, rating, IATA code, timezone) is the key added behavioral context; it does not cover error/invalid-ID 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?

Two sentences, zero filler, with the purpose and the sequencing constraint (after places_search) front-loaded.

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 tool with full annotation coverage, this is nearly complete — the missing output schema is compensated by the explicit field list. Minor gaps remain around invalid/missing place_id handling, but nothing essential for correct invocation is absent.

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 (place_id, language) are already documented, including that place_id comes from places_search. The description adds no syntax or format detail 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?

States a specific verb and resource ('Get detailed information for a selected place') and enumerates the concrete fields returned, which lets an agent distinguish it from sibling places_search 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 routes the agent: 'Use this after places_search when the user chooses a place or needs the address, phone, website...'. It names the upstream alternative and the condition that selects this tool, leaving little to infer.

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 fully covered by structured data. The description adds nothing beyond that — no note on ranking, result ordering, truncation, or that results are candidates needing place_details before use. With annotations carrying the load, this is adequate but thin.

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 the second sentence is a purpose-built usage scope rather than filler. The long enumeration of place types is slightly padded but still earns its place by signalling coverage breadth.

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 is the only place an agent could learn about return shape, limit behavior, or how to chain into place_details/segment_associate_place, and it says none of that. Full schema coverage and rich annotations keep it usable, but the tool-to-tool workflow is left implicit.

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%: query, language, max_results (1–20, default 10), included_type, location_bias, and radius_meters are all documented in the schema with defaults and examples. The description adds no parameter-level detail, 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 gives a specific verb+resource ('Search for real-world places by text') and enumerates the kinds of places covered. It does not, however, distinguish itself from close siblings such as cities_search, search_hotels, search_attractions, or place_details, so an agent must still infer which search surface to use.

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 clear usage context: use it when the user needs to locate a place before adding or editing a trip segment. It gives no exclusions and never names an alternative (e.g. place_details for a known place, or the vertical search_hotels/search_attractions tools), so guidance is contextual but not routing-complete.

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 safe read profile (readOnly, idempotent, non-destructive, closed-world), so the description is not carrying the safety burden. It usefully adds the return shape — citation-ready IDs, titles, canonical URLs — which matters because no output schema exists. It does not mention result limits, pagination, or ranking 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?

Two sentences, no filler. The usage condition is front-loaded and the return detail follows, so an agent can decide and act after one read.

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 compensates by naming the returned fields, and a one-parameter read-only search needs little else. The remaining gap is operational: no indication of result counts, pagination, or whether some entity types are searched by default.

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

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

Schema coverage is 100%, so the single 'query' parameter is already documented. The description still adds real value by clarifying what the query is matched against (trips, segments, documents), implying one keyword query spans multiple entity types. Only the syntax itself is left unspecified.

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 (search) plus the resource scope: the user's own trips, itinerary segments, and travel documents by keyword. This implicitly separates it from catalog search siblings like places_search or search_hotels, which query external inventories rather than user data. It stops short of naming any sibling explicitly, but the scope 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?

Gives an explicit trigger condition: 'Use this when the user wants to search their trips, itinerary segments, or travel documents by keyword.' That is a clear when-to-use. It offers no when-not guidance or named alternative (e.g., mentions_search for @-mentions), so it falls short of the top mark.

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 material behavioral context beyond that: the access-tier requirement and the caveat that gate relevance is categorical rather than walking distance, which prevents misinterpretation of results. It stops short of describing matching or empty-result 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?

Two sentences, zero filler, and the access prerequisite and search scope are front-loaded before the return-value detail. 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 read-only search with full annotation coverage and an output schema, the description covers access requirements, search scope, returned field categories, and the key gate-relevance caveat. Minor omissions (matching semantics, behavior on zero results) keep it just short of 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 description coverage is 100%, so the baseline is 3. The description mirrors the schema parameters (IATA, terminal/gate) without adding syntax or interaction rules, and says nothing about max_results; the one nuance it adds concerns result interpretation rather than parameter usage.

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 Tineo's populated first-party airport-lounge catalog') and narrows scope by key ('by IATA and optional terminal/gate'). This is clearly distinguishable from sibling search tools like search_hotels, search_attractions, and places_search 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?

It gives a real eligibility prerequisite ('Requires Tineo Ultra access'), which is useful context, but says nothing about when to prefer this over alternatives or when it is inapplicable. Usage is implied rather than stated, so a 3 is appropriate.

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 open-world behavior, so the bar is lower. The description adds useful context beyond that: it names the external providers (TripAdvisor, Google Places) and describes the return payload (cards with ratings, descriptions, addresses, ticket/experience links). It omits rate limits or result caching, but that 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?

Three sentences, front-loaded with the purpose, then output shape, then usage trigger. No filler, though "attractions/sights/landmarks/things to do" is slightly repetitive in its enumeration.

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

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

There is no output schema, so the description correctly compensates by describing the returned cards. Purpose, output, and usage are all covered; only explicit sibling differentiation is missing, which keeps it from a 5.

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

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

Schema description coverage is 100%, so all three parameters (query, limit, location) are already documented in the schema. The description adds no syntax, format, or filtering semantics beyond that. Baseline 3 is appropriate.

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

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

States a specific verb (search) and resource (attractions, sights, landmarks, things to do) and names the data sources (TripAdvisor, Google Places). It is clearly distinguishable in spirit from search_tours/search_hotels, though it does not explicitly contrast itself against the closely related places_search 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?

"Use when the user asks about top sights, landmarks, or attractions in a city" gives a clear trigger condition. However, it names no alternative tool and gives no when-not guidance, so an agent facing places_search or search_tours must still infer the boundary.

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 safety is covered. The description adds real value beyond them: it enumerates the response contents (prices, durations, airlines, layovers, ranked route-search actions) and discloses child-age provider mapping and the infant lap-versus-seat policy that must be confirmed before booking.

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 purpose and output scope; the age-policy sentence is dense but each clause carries information relevant to correct invocation. No filler or 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?

With no output schema, the description usefully summarizes the return payload, and the 11-parameter surface is fully documented in the schema. Missing only selection guidance against siblings like flight_route_lookup or flight_booking_link.

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

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

Schema coverage is 100%, so the schema already documents all 11 parameters, including currency fallback ordering and the outbound_end_date calendar behavior. The description restates the child-age mapping that is already in the schema and adds no new parameter syntax or semantics, so the baseline of 3 applies.

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

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

States a specific verb (search), resource (flight itineraries with prices), and scope (two airports on a date) plus the underlying provider (Google Flights). An agent can distinguish it from route-oriented siblings like flight_route_lookup or status-oriented ones like flight_status_for_segment, though no sibling is named 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?

There is no when-to-use statement, no condition selecting this over flight_route_lookup/flight_booking_link, and no exclusions. The only guidance is an age-handling caveat ('confirm before booking'), which is a booking caveat rather than tool-selection 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, openWorld, and non-destructive. The description earns credit beyond them by disclosing that SearchAPI does not apply the text query or style preferences inside the radius, that provider coverage may be incomplete, that prices may change, and that only a unique identity match retains offer links.

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 the core purpose and then walks through the modes in compact sentences with no filler. It is dense but every sentence carries behavioral or routing information, so it stays appropriately sized.

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

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

For a 12-parameter, zero-required, multi-mode tool with no output schema, the description does the heavy lifting of explaining the modes, the radius caveats, and the check-in/check-out gating implied by the schema. Return-shape detail is absent, but it discloses offer-link behavior, which is the key observable outcome.

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

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

Schema coverage is 100%, so the schema already documents all 12 parameters and the baseline is 3. The description adds cross-parameter interaction semantics for hotel_place_id combined with radius_meters, but does not add format or constraint detail beyond what each property description already 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?

The description opens with a specific verb and resource ("Search for hotels and accommodations") and then distinguishes the tool's operating modes (ordinary text query vs dated radius search vs hotel_place_id lookup). It is clearly not a generic search, though it never names sibling tools like places_search or search_attractions to sharpen the boundary against them.

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 explains when each mode applies: plain text query for ordinary searches, bounding box plus distance for dated radius searches, and hotel_place_id with or without radius_meters for identity vs nearby lookups. This is genuine when-to-use guidance, but it stops short of naming explicit alternatives or exclusions within the tool family.

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, idempotent, open-world behavior, and the description usefully adds the provider fallback chain (GetYourGuide primary, Viator/Tiqets fallbacks) plus the return shape. Minor inconsistency: Tiqets is cited as a fallback but the provider enum omits it, though this is not an annotation contradiction.

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

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

Three sentences: purpose, return contents, and usage trigger, with the core action front-loaded. Efficient and free of padding, though the provider-sourcing clause makes the first sentence slightly dense.

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 search tool with a fully documented schema and no output schema, the description covers purpose, sourcing, return fields, and triggers adequately. It does not address result ordering or pagination behavior, but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, so all six parameters are already documented with format, defaults, and currency precedence rules. The description adds no parameter-level detail beyond what the schema provides, 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 (search) and resource (bookable tours/activities/excursions/experiences) and adds provider sourcing detail. It is clear in isolation, but never names the adjacent sibling search_attractions to draw the boundary, so 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?

The final sentence gives a concrete usage trigger ('when the user asks about things to do, tours, activities, excursions, or experiences in a city or destination'). It lacks any when-not guidance or explicit routing to alternatives like search_attractions or places_search, so it stops short of the top band.

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

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

Annotations already declare destructiveHint=true and non-idempotent, and the description adds real context by explaining what gets written and that it syncs address/city/country/coordinates. It stops short of stating whether an existing address is overwritten, which would fully justify the destructive flag.

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 parenthetical and em-dash construction front-loads the core action and then layers conditions. Every clause carries actionable information (prerequisite, role rules) with no filler.

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

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

For a mutation tool with no output schema, the description covers what it does, the prerequisite source of place_id, and the per-segment role behavior — everything needed to invoke 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?

Schema coverage is 100%, so the schema documents place_id, segment_id, and the role enum. The description goes beyond that by explaining where place_id comes from and when to pass origin/destination versus omitting role for single-location segments, adding conditional semantics the schema does not.

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 ('Attach a Google Place to an ALREADY-EXISTING segment') and clarifies the retroactive scope, distinguishing it from segment_create/segment_update. An agent can tell exactly what it does 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 gives the when: segments with a venue/name but no address, e.g. imported from a ticket confirmation. It also names the prerequisite data source (place_id from places_search/place_details) and routes role usage per segment type, leaving little 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety and idempotency profile is covered structurally. The description adds that results are bundled 'as booking_link_cards' and enumerates the link categories returned, which is mild extra context but says nothing about auth needs, rate limits, or empty-result 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?

One front-loaded sentence with no filler, stating the action, scope, and return shape up front. The long list of link categories is mildly redundant but efficiently conveys the breadth of results.

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

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

With no output schema, the description usefully names the return container ('booking_link_cards') and the kinds of links returned. Combined with annotations covering safety and a fully documented schema, the definition is nearly complete; only filtering behavior and empty/pagination behavior are unaddressed.

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% with only 2 parameters, so the schema already documents segment_id and the classifications filter. The description's enumeration of link types loosely hints at classification values but adds no format or filtering semantics beyond the schema; baseline 3 applies.

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

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

The description gives a specific verb (Return) and resource (booking/reservation/ticket/travel-document links) scoped to 'one trip segment', which is clear. It does not name sibling tools like trip_booking_links or flight_booking_link, so an agent must infer the segment-level vs trip-level vs mode-specific distinction. Clear purpose but no explicit 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 'for one trip segment' implies use when a segment ID is known, but there is no explicit when/when-not guidance or reference to alternatives such as trip_booking_links or mode-specific link tools. Usage is only implied, not 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 this is a non-read-only, non-destructive, non-idempotent write; the description adds real behavioral context beyond them by disclosing the date-within-parent-trip validation rule and the ordering dependency on segment_get_schema. It does not cover auth/permission requirements or what happens on validation failure, so it is 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?

Three short sentences, front-loaded with the action and then the required call order and constraint; each sentence carries distinct information with 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?

Covers the prerequisite, required identifiers, dynamic field source, and a key validation constraint for a create tool with no output schema. It leaves the return value (e.g., the created segment ID for chaining) unstated, which is a minor gap 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 coverage is 100%, so the baseline is 3; the description goes beyond it by explaining that `fields` is dynamic and must be derived from segment_get_schema for the chosen segment_type, which the schema only hints at. This meaningfully disambiguates the nested, type-dependent parameter.

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

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

States a specific verb and resource ('Create a new segment in a trip') and the description's workflow (schema lookup, then trip_id + segment_type + fields) makes clear it creates a single typed segment, distinguishing it from segment_update and batch_segment_create. An agent can identify the operation 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 a concrete prerequisite sequence ('FIRST call segment_get_schema') and a pre-condition with a remediation path ('dates must fall within parent trip dates; use trip_update first to extend the trip'), which is unusually clear context. It stops short of saying when to prefer batch_segment_create over this tool or any explicit 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?

Annotations already declare destructiveHint=true and idempotentHint=false. The description reinforces this with 'This action cannot be undone,' adding irreversibility emphasis beyond the flags. However, it says nothing about permissions, cascading effects on associated bookings/places, or rate limits, which would be valuable for a delete.

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

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

Two short sentences, zero waste, with the destructive warning front-loaded immediately after the purpose. Ideal size for a simple delete.

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 delete with annotations covering the safety profile and no output schema needed, the description is essentially complete. Only minor gaps remain around side effects on linked data.

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 a single parameter at 100% schema description coverage, the schema fully documents segment_id. The description adds no format, sourcing, or constraint detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Delete') and resource ('segment from a trip'), so an agent immediately knows the operation. It does not explicitly distinguish itself from siblings like segment_update or trip_delete, but the resource name 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?

There is no guidance on when to use this versus alternatives (e.g., segment_update for edits, batch_segment_create for bulk adds, trip_delete for whole-trip removal). Usage is only implied by the verb.

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, non-openWorld, so the safety burden is carried. The description adds value by disclosing the per-type return payloads and, notably, clarifying that bookingContext indicates change-preparedness and is explicitly NOT a save confirmation or write authority, which prevents a misuse.

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 a clear one-line purpose, followed by scoping detail and a useful bookingContext caveat. The per-segment-type field enumeration is somewhat long and partly redundant with the output schema, costing a point, but every sentence carries 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?

With a rich output schema covering return values and full annotations covering safety, the agent has nearly everything needed. The description rounds out intent and the bookingContext semantics; only the lack of routing guidance to sibling tools leaves a minor gap.

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

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

One parameter at 100% schema description coverage, so the schema alone documents segment_id. The description adds no syntax, format, or sourcing guidance beyond what the schema provides, making the baseline of 3 appropriate.

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

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

States a specific verb (Get full details) and resource (specific trip segment), and the enumeration per segment type makes the scope unambiguous. An agent can distinguish this from trip_details (trip-level) and segment_get_schema (schema-level) 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: call this to fetch details for a known segment. However, no guidance is given on when to prefer it over segment_get_schema or trip_details, nor any prerequisite (e.g., needing a valid segment_id from trips_hub/segment_create). Minimum viable but with a clear gap.

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 safe read-only, idempotent profile. The description adds useful behavioral context beyond them: it discloses a call-order requirement and states the return content ('required fields and their types'), which is especially valuable because no 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?

The description is front-loaded with the action and the critical call-order instruction. It is efficient overall, though the supported-type list duplicates the schema's enum-like descriptions rather than adding new information.

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

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

For a simple one-parameter read-only tool with rich annotations but no output schema, the description supplies the essential missing pieces: what the tool returns and when to call it. An agent has enough information to invoke 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?

Schema description coverage is 100%, and the single segment_type parameter is already fully documented in the input schema. The description repeats the supported-type list but adds no syntax, format, or validation semantics beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('Get') and resource ('schema for a segment type'), and distinguishes the tool from siblings by explaining it retrieves field metadata rather than creating or updating segments. The supported-type list makes the resource scope 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?

It gives clear usage context with 'CALL THIS FIRST before creating/updating segments,' which routes the agent appropriately relative to segment_create and segment_update. It does not explicitly name those sibling tools or state when not to use this tool, so it stops short of 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 already declare the write/destructive/idempotent profile, so the description is free to add the non-obvious parts: partial-update semantics that clarify what is left untouched, and the hard constraint that segment dates must fall within the parent trip's dates. It does not cover permissions or failure behavior, but it adds real behavioral value 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?

Three short sentences, front-loaded with the update action, then the partial-update rule, then the constraint. Every sentence carries distinct 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?

For a mutation tool with full schema coverage and no output schema, the description supplies the two things an agent most needs: how to populate the free-form fields object and the trip-date constraint. Nothing essential 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 meaningful semantics for the untyped nested `fields` object: only supply fields you intend to change, and fetch valid field names from segment_get_schema. That is genuine guidance 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?

The description opens with a specific verb+resource ("Update an existing segment") and the word "existing" implicitly separates it from the create/delete siblings. It is clear and actionable, but there is no explicit naming of sibling tools for writes, so it stops just 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?

It gives partial-update guidance ("Only provide the fields you want to change"), routes the agent to segment_get_schema for field names, and states a precondition with an alternative ("use trip_update first to extend the trip"). No explicit when-not-to-use is given, but the routing to two siblings by condition is strong.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the scope of what is read (user-scoped display and notification settings), but says nothing about auth requirements, defaults, or per-user vs global behavior, so it adds only moderate value.

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 with the verb and resource leading and the scope list trailing. Each clause earns its place by naming a distinct settings area, with no filler.

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

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

For a zero-parameter, read-only tool with complete annotations and an output schema, the description supplies the categories of returned settings and nothing essential is missing. It could be marginally stronger by noting whose settings (account-level vs trip-level), but the output schema covers return structure.

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 zero parameters and full schema description coverage, there is nothing for the description to disambiguate at the parameter level; the 0-param baseline of 4 applies. No syntax or argument nuance is needed for a no-argument read 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?

The description states a specific verb ("Reads") and resource ("the user's Tineo display and notification settings") and enumerates the covered categories: units, date/time formats, flight monitoring, and trip reminder emails. This is clear enough for an agent to distinguish it, though it doesn't explicitly name the read/write counterpart settings_update in text.

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?

There is no explicit when-to-use guidance or exclusion, but the read verb plus the sibling settings_update make the usage context strongly implied (read current settings before modifying them). It stops at implied usage rather than stating conditions or 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 disclose the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=false). The description adds genuine behavioral context by implying a partial merge rather than a full replace, but it never explains what the destructiveHint means here — whether omitted settings are preserved or reset, or whether the change needs confirmation.

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 action and followed immediately by the constraint, with no filler. It is tight but so brief that it borders on under-specification rather than being optimally informative.

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 minProperties:1 constraint is conveyed by the sparse-update sentence. For a mutation tool with a nested six-field object and destructiveHint=true, however, the description leaves the merge/destructive behavior and permission requirements 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, and it only goes as far as framing the six nested fields as "display" (formats, units) and "notification" (flight monitoring, trip reminders) settings. It adds useful grouping but no per-parameter meaning, enum semantics, or format strings beyond what the schema already lists.

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 (Changes) and resource (the user's Tineo display and notification settings), and the read/write pairing with the sibling settings_read is easy to infer. It stops short of naming that sibling or distinguishing itself from other update tools, but an agent can tell what it does 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?

"Only include settings the user asked to change" gives one useful operating rule for invoking it (send a sparse update, not a full snapshot). There is no explicit when-to-use/when-not guidance and no reference to settings_read as the alternative for inspection, so usage is only implied.

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 a non-read-only, destructive, open-world, non-idempotent write. The description adds meaningful context beyond that: an outbound email notification to Tineo support and the user-confirmation gate on the write. It stops short of covering duplication behavior, rate limits, or what happens after submission.

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, zero filler, and the action plus its precondition are front-loaded before the trigger conditions. Every clause earns its place.

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

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

For a mutation tool with full schema coverage and no output schema, the description covers purpose, gating, and trigger conditions adequately. The main omission is any indication of what the caller receives back (e.g., the created ticket reference) or what to do if creation fails.

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% across all 8 parameters, including inline docs for confirmed, source, failure_context, and attachments, so the schema carries the parameter burden. The description reinforces the confirmed precondition but adds no parameter semantics (formats, id relationships, attachment limits) beyond 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?

Specific verb+resource (create a support ticket) plus the secondary effect of emailing Tineo support. It is unmistakable against the travel-oriented siblings, none of which handle support escalation.

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 conditions are given (assistant cannot complete, tool fails, capability unsupported) and a hard precondition is stated (only after the user explicitly asks or confirms). That is as close to when/when-not guidance as this tool needs.

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 readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds useful scope context (a signed-in check, not a data listing) beyond what the annotations say, though it omits any failure/auth-expired behavior an agent might want.

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 no filler. The purpose is front-loaded and the scoping caveat follows immediately.

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 elaboration, and the annotations carry the safety profile. For a parameterless connectivity check, nothing an agent needs to invoke it correctly is absent.

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; the baseline for a parameterless tool applies. No parameter semantics are needed or missing.

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: verifies Tineo connectivity and the signed-in user. It also draws a boundary against a likely confusion point in this sibling set by noting it does not list trips, so an agent can distinguish it from trips_list without opening a schema.

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

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

The condition for use (verify the connection/account is live before doing other work) is clear from the phrasing, and the closing clause steers agents away from treating it as a trip-listing call. No explicit alternative tool is named, which keeps it 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 declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: it is only a search handoff, it preserves the requested date, and it provides no live fares, availability, or tickets. That negative disclosure is genuinely useful for setting agent expectations.

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

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

Three tight sentences with the core purpose front-loaded and the key limitation last. Only the middle sentence about selecting dates on Omio is mildly redundant, but 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 read-only link generator with no output schema, the description covers purpose, the handoff workflow, and the crucial absence of live fares/tickets. Combined with fully documented params and safety annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so all eight parameters (including trip_id/currency defaulting logic) are already fully documented in the schema. The description only alludes to dates and passenger details, adding nothing beyond the structured fields, 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 verb and resource ('Return an Omio train-search handoff') and even narrows the supported routes (Madrid-Barcelona, Tokyo-Kyoto). This clearly separates it from flight_booking_link and ground_transfer_booking_links by mode, though it never names those siblings 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?

Implies the use case (a handoff where the user finishes booking on Omio) and rules out expecting live data, but gives no explicit when-to-use vs alternatives routing against flight_booking_link or segment_booking_links. Usage is inferable 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the mutation profile is covered. The description adds non-obvious cascade behavior beyond that: linked files move with the document, while a file also attached elsewhere is left in place and reported, plus the owned-trip restriction. It stops short of describing error/permission failure behavior, but adds real value over 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?

Action and scope are front-loaded, followed by input sourcing, the unassign rule, ownership constraint, side effects, and return shape. Every sentence carries information; only the restated omit-trip_id rule slightly overlaps the schema 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?

For a two-parameter mutation with no output schema, the definition covers target sourcing, the unassign path, ownership restriction, ambiguous-match handling, the file cascade side effect, and even the response contents (document, previous/new trip, count of re-pointed files). An agent has everything needed to call it safely.

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, and both parameters are already documented in the schema. The description adds value by naming the source endpoints for each id (documents listing, trips_list) and restating the omit/null-to-library semantic as an operational instruction rather than a field note.

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 (move/assign) plus resource (travel document) and the two possible destinations (another owned trip or the general library). It is clearly distinguishable from siblings like audit_travel_documents or trip_update 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 where to obtain inputs (document_id from a documents listing, trip_id from trips_list), when to omit trip_id (library), the ownership precondition, and to confirm when multiple documents could match. This is when/when-not/alternative 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 flag destructiveHint=true, openWorldHint=true, and non-idempotency, so the safety profile is covered. The description adds genuinely new behavior: that passing email actually creates and sends the trip invitation to an external party, plus the dependency on known_participants. It does not address duplicate travelers or error/rollback 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, no filler, and the ordering constraint is front-loaded before the branching detail. It is slightly compressed but every clause carries information an agent needs at call time.

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 mutating tool with annotations present, no output schema, and fully documented parameters, the description covers the prerequisite, both decision branches, and the external send side effect. It omits what happens on success/failure or when the traveler already exists, which are minor gaps given the structured data available.

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?