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 declare readOnly/idempotent/openWorld, so the safety bar is covered, yet the description adds substantial behavior beyond them: location and dates are derived from the trip with model override, out-of-area listings are sorted last, and the unavailable-status path has a no-retry policy with three concrete fallbacks. This is genuine operational context, not restatement.

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

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

Purpose and the trip-derivation rule are front-loaded, and every sentence carries an actionable rule rather than filler. It runs long as a single dense paragraph, so the fallback and no-search-substitution rules are slightly less scannable than they could be, 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 16-parameter, no-output-schema tool, the description is unusually complete: it explains card fields (distance_km, in_requested_area), ordering, the empty-area case, the filter limitation, and the structuredContent.status/fallback_search_url contract. An agent has what it needs to call the tool and to handle its edge outcomes without 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?

With 16 parameters and 50% schema coverage, the description compensates well by clarifying the most error-prone inputs: location must be a city/area rather than a country, and the amenities enum is the only filter (no keyword/free-text). It adds little for numerics like adults/children/min_beds/price/room_type, which remain schema-only.

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

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

States a specific verb (Search) and resource (Airbnb listings) scoped to 'an existing Tineo trip,' which cleanly separates it from the sibling assistant_airbnb_search_user that presumably searches by user profile rather than trip. An agent can identify the tool and its scope 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 explicit when-to-use and when-not guidance: location must be a city, not a country (ask the user), do not re-search the same place with reworded strings when nothing is in the area, and if structuredContent.status is 'unavailable' do not retry but instead use fallback_search_url, offer a hotel search (search_hotels sibling), or open a support ticket. Alternatives and exclusions are named outright.

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/non-destructive, yet the description adds substantial behavioral context beyond them: the returned card fields, area-membership ordering via distance_km/in_requested_area, the amenity-only filtering constraint (no keyword filter), and the unavailable-status handling with fallback_search_url and the explicit 'do NOT retry' rule.

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

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

The description is front-loaded with purpose and scope, and each sentence contributes actionable guidance rather than filler. It is somewhat dense and run-on, but the length is justified by the tool's complexity (15 params, no output schema, sibling disambiguation).

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 explains the return value (slim list of cards) and even the structuredContent.status/fallback_search_url failure path. Combined with the location and amenity constraints, it is nearly complete for invocation; the gap is the unaddressed remaining query parameters.

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 47%, below the 50% threshold, so the description carries a compensation burden. It adds real meaning for location ('must be a city or area, not a whole country') and amenities (enum-only, no free-text), but says nothing about guests, price, room_type, beds/bathrooms, or max_results, leaving half the parameters undocumented in both places.

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+resource ('Search Airbnb listings by location and dates') and explicitly carves out scope with 'Use when the user is not asking about a specific trip in Tineo,' clearly distinguishing it from the sibling assistant_airbnb_search_trip. It also characterizes the output shape, so the agent knows exactly what this tool returns.

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 explicit when/when-not guidance (trip-specific vs general search), a location pre-condition to resolve with the user, an anti-pattern rule ('do NOT re-search the same place with a reworded location string'), and concrete alternatives for the unavailable case (fallback_search_url, hotel search, support ticket). This is the strongest form of 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 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 write/non-idempotent/non-destructive, but the description adds substantial behavior: per-item partial success/failure with index-based failure reporting, the 50-segment cap, date-range auto-extension with a warning, place-linking side effects (map pin, coordinates, and auto-filled name/address/phone/website), and the 'time not set' semantics. This is far richer than the annotations alone.

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

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

Long, but front-loaded with the core action and then ordered by importance: batching, partial-failure handling, limits, date rules, place linking, time rules. Nearly every sentence carries actionable constraint, though the density is dense enough that a tighter grouping would help.

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 batch write tool with no output schema, the description supplies the missing return behavior (failed items returned by index with reasons) and covers prerequisites, limits, and edge-case date handling. 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 the baseline is 3, but the description earns extra by cross-referencing segment_get_schema for field naming, defining the Activity activityType values, and specifying startDateTime formats (YYYY-MM-DD vs. clock time) plus the placeId contract that the generic 'fields' object does not document.

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 multiple segments in a trip in one call'), immediately distinguishing the batch operation from the single-item segment_create sibling. An agent knows exactly what this 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?

Explicit when-to-use and when-to-escalate: split itineraries larger than 50 segments, resend only failed items, call trip_update for dates more than 1 day outside the trip, and call places_search before creating Activity/Lodging/EventTicket/Parking at a real place. Alternatives and preconditions are named, not inferred.

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, open-world, idempotent, non-destructive behavior. The description adds real value beyond them by disclosing that the returned content is affiliate search handoff cards rather than live data or confirmed bookings — an important expectation-setting trait not captured by 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 zero padding; the core purpose is front-loaded and the 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?

With no output schema, the description usefully characterizes what the tool returns (provider search handoff cards) so the agent knows not to treat results as live booking data. Combined with the rich parameter schema, this is nearly complete; only a clearer routing recommendation versus alternatives 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 (including locale, trip_id currency defaults, and date formats) are fully documented in the schema. The description restates the pickup location and dates but adds no syntax or semantics beyond that, 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 (Return) and resource (DiscoverCars and Expedia affiliate car-rental search cards) with scope (pickup city/airport + dates). It distinguishes itself clearly from the sibling booking-link tools (flight_booking_link, train_booking_link, ground_transfer_booking_links).

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 second sentence gives strong context on what this tool is not ('provider search handoffs only, not live availability, prices, vehicles, or confirmed bookings'), which steers the agent away from promising real prices. It does not, however, explicitly name an alternative to use when the user needs actual availability, so it falls short of a full when/when-not/alternative guide.

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

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

Adds substantial context beyond the annotations: appends to the end, 100-task cap, flat list with no subtasks, and the concrete consequence of non-idempotency ('calling this twice adds the tasks twice'), which explains what idempotentHint=false actually means. Also flags the 'never show IDs to users' presentation rule.

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

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

Front-loaded with the core action, then ordered supporting facts (ID source, item shape, limits, idempotency, alternative, display rule). Dense with zero filler sentences.

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

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

For a 2-parameter append tool with no output schema, it covers constraints, idempotency, prerequisites, and alternatives thoroughly. It omits any hint about the response shape or ordering feedback, 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?

Schema description coverage is 100%, so the baseline is 3. The description restates that each item has text plus an optional category as 'the section heading it appears under', but adds little syntax or format detail beyond what the schema already documents.

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

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

States a specific verb+resource+scope: 'Add one or more tasks to the end of an existing trip checklist.' The appended-at-end behavior and 'existing checklist' qualifier distinguish it cleanly from checklist_item_update, checklist_items_reorder, checklist_items_remove, and 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?

Gives a prerequisite (get checklist_id from trip_checklists) and routes to the right alternative for creating a checklist ('use segment_create (type Note, isChecklist true)'). It does not spell out an explicit when-not-to-use case, but the sibling routing is clear and actionable.

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 and idempotentHint=true, but the description adds meaningful context: the removal is 'permanent', it requires user confirmation, and IDs must never be surfaced. These behavioral constraints go beyond the structured hints.

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

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

Four short, front-loaded sentences with no filler; the destructive action and confirmation rule lead. The 'never show IDs' sentence is slightly tangential but still relevant to invocation behavior.

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

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

With annotations covering the safety profile, full schema coverage, and no output schema, the description supplies everything needed: permanence, confirmation requirement, ID sourcing, and the sibling alternative. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, and the schema itself documents both checklist_id and item_ids as coming from trip_checklists, so the description largely restates that provenance. The 'never show IDs to users' note adds a presentation constraint but no new parameter mechanics. 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+resource (remove tasks from a trip checklist) with explicit scope ('one or more tasks'). It also distinguishes itself from the whole-checklist deletion path by naming segment_delete, so an agent can route 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 clear usage context: source the IDs from trip_checklists, confirm with the user first, and use segment_delete for a full checklist. Lacks explicit exclusion against adjacent item-level tools (checklist_item_update, checklist_items_reorder), but the intent 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 destructive/idempotent/openWorld, so the safety profile is covered. The description adds real behavior beyond them: tasks are grouped under section headings in first-appearance order, and the order array must contain every task ID exactly once. It doesn't clarify what happens to omitted IDs, which is the one gap given destructiveHint=true.

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

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

Four tight sentences, purpose front-loaded, then prerequisite, then format constraint and grouping behavior. The trailing UI note ('Never show IDs to users') is slightly tangential but brief and harmless.

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 and full param coverage, the description supplies the prerequisite chain, the required input shape, and the grouping semantics — enough to call it correctly. Only the treatment of omitted IDs is left unstated.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning about the order parameter — it must list every task ID exactly once — reinforcing the schema's uniqueItems/minItems constraints and explaining the section-grouping consequence of the ordering.

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 (put in a new order) and resource (a trip checklist's tasks), which cleanly distinguishes it from the sibling mutators checklist_items_add, checklist_items_remove, and checklist_item_update. 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?

It gives a clear prerequisite workflow — get checklist_id and item IDs from trip_checklists first — and specifies the required shape of the call (every task ID exactly once). It does not name a when-not-to-use case or contrast against checklist_item_update, so it stops short of 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 cover the safety profile (destructive, non-read-only, idempotent), but the description adds genuinely useful behavior the annotations cannot convey: shared-trip completion semantics (done only once every traveler ticks it), the fact that checked=false unticks, and that an empty category removes the task from its section. It does not mention error behavior or what happens with concurrent edits, which keeps 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?

Front-loaded with the verb and resource, then proceeds through mutable fields, ID sourcing, and per-field semantics in a logical order with no filler. The closing instruction 'Never show IDs to users' is off-topic for tool invocation (a presentation rule) and slightly dilutes an otherwise tight paragraph.

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 5-parameter mutation tool with no output schema, the description covers the mutation surface, the partial-update contract, ID provenance, and the highest-risk behavioral nuance (shared-trip completion). It lacks only edge-case handling (invalid item_id, text trimming) to be 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the field docs: it explains the cross-user effect of checked on a shared trip and clarifies that an empty category detaches the item from its section rather than merely blanking a label. The 'send only what changes' framing also clarifies that all three optional fields are independently omittable.

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 (change) and a precisely scoped resource (one task on a trip checklist), then enumerates the three mutable aspects: text, category, done-state. That scope cleanly separates it from checklist_items_add, checklist_items_remove, checklist_items_reorder, and library_list_item_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?

Gives a real prerequisite ('Get checklist_id and item_id from trip_checklists') and a usage rule ('Send only what changes'), which tells the agent this is a partial update rather than a full replace. It stops short of explicit exclusions or naming which sibling to use for adjacent operations (reorder, delete).

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. On top of that the description discloses matching semantics (whole names, prefixes, word starts, exact matches ranked first) and the important empty-result caveat, plus the explicit statement that search does not add or select a city.

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

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

Purpose and workflow cue come first, followed by matching behavior and the empty-result escape hatch. Six short sentences, all carrying information, though the matching-mode and return-value sentences 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 supplies the return shape (stored city IDs and location details) and covers the non-side-effecting nature plus the fallback path when nothing matches. An agent has everything needed to call it and interpret an empty 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 coverage is 100%, so query, limit and country are already fully documented including ranges, defaults and the ISO-code example. The description only restates the country filter, adding no syntax or behavior beyond the schema, which is the correct 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 and resource ('Search the saved city catalog by city name or alias') plus the workflow context ('before adding a city to a trip'), which cleanly separates it from trip_city_add and the other search_* siblings.

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

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

Explicitly gives when to use it (before adding a city), how to narrow (pass country), and redirects to the alternative with the condition that selects it: an empty result does not mean the place is unavailable because trip_city_add accepts city_name and country for uncatalogued towns and islands.

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 a non-destructive, non-idempotent write, so the bar is lower, and the description still adds substantive behavior: copies retain item text and sections, every item starts unchecked, copies are limited to 10 and stay on the same trip. What it omits is the response shape and whether the source must be non-empty.

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 with no filler: action and scope first, then behavior of the copies, then required inputs. Every clause carries 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?

There is no output schema, yet the description never indicates what is returned (e.g., new checklist IDs or titles), which is the one thing an agent needs to chain follow-up calls. Everything else for correct invocation is present given the full schema coverage.

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

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

Schema coverage is 100% and both parameters are documented there, including the 1-10 range and 200-character limit. The description mainly restates the schema (segment ID from trip_details, one title per copy, max 10) rather than adding new semantics, 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 (duplicate) and resource (checklist), plus the outcome: one or more new checklists on the same trip. This is clearly distinct from creation siblings like segment_create or batch_segment_create, though it never names an alternative explicitly, which keeps it at a 4 rather than 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 prerequisite that source_note_id comes from trip_details, which is real usage context, but offers no when-to-use vs when-not guidance and never points to a sibling tool for adjacent operations. 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?

Goes well beyond the annotations by naming the external data source (Apple Maps traffic prediction), which explains the openWorldHint, by spelling out the side effect of apply=true (calendar and iCal feed reflect real ride length instead of a flat hour), and by guaranteeing that existing drop-off times are never overwritten and a failed lookup is a no-op. This effectively confirms idempotentHint and destructiveHint=false with concrete semantics.

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

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

Front-loads what the tool does, then the apply semantics, then the safety guarantees; every sentence carries information. It is a long single sentence plus two shorter ones, slightly wordy but not 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 still tells the agent that the result is a reported estimate rather than a value to be treated as fact, and it covers the mutation semantics and failure behavior. It could say more about the estimate's return shape or precision, but for a 2-param tool this is close to complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: not just that apply saves the estimate, but the downstream consequence (calendar/iCal show true ride length vs. a flat hour) and the protective rule that a pre-existing or user-set drop-off time is left alone. segment_id semantics remain solely in 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 (estimate) plus the exact resource (drive time of a Transfer/Transport segment) and the inputs it derives from (pickup, drop-off, pickup time). An agent can distinguish it from siblings like segment_update or get_routes 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?

Clearly explains the two operating modes: apply=false reports only, apply=true persists the estimate. It also states the guardrails for when not to expect a change (existing drop-off, failed lookup). It doesn't explicitly name an alternative tool for recomputing or clearing an estimate, so it stops short of 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/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?

Adds real behavioral context the annotations cannot express: results are cached for a few minutes, so repeated calls for the same flight return the same payload, implying 'call once per flight per answer.' It also notes the response text carries the provider's last-update time, which sets freshness expectations beyond readOnly/idempotent hints.

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, front-loaded with purpose then usage then the caching caveat, which is exactly where an agent needs it before deciding to re-call. 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-value description is unnecessary; annotations cover safety and open-world behavior; the description covers caching and data-freshness semantics. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and both parameters are documented there, including the 'id' alias for segment_id, so the schema does the heavy lifting. The description adds no extra meaning about the identifier's origin or the alias behavior, 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 precise verb+resource+scope: 'current flight status for an existing flight segment in a user's trip.' That scope phrase implicitly separates it from siblings like flight_route_lookup (schedules/routes) and get_flight_airport_conditions (airport-level, not a saved segment).

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

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

Gives concrete triggering situations ('delayed, canceled, on time, boarding, or gate/terminal updates'), which is clearer than generic context. It stops short of naming an alternative for adjacent cases (e.g. airport conditions or route lookups), 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?

Goes well beyond annotations by explaining what the address is for (email ingestion, booking extraction), its non-destructive/no-op behavior on existing addresses ('Never replaces or changes an existing address: if one already exists it is returned unchanged'), and hands off to the read sibling. This clarifies why idempotentHint is true in behavioral terms.

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 front-loaded. Each sentence carries distinct value (what it is, what it enables, the no-replace guarantee, the alternative). Slightly longer than strictly needed but no wasted content.

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-param, no-output-schema tool, the description covers the required intent gate, the side-effect-free behavior on existing state, and the routing to the read sibling. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the single 'confirmed' parameter is already documented. The description reinforces the explicit-user-intent condition but adds no syntax or value 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 ('Create the authenticated user's personal Tineo forwarding address') and distinguishes itself from the sibling forwarding_address_get by naming it as the read-only alternative. 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?

Explicitly states the trigger condition ('when they explicitly ask for one') and names the alternative tool ('Use forwarding_address_get to read addresses without creating one'). Both when-to-use and how-to-avoid are covered.

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 profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description's 'without changing anything' is consistent with them. It goes beyond the annotations by explaining the semantics of the universal trips@tineo.ai address and the fact that a personal address can receive mail from assistants and travel providers. It stops short of return shape/ordering specifics, so 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-loaded with the core action and the non-mutating constraint, with the sibling routing last. Four sentences, all carrying information; the middle sentences on the trips@tineo.ai address and assistant/travel-provider delivery are dense but earn their place for a tool whose whole value is explaining address semantics.

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 describing what comes back: the personal address when one exists, other active personal addresses, and the universal address — including the empty case. For a zero-param read tool this is everything an agent needs to call it and interpret the answer.

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 per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it does not clutter itself with irrelevant parameter talk.

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

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

States a specific verb ('Read') and resource ('the authenticated user's Tineo email forwarding addresses') and immediately scopes it as non-mutating. It also enumerates the three kinds of addresses returned, so the agent knows exactly what data this tool surfaces versus the many sibling tools in the catalog.

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

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

Explicitly names the alternative ('use forwarding_address_create') and the condition that selects it ('If the user has no personal address and wants one... after they ask for it'). This both routes the agent to the sibling and adds a consent gate, which is more than most definitions provide.

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 it is a write (readOnlyHint=false), open-world, idempotent, non-destructive operation. The description adds substantial beyond-annotations context: the no-op-if-exists semantics, the 3-segment precondition, the data transmitted to the third-party AI provider, and a privacy statement (names and sensitive health data never sent). This is rich behavioral disclosure.

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, then the critical no-op/replace distinction, then preconditions and parameters. Slightly long and dense, and the privacy sentence is a touch verbose, but every sentence carries real information. Just short of a 5 due to mild density.

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 the action, its idempotent/no-op behavior, the precondition, the alternative, parameter semantics, and a privacy boundary for third-party data sharing. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the nested people object is thoroughly documented in-schema, so the schema does the heavy lifting. The description adds a little value ('max 6', 'one list per person', 'the person's age band and notes but never their name'), but mostly restates what the schema already states, 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?

Specific verb+resource ('Create a weather- and activity-aware packing checklist'), plus it names the resulting artifact ('pinned checklist note') and explicitly distinguishes itself from the sibling packing_list_regenerate. An agent can tell it apart from other checklist tools 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 explicit when-to-use behavior ('Never changes an existing list: if one already exists it is returned unchanged'), names the alternative ('use packing_list_regenerate to replace it'), and states a precondition ('Requires the trip to have at least 3 substantive segments'). Routing and prerequisites are fully specified.

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, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds that parsing produces 'proposed' segments and saves nothing, which is mildly redundant with the read-only hint but clarifies the preview nature. It does not add deeper behavioral context like rate limits, error behavior, or output 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?

Two tight sentences with no waste. The purpose and non-persistence are front-loaded, followed by a clear usage instruction. Every sentence earns its place.

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

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

The description covers the tool's purpose and when to use it, and the input schema is fully described. With no output schema, it would be slightly more complete if it described the shape or fields of the returned segment previews, but the core need is met.

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 input schema already documents every parameter thoroughly, including the 90-second parse limit. The description contributes no parameter-level meaning 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?

The description states a specific verb ('Parse') and resource ('pasted travel confirmation text') and clarifies the output ('proposed itinerary segments') and the key constraint ('without saving anything'). It implicitly distinguishes itself from segment_create by being a non-persistent preview, so an agent can tell it apart from creation tools 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?

It gives a clear usage trigger: 'Use this before creating segments from copied email, PDF, or booking text.' This tells the agent exactly when to reach for it. However, it does not name a specific alternative (e.g., segment_create) or say when not to use it, leaving minor inference to the agent.

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 destructive=true and idempotent=true, but the description adds the crucial human-in-the-loop constraint that confirmed=true is required and that unconfirmed calls change nothing, plus the version-conflict recovery path. This is behavior an agent cannot derive from the annotations alone.

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

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

Front-loads the destructive action, then the confirmation requirement, then the sourcing and error-handling instructions. Every clause is load-bearing 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 destructive mutation with no output schema, the description covers scope, prerequisites, confirmation workflow, parameter sourcing, and conflict recovery — everything an agent needs to invoke it safely and correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by tying listId and expectedVersion to their source (latest library_list_get) and explaining confirmed as a user-confirmation gate. That workflow meaning exceeds the field-level schema text.

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

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

States a specific verb and resource: 'Permanently delete every completed item from an owned Library List.' It also draws an explicit scope boundary against the many sibling deletion tools by noting 'Library Lists only, not trip checklists.' An agent can distinguish it from library_list_delete, library_list_item_delete, and checklist_items_remove immediately.

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 full when-to-use protocol: confirm the removal count with the user, call with confirmed=true only after confirmation, and source listId/expectedVersion from the latest library_list_get. It even prescribes recovery behavior on library_version_mismatch (re-read and reconsider, never retry blindly), leaving nothing 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 flag this as destructive and non-idempotent-safe, but the description adds genuine behavioral context beyond them: the mandatory user-confirmation gate, the fact that without confirmed=true nothing changes and the pending change is returned for review, and the version-conflict recovery procedure.

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?

Five tightly packed sentences, front-loaded with the destructive scope and confirmation requirement, then the sourcing and error-handling rules. 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?

For a destructive, confirmation-gated mutation with no output schema, the description covers everything an agent needs: what is destroyed, the confirmation requirement, how to obtain required parameters, and how to handle version mismatches. 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%, so the schema already documents listId, confirmed, and expectedVersion thoroughly — including the confirmation semantics. The description's guidance to source values 'from the latest library_list_get' largely echoes the schema, so it stays at the baseline for a fully-covered 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 (delete) and resource (Library List) with explicit scope: the entire list and all of its items. It also draws a clear boundary — 'Library Lists only, not trip checklists' — which separates it from the checklist siblings, and the 'entire...all of its items' framing distinguishes it from library_list_item_delete.

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 workflow: name the list to the user first, only pass confirmed=true after they confirm, and source listId/expectedVersion from the latest library_list_get. It also prescribes the recovery path on library_version_mismatch (re-read and reconsider, never retry blindly), 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 cover readOnly/idempotent/non-destructive/non-open-world, so the bar is lower, but the description adds real behavior: the payload includes every stable item UUID and its version, and it flags the edit-preservation concern. It does not describe pagination, though a single-list read likely has none.

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 read scope, then the workflow rule, then the guardrail. Nothing is filler and the ordering matches how an agent would act.

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 says what comes back (item UUIDs and versions) and covers safety via annotations. The remaining gap is parameter documentation for itemType and the source of a valid listId.

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

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

Schema coverage is 0% for two parameters, so the description must compensate. It gives genuine semantics for listId (it is not a trip segment ID and must be a known/real ID, not guessed), but says nothing about itemType (enum with default 'list') or where a valid listId is obtained.

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 ('Read one owned Tineo Library List') with scoping word 'one' and 'owned' that separates it from the sibling library_lists_search. An agent can pick it 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?

'Read before editing' gives an explicit when-to-use rule that ties it to the library_list_edit sibling, and 'Never use trip segment IDs or guess list/item IDs' gives a clear when-not caveat. It stops short of naming the alternate lookup tool (library_lists_search) for obtaining a listId.

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 idempotentHint=true, but the description explains the mechanism behind it: a caller-generated itemId reused on retries so a retried call never duplicates. It also discloses the version-mismatch failure mode and the required recovery behavior, which annotations cannot convey.

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

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

Four compact sentences, all front-loaded on the action, and each one carries distinct, non-redundant information (purpose, idempotency, sourcing, error handling, scope). 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, but the description covers the full contract an agent needs: which ID/version to supply, how to retry safely, how to react to version mismatch, and what this tool explicitly does not touch. Nothing essential 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 baseline is 3, but the description adds cross-tool provenance for listId and expectedVersion ('from the latest library_list_get') and the 'latest' qualifier on expectedVersion, which clarifies freshness expectations beyond the schema text.

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 plus scope: 'Add one item to an owned Library List.' The singular 'one item' plus the explicit 'Library Lists only, not trip checklists' distinguishes it from the plural sibling library_list_items_add and from checklist_items_add.

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 preconditions ('Use the listId and expectedVersion from the latest library_list_get'), an error-recovery path ('On library_version_mismatch, read the list again and reconsider the change; never retry blindly'), and a scope exclusion ('not trip checklists'). This is when/when-not/alternative guidance at a high level of specificity.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes further: it emphasizes permanence, explains the confirmed=true gate (without it the tool changes nothing), and prescribes recovery on library_version_mismatch ('read the list again... never retry blindly'). This is exactly the behavioral context annotations cannot carry.

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?

Five short sentences, action front-loaded, followed by confirmation workflow, value sourcing, and error recovery. Every sentence carries distinct operational value 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 destructive, version-guarded mutation with no output schema, the description covers the confirmation gate, parameter provenance, and version-conflict handling. Nothing an agent needs to invoke it safely 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 sourcing semantics beyond the schema by telling the agent to pull listId and expectedVersion 'from the latest library_list_get.' It does not add format or edge-case meaning for itemId, so it sits just above baseline.

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

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

States a specific verb and resource ('Permanently delete one item from an owned Library List') and explicitly bounds scope with 'Library Lists only, not trip checklists,' which separates it from the checklist_items_remove sibling. An agent can identify the operation and its object 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 explicit sequencing ('Show the user the exact item first; call with confirmed=true only after they confirm'), names the source tools for the required values (library_list_get), and states the exclusion ('not trip checklists'). When-to-use, prerequisites, and the alternative boundary are all present.

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 idempotentHint=true and destructiveHint=false, but the description goes further by explaining the mechanism that makes retries safe (caller-generated itemIds reused on retry) and the exact error-recovery path for version conflicts. It also discloses the 100-item ceiling, none of which is in the structured fields.

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

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

The what, the idempotency contract, the limits, and the failure-handling rule are packed into five tight sentences with the primary action front-loaded and 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, it covers the essentials an agent needs: batch limits, version preconditioning, retry safety, and error recovery. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents itemId reuse semantics, listId provenance, and expectedVersion opaque format. The description's guidance on where to obtain listId/expectedVersion and the 'in order' constraint largely restates what the schema already says, so it earns baseline rather than added value.

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 (add), resource (several items), and scope (an owned Library List, in one call, in order) that an agent can act on directly. It also excludes trip checklists, which cleanly separates it from the many checklist_* and library_list_item_* siblings.

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

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

Explicitly prescribes the workflow: fetch listId and expectedVersion from library_list_get, split lists over 100 items, and handle library_version_mismatch by re-reading rather than blindly retrying. It also names the boundary case (Library Lists, not trip checklists), leaving nothing 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 it non-read-only, idempotent, and destructive; the description adds substantial context beyond them — a required-confirmation gate, version preconditions, and conflict-recovery policy that no annotation covers. It stops short of explaining what makes the operation destructive (nothing is deleted since every item must appear exactly once), so the destructiveHint is left unaddressed.

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 action, then presents the constraint, confirmation gate, parameter sourcing, and error policy in dense, waste-free sentences. Every sentence carries a distinct operational instruction.

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

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

No output schema exists, and the description compensates by covering the confirmation flow, versioning preconditions, conflict handling, and scope limits — everything an agent needs to invoke this mutation correctly without blindly retrying.

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 restates the orderedItemIds constraint ('every current item ID exactly once, in the new order') and points to library_list_get for listId/expectedVersion, but adds little meaning beyond what the schema already documents per-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 (reorder) and resource (items of an owned Library List), and explicitly distinguishes itself from the closest sibling with 'Library Lists only, not trip checklists' — separating it from checklist_items_reorder. An agent can identify the correct tool 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 preconditions (use listId/expectedVersion from the latest library_list_get), a gated confirmation flow ('show the proposed order first; call with confirmed=true only after they confirm'), and recovery guidance for library_version_mismatch ('read the list again and reconsider; never retry blindly'). It also names the excluded alternative scope.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true, so the safety profile is partially covered. The description adds valuable behavior beyond that: it is a partial update ('Changes only the fields named in updateFields') and it uses optimistic concurrency via expectedVersion with a mismatch-retry policy. It stops short of describing what 'destructive' means here (e.g. field clearing), which the schema's updateFields description covers instead.

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

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

Front-loaded with the core action, then scoping, then the concurrency/error contract. Each sentence earns its place: field list, partial-update rule, parameter sourcing, mismatch recovery, and scope exclusion.

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 supplies what the annotations cannot: partial-update semantics, the concurrency token contract, and a safe error-recovery rule. Combined with the fully documented schema, 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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that only keys named in updateFields are applied and by specifying that listId/expectedVersion come from the latest library_list_get, reinforcing the optimistic-concurrency contract.

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 ('Change one existing item in an owned Library List'), enumerates the mutable fields, and gives a concrete example ('to check it off'). It also explicitly excludes the adjacent sibling by scope ('Library Lists only, not trip checklists'), so an agent can distinguish it from checklist_item_update.

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 workflow guidance: 'Use the listId and expectedVersion from the latest library_list_get' and a recovery path for 'library_version_mismatch' ('read the list again and reconsider the change; never retry blindly'). It also names the boundary condition against trip checklists. When-to-use and error handling are both present.

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, so the safety profile is covered. The description adds useful behavioral context: it returns candidate IDs rather than full records, and tells the agent to prompt the user when there are multiple matches. It does not cover pagination or the limit/offset behavior, but it exceeds the annotation baseline.

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 compact sentences, front-loaded with the core search action. The last sentence about not inventing journal/place/file edits is slightly tangential for a search tool but serves as a useful guardrail against hallucinated scope.

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 purpose, disambiguation, and scope boundaries, which is adequate for a read-only search with annotations. However, with no output schema and only 25% parameter coverage, it should explain return shape or parameter meaning more fully; the description stops at 'return candidate IDs' without saying what an ID is or how to use it.

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 25%; only the 'limit' parameter carries a description. The description does not explain the query, offset, or itemType semantics (e.g., that itemType is fixed to 'list'). Baseline 3 applies because the schema partially documents the key parameter, but the description misses the chance to compensate for the low coverage.

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

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

States a specific verb (Find) and resource (signed-in user's Tineo Library Lists) scoped by title or description. It also distinguishes from siblings by noting these are 'freestanding Library Lists, separate from trip packing/checklists,' which rules out generate_packing_list and similar tools.

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 use context ('Find the signed-in user's Tineo Library Lists by title or description') and a disambiguation instruction ('when several titles match, ask the user to select one'). It also bounds usage ('Only lists are supported; do not invent journal, place or file edits'). It stops short of naming the natural alternative siblings (library_list_get, library_list_edit).

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 idempotentHint=true, destructiveHint=true, and openWorldHint=false, so the safety profile is largely structured. The description still adds real value beyond that: it discloses partial-update semantics via updateFields and the version-mismatch recovery behavior. It stops short of stating permissions or exactly what 'destructive' means here, hence 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?

Front-loaded with the core action, then scoping, then the concurrency workflow and failure branch. Every clause carries distinct, actionable 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 annotation coverage, 100% schema coverage, and no output schema, the description supplies the missing operational context: the partial-update contract, the item-safety guarantee, and the version-conflict recovery procedure. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents updates, updateFields (including the empty-string clear convention), listId, and expectedVersion in detail. The description's parameter content (field list, updateFields scoping, listId/expectedVersion sources) largely restates 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 ('Change one owned Library List's own details') and enumerates the affected fields. It explicitly distinguishes itself from item operations ('never touches the list's items') and from trip checklists, so an agent can separate it from library_list_item_update and checklist_item_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?

Gives the precondition for the required optimistic-concurrency args ('Use the listId and expectedVersion from the latest library_list_get'), an explicit error-recovery path ('On library_version_mismatch, read the list again...never retry blindly'), and a scope exclusion ('Library Lists only, not trip checklists'). When-to-use, when-to-recover, and when-not-to-use are all covered.

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 destructiveHint=true and non-idempotency, but the description adds genuinely new behavior: exactly what is destroyed (untouched generated items) versus preserved (user-checked/added/edited items), and that generation happens on Tineo's servers via an AI model provider. It even discloses the data payload sent and the privacy exclusions (names never sent), which no annotation conveys.

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 merge rule, followed by usage gating, scoping, and the data-handling note. Dense but each sentence carries distinct information; the final data-flow sentence is long yet earns its place given the privacy implications.

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

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

For a destructive, non-idempotent, no-output-schema tool, the description covers everything an agent needs: trigger condition, merge behavior, people scoping, trip_id sourcing, and server-side processing with privacy exclusions. Nothing material is left 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: trip_id's source (trips_list), and that passing 'people' regenerates only those people's lists while creating new ones for list-less people. It reinforces rather than merely repeats the schema's own descriptions.

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

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

States a specific verb and resource ('Regenerate a trip's existing packing checklist') and immediately defines the merge semantics: untouched generated items are replaced while checked/added/edited items are kept. This uniquely distinguishes it from the sibling generate_packing_list, which an agent can now tell 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?

Gives an explicit trigger condition ('Use only after the user asks to redo or refresh the list') plus scoping rules for people and list-less trips, and points to trips_list for the trip_id. It stops short of naming generate_packing_list as the alternative for a first-time list, which is the key routing decision.

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, openWorld, non-destructive), and the description layers on context those annotations cannot express: Google rich business details are disabled, missing fields mean unavailable rather than closed/absent, and cached optional details may be stale. These are exactly the failure modes an agent would otherwise misread.

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

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

Four short sentences, ordered purpose first, then the negative routing, then two interpretation caveats. No filler, and the most decision-relevant constraint (what this tool cannot answer) 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 still tells the agent which fields to expect, how to interpret absent fields, and that cached values may be stale. Nothing needed to call or interpret this tool correctly is missing.

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

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

Schema description coverage is 100%, so both place_id and language are already documented in the schema, and the description correctly ties place_id back to places_search output. It adds nothing about the language parameter's effect on returned data, 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 (look up) and resource (place ID) and enumerates the exact fields returned: name, address, map URL, coordinates, photos, timezone. It also positions itself relative to the sibling places_search by scoping its use to IDs already obtained there.

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 ('when missing from places_search') and explicit exclusions naming six question categories (opening-hours, open-now, price, website, phone, rating) the tool must not be used for. This is a rare case of a description telling the agent both when to use it and when not to.

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.