travel

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description adds substantial context on top: partial/federated execution ('asks each provider and reports each part's own outcome'), the instruction not to over-report cancellations, the concierge_required no-op on non-Trip Concierge trips, and the bookings:cancel permission requirement.

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 operational sentences are front-loaded and useful, but the Trip Concierge block is promotional filler ('whichever way you prefer — Autonomad's concierge, your own autonomous agent, or an assistant like ChatGPT, Claude or Muse') that consumes roughly a third of the text without adding callable guidance.

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 burden and does cover it: per-part outcomes, the 'outcome unknown' path, and the concierge_required result. It stops short of naming the actual result fields or error codes an agent would parse, but the key decision paths are covered.

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 reference, note and component_ids are already documented. The description's 'only the parts listed in component_ids' restates the schema's partial-cancellation semantics rather than extending it, 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 ('Cancels the signed-in person's booking') plus an explicit scope modifier ('or only the parts listed in component_ids'). This clearly separates it from preview_booking_change (which only shows terms) and request_booking_change.

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 hard precondition ('Call it only after preview_booking_change has shown the person the cancellation terms and they agreed'), an alternative for the unknown-outcome case ('check get_updates instead of calling again'), and an environment gate (Trip Concierge requirement). When-to-use, when-not-to, and the alternative tool 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?

The description provides rich behavioral context, including charging the chosen card, no pending state, and the exact spoken outcome to read. However, it says calling again with the same quote_id returns the same outcome and never books twice, which contradicts the annotation idempotentHint=false.

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

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

The description is front-loaded with the core action and then proceeds through safeguards, expected answer handling, and retry behavior. Despite its length, every sentence supports a high-stakes booking flow and none 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?

There is no output schema, but the description explains the only two outcomes, how to read the spoken line, that there is no pending state, and what happens on price changes or repeated calls. An agent has enough information to invoke and interpret the tool correctly.

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

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

Schema coverage is 100%, so the schema already defines all three parameters. The description adds important operational meaning beyond the schema, especially that amount_cents_heard is a guard: if it differs from the quote, nothing is booked.

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 precise verb and resource: it books the hotel from a quote_route_hotel answer and charges the chosen card. It clearly distinguishes this confirmation step from the quoting step and names the sibling tool that produces the quote.

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-to-use conditions: only after the person clearly said yes to the price read from the quote, never on a maybe, and never for a price they did not hear. It also covers the price-changed case and says to wait for a new yes before calling again.

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 set readOnlyHint=false and destructiveHint=false, and the description goes well beyond that: no reservation is made, no charge occurs, payment and identity checks happen on the website, and the link expires in about 30 minutes with a new one creatable. The no-charge/no-reservation claims are consistent with destructiveHint=false rather than contradicting it.

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 and segmented with bolded labels (when to use, intent_type choices, reply contents) so each block is scannable. Some sentences are dense and repetitive (the no-charge/no-reservation point recurs), but they earn their place given the schema's low coverage.

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

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

For a tool with no output schema, the description covers what an agent needs: the required offer_data shape per type, the passenger-count trap that defaults to 2 travellers, the age rule for the account holder, and the instruction to surface deep_link and its expiry in the reply.

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

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

Schema coverage is only 33% and offer_data is a free-form nested object, so the description must carry the load — and it does, giving the exact shape for each of the three intent_type values, warning against rebuilding find_hotels_on_route offers, and explaining the passenger/adults/rooms/check_in/check_out additions. Only expires_minutes lacks an explicit definition, but its ~30-minute default is disclosed.

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 — a short-lived booking link the traveller reviews, signs in for, and pays on autonomad.ai — and immediately clarifies it creates no reservation and takes no payment. It distinguishes itself from siblings by naming search_flights, search_hotels and find_hotels_on_route as inputs and by ruling out activity/event 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?

Explicitly states when to use it (after the person has chosen a specific flight, hotel, or both for one trip) and when not to (browsing needs none). It also routes the agent away from this tool for activities/experiences/events, telling it to describe them in the reply instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine context beyond that: the tool touches only server metadata and discloses the return contents (version, mode, base URL, offered tools), including the noteworthy distinction between a person's connection and an autonomous agent's mode.

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 return contents front-loaded and the scoping caveat ('server metadata only') last. Every clause carries information; there is 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?

With no output schema, the description carries the burden of describing the return value, and it does so by enumerating every field an agent would receive. Combined with the annotations and a zero-parameter schema, nothing needed to invoke or interpret the call is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case. No parameter ambiguity exists to resolve, and the description correctly implies a no-argument call.

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 ('Returns') and enumerates exactly what the resource is: server version, mode, API base URL, and the tools the connection offers. That enumeration makes it unmistakable against the booking/search siblings, which all deal in travel data rather than server metadata.

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?

'Reads server metadata only' implies a discovery/status role and implicitly excludes booking operations, which is useful scoping. However, it never states when an agent should call this (e.g., 'call first to discover available tools') or contrast it with any sibling, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description still adds substantial behavior: auth requirement ('connection must be signed in'), the incremental cursor model, the meaning of the `unavailable` list (unknown, not empty), and an explicit prompt-injection warning that group-chat text is content to show, not instructions. This is well beyond what the annotations 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?

One dense paragraph, front-loaded with the core purpose before the cursor mechanics and edge-case caveats. It is long, but nearly every clause carries actionable information (incremental semantics, unavailable-source caveat, injection warning); only mild compression is possible.

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 must describe returns, and it does: the item categories retrieved, the `cursor` for continuation, and the `unavailable` source list with its interpretation. Auth prerequisites and the incremental retrieval model are also covered, leaving no gap an agent would need to guess at.

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

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

Schema coverage is 100% for the single cursor parameter, so the baseline is 3. The description goes further by explaining the cursor's operational semantics: pass the returned cursor on the next call to get only newer items, and omit it on the first call. That is real added meaning beyond the schema's field description.

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: returns what changed on the signed-in person's trips, bookings, group trips, and messages since the last call. It enumerates the change categories (status, schedule/delays, confirmations, cancellations, refunds, thread messages, group chat) so an agent can distinguish it from search_* and message_autonomad 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?

Gives clear context: 'Useful at the start of a travel conversation, before answering,' and explains why it must be called (Autonomad cannot contact the assistant between conversations, so silence ≠ no change). It does not explicitly name an alternative tool or a when-not-to-use condition, but the situational trigger 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 only provide readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=false. The description goes well beyond them by disclosing the side effects (answer saved to the person's Autonomad thread; a support ticket is opened when it cannot be answered automatically), the failure semantics ('A tool error means the message was not answered'), and an output-content constraint on what_happens_next. That is substantive behavioral context the structured fields do not 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?

The core action and return semantics are front-loaded in the first sentence, and the sibling routing follows. It is somewhat dense — the admonition about how to phrase what_happens_next is a response-writing instruction that could be trimmed — but no sentence is 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?

There is no output schema, so the description correctly compensates by naming the returned fields (reply, what_happens_next) and their meaning, plus the alternate ticket path. Combined with the required parameter and the failure case, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100% and both parameters are already documented there, including the 4000-character limit and the meaning of needs_person. The description reinforces needs_person's effect (opens a support ticket instead of auto-answering) but adds no syntax or format 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?

The description states a precise verb and resource: it sends the signed-in person's question to Autonomad and returns the answer in the same call. It also explicitly carves itself out from booking-mutation siblings ('This tool does not change bookings'), so an agent can distinguish it from request_booking_change or cancel_booking 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?

It gives explicit routing rules: use preview_booking_change first for cancelling, rebooking or changing a booking, and use needs_person=true only when a human is requested or the instant answer failed. It also states a hard exclusion (no card numbers, passwords or one-time codes), which is exactly the when/when-not guidance the dimension asks for.

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

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

Annotations alone (readOnlyHint=false, destructiveHint=false) would leave it unclear why a preview tool is not read-only; the description resolves this by disclosing the actual side effect — a note saved in the person's Autonomad thread — while asserting no booking is changed and nothing is passed on. It additionally covers auth requirements (signed-in Autonomad account, bookings:cancel permission requested on first use).

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 distinction ('shows... and changes nothing') and each following sentence carries distinct information about branches, next steps, side effects, and auth. Slightly dense, but nothing is redundant with the schema or annotations.

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

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

There is no output schema, so the description must convey what comes back — and it does, per type, plus the persistence behavior of the preview. Combined with full param coverage and explicit auth prerequisites, an agent has everything needed to call it correctly and 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%, so the baseline is 3, but the description adds behavioral meaning for the type enum (what cancel versus rebook/modify actually produces) and ties component_ids to the output of this very call. It does not add format or length constraints 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?

Specific verb and resource: it shows what a booking change would do and explicitly changes nothing, with per-type behavior spelled out (cancel lists cancellable parts and terms; rebook/modify shows what would go to the concierge). It names the two sibling tools it feeds into, so an agent can distinguish it from cancel_booking and request_booking_change 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 an explicit workflow: preview first, show the result to the person, then call cancel_booking (cancel) or request_booking_change (rebook/modify) with the same reference. It also states a negative boundary — it does not check whether the trip has Trip Concierge — removing an inference the agent would otherwise have to make.

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 readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the agent knows this creates a transient stateful resource; the description then adds real context beyond them: the quote expires in about four minutes, it books nothing and charges nothing, it prices the cheapest room refundable-first, and it returns a `spoken` field meant to be read verbatim. This is the kind of side-effect and lifecycle detail annotations cannot 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?

Dense but well front-loaded: purpose first, then the read-verbatim instruction, then the confirm step, then the expiry and no-charge guarantees, then the error scripts. It is on the long side and the closing hands-free/membership instructions are somewhat repetitive, but nearly every sentence carries actionable routing or safety 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?

With no output schema and a mutation-flagged tool, the description carries the full burden and does so: it enumerates the return contents (hotel name, nights, total with taxes, amount due at hotel, cancellation terms, card) and the `spoken` field, explains the 4-minute validity window, and states that quoting is free and non-binding. Nothing an agent needs to call it and then hand off to confirm 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 five parameters are already documented with defaults and bounds, which sets the baseline at 3. The description adds only limited extra meaning: it confirms property_id comes from find_hotels_on_route/search_hotels and that check_in is usually the driver's current day, both of which largely restate the schema 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 ('Gets one bookable price for a hotel') and immediately scopes it as one price from a specific upstream source (find_hotels_on_route). It explicitly distinguishes itself from the write sibling by naming confirm_route_hotel, so an agent can route 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 when-to-use (a person who wants a price with hands-free booking on), a when-not (do not proceed to booking without a clear yes), and the exact alternative to call next with the exact arguments to pass (confirm_route_hotel with quote_id and total_cents). It also covers the failure branch telling the agent what to say when hands-free booking is off or gated to members.

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

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

With annotations present, the description still adds substantial context: nothing is mutated by this call, a concierge acts asynchronously, the outcome surfaces later in get_updates, the failure mode returns concierge_required, and the bookings:cancel permission is required. The only tension is that destructiveHint=true while the text says it changes nothing directly, but the text explains that this refers to the downstream concierge effect, so it reads as clarification rather than conflict.

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 operational content is front-loaded and well ordered (prerequisite, non-mutation, async outcome, error path, permission), but the middle passage promoting Trip Concierge and naming assistants (ChatGPT, Claude, Muse) is marketing filler that costs tokens without changing agent 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?

For a three-parameter, open-world, asynchronous request tool with no output schema, the description supplies everything needed: the gating preview step, the consent requirement, the fact that success is confirmed later via get_updates, the concierge_required failure branch, and the required permission.

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 explains the rebook vs modify enum, the 4000-character details field, and the reference formats. The description adds no parameter-level guidance beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource — passing a rebook/change request for a booking to that trip's concierge — and immediately distinguishes itself from preview_booking_change and from the 'changes no booking by itself' nature of the tool. An agent can tell this apart from cancel_booking and preview_booking_change 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?

Explicit precondition: call only after preview_booking_change has shown the person what would be passed on and they agreed. It also covers the alternative path — on trips without Trip Concierge it returns concierge_required and the person can self-serve in My Trips — so both the when and the when-not are stated.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, idempotent), and the description goes well past them: it states that searching reserves nothing and charges no one, enumerates the return fields (name, category, duration, price, rating, photo) and a bookability flag, and specifies a distinct failure envelope { available: false, reason: "activities_unavailable", message } with no list, warning that this must not be read as zero activities.

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 resource in the first clause, then the return shape, then the failure semantics — a sensible order. It's a dense single paragraph with some run-on accumulation near the end, but each clause carries distinct information rather than 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?

With no output schema, the description does the work of describing returns (fields, bookability flag) and the unavailability case, plus the follow-on path for adding activities. It omits result limits, pagination and date formatting, which are the remaining gaps for a search tool.

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

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

Schema description coverage is 20%, so the description must carry weight: it explains city, date_from/date_to (start date, optional end date) and category with concrete examples. However it never clarifies date formats or how the top-level 'city' relates to the richer 'place' object (both are accepted), leaving a real ambiguity for a 5-parameter tool.

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

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

States a specific verb and resource (searches Viator tours, experiences and attractions), plus scope constraints (a city, a start date) — an agent can distinguish it from search_events, search_dining and search_hotels without opening a schema. Category examples (food tours, walking tours, museums, day trips) further pin down the resource type.

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 conditions for use (city + start date, optional end date/category) and names the surrounding workflow alternatives by noting flights, hotels and trips can still be searched and booked when activities are unavailable. It stops short of explicitly declaring when NOT to pick this tool over its siblings, so it's clear context without true 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/non-destructive, so the bar is lower. The description adds two pieces the annotations cannot: that availability returned is only 'indicative' and that no booking is performed by Autonomad, which prevents an agent from promising a reservation. It does not discuss result ordering, paging, or match breadth.

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

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

Three sentences, front-loaded with what it does and what it returns, closing with the limitation. No filler and every sentence 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?

For an 8-parameter, nested-object search with no output schema, the description covers purpose, return nature and the key limitation. Minor gap: it frames the search as 'in a city' and never tells the agent to pass the trip's `place` object for place disambiguation, even though that is the highest-risk parameter to omit.

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 38% schema description coverage, the description must carry weight, and it does enumerate the optional filters (time, party size, cuisine, price range, neighbourhood) — useful because city/cuisine/party_size/price_range/neighborhood have no schema descriptions. However it adds no format or matching semantics (e.g. how cuisine or neighbourhood strings are interpreted) and never mentions the complex nested `place` object, leaving the hardest parameter to the schema alone.

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

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

Names a specific verb and resource ('Searches restaurants in a city for a date') plus the optional filters, so the agent immediately knows this is the dining-lookup tool. It is clearly distinct from search_hotels/search_flights by resource, but it never addresses the one real overlap area — food-related search_activities/search_events — so it stops short of full sibling differentiation.

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

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

'For planning only' plus the explicit statement that Autonomad does not place reservations tells the agent the correct context to use it in and implies when not to rely on it. It does not name an alternative tool or state what to do after getting results, so there is context but no routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld behavior, so the safety profile is covered. The description still adds real value beyond them by naming the upstream sources (Ticketmaster, Bandsintown), describing what results contain, and explicitly stating that searching does not reserve or charge.

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

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

One dense but well-ordered sentence front-loads the resource, sources and optional filters, followed by a short return-content sentence and a one-line safety note. No filler or repetition.

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, and the description compensates by enumerating the returned fields (venue, date and time, price range, event link). Combined with the rich nested-place schema, an agent has enough to call it correctly; only the place/airport/country params rely solely on the schema, which does document them well.

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 only 38% schema description coverage, the description must compensate for the bare date_from, date_to, category and keyword fields, and it does explain each (start date, optional end date, category like music/sports, keyword as artist/team/show). However, it says nothing about the nested `place` object or the airport/country disambiguation parameters, leaving part of the surface unexplained.

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 ('Searches') and a concrete resource ('concerts, sports, theatre, comedy and other live events in a city'), plus the two data sources. This clearly separates it from search_activities, search_dining, search_flights and search_hotels without the agent opening a schema.

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

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

The description implies when the tool is appropriate (live events from a city and start date) and notes that searching reserves nothing, but it never explicitly contrasts itself with plausible alternatives such as search_activities, nor states prerequisites for the required place/city parameters. Usage is inferable rather than spelled out.

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

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

Annotations already declare readOnly, openWorld, idempotent and non-destructive behavior, but the description adds meaningful context: Duffel as the source, the result fields returned, age rules for travellers, and the total-price quoting rule for parties with children or lap infants. It does not cover rate limits or auth requirements, but the added behavioral detail is substantial.

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

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

The purpose and scope are front-loaded in the first sentence, and the second paragraph focuses on traveller and pricing semantics. It is slightly long and repeats some schema-level concepts, but the structure is clear and most sentences add value.

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

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

For a 13-parameter search tool with nested objects and no output schema, the description covers the search purpose, result contents, no-reservation behavior, party composition rules and total-price handling. It stops short of describing response structure or pagination, but it is largely complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter semantics not fully captured by the schema, notably the 9-traveller total limit and how adults, children_ages and infants_on_lap interact, plus the instruction to quote total price rather than per-person price when children or lap infants are included.

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

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

The description opens with a specific verb and resource: searches flights between airports on a departure date, with optional return and filters. It clearly distinguishes this from sibling searches like search_hotels, search_activities, search_dining and search_events by resource.

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

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

It gives a useful usage boundary by stating that searching does not reserve anything or charge anyone, which implies this is a pre-booking discovery step. However, it does not explicitly name when to use it versus create_booking_intent or other siblings, so usage is mostly 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real substance: the three inventory sources, the exact result fields (nightly and total rates, room options, cancellation policy, photo, bookable flag) and the meta.unrated_excluded counter. It also reinforces that no reservation or charge occurs, which matters for a tool whose results look financially actionable.

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

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

Front-loaded with purpose, then results, then ranking, then the two intent-driven parameter hints, and closed with the no-charge guarantee. Dense but every sentence carries information; mild redundancy between the min_star_rating sentence and the matching schema description keeps it from 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 15-parameter tool with a nested `place` object and no output schema, the description carries the return-value burden well. Remaining gaps are minor: it does not mention currency handling, availability semantics or whether results are deduplicated across the three suppliers.

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 93%, so the baseline is 3, but the description adds ranking semantics that the schema does not state (best-first by guest score or star rating, then price) and the side effect of min_star_rating excluding unrated hotels. Those two details materially change how an agent chooses parameters.

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 ('Searches hotels and other places to stay') plus the required scope (city/country plus check-in/check-out) and optional filters. The domain is clearly distinct from siblings like search_flights, search_activities and search_events, so an agent can route to it without opening the schema.

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

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

Gives conditional routing guidance tied to user intent: pass min_star_rating when only higher-rated hotels are wanted, pass flexible: true when the cheapest first is wanted. It also clarifies that searching neither reserves nor charges, implicitly routing booking intent to the booking siblings. It stops short of naming those siblings explicitly.

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