My Next Adventure

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing a downstream consequence: omitting total cost and currency corrupts the trip budget. It still says nothing about return shape, duplicate handling, or permission requirements.

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 the tool does, then the multi-option workflow, then the two hard constraints. No preamble, no repetition of the title, and every sentence carries a distinct instruction.

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

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

For a nested-object mutation tool with no output schema, the description covers purpose, workflow routing, a required-field constraint and a naming convention. Gaps remain around what is returned after the add and how duplicates or re-adds behave, but annotations carry the safety profile so nothing critical for 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%, including detailed guidance on name hygiene, currency, dates and nested objects, so the baseline is 3. The description restates the cost/currency requirement and the 'keep name clean' rule, which reinforces but does not add syntactic or semantic detail beyond what the schema already provides.

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 ('Propose somewhere to stay at a destination') and enumerates the supported types (hotel, hostel, apartment, house, camping), which maps directly onto the type enum. It also situates the tool in a workflow by naming select_destination_option as the downstream step, so an agent can separate it from sibling add_* tools 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?

Explicitly tells the agent to add several options to the same destination for comparison and to route to select_destination_option once a choice is made — clear when-to-use and a named alternative. However, it never mentions the obvious edit path (update_destination_option) for correcting an existing option, so the guidance is one-directional rather than 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 declare readOnly=false, destructive=false and idempotent=false, so the mutation and safety profile is partly covered. The description adds genuine behavioral context beyond that: the ordering relationship to option-type tools, that destinations are the anchor objects options attach to, and that isReturnToHome is pinned to the end. It doesn't mention permissions or return identity, but it adds real value over the annotations.

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

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

Two tight sentences, front-loaded with the core action and scope, followed by the ordering prerequisite and the special-case parameter hint. Every sentence carries information an agent needs to call it correctly.

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 safety profile is covered by annotations and the description supplies the workflow ordering and isReturnToHome semantics. What is missing is what the call returns and how the newly added destination is identified for follow-up calls (e.g. update_destination), so it is strong but not fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes slightly beyond by giving usage meaning to isReturnToHome ('for the final leg home') and tying the destination data to itinerary order, which reinforces how startDate/endDate fit. It adds a little but leaves most parameter detail to the schema.

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

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

States a specific verb and resource ('Add a place the traveller will stay at within a variant') and clarifies the domain concept with a concrete example ('Lisbon, Portugal'). It also distinguishes destinations from the option-type siblings by explaining that accommodation, transport and getting-around options attach to destinations.

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 ordering guidance: 'add these before adding options' and 'Set isReturnToHome for the final leg home.' This tells the agent both the sequencing prerequisite and a special-case parameter usage. It stops short of naming a specific alternative sibling or stating when not to use it, so it is not a full 5.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write. The description usefully adds that events attach to the variant and that start/end are optional (scheduled or left as ideas), which is real behavioral context. It does not cover permissions, duplicate-handling, or what the call returns.

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 with zero filler, front-loaded with the core action and immediately followed by the scoping constraint. 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?

For a write tool with full annotation coverage, a complete input schema, and no output schema, the description is largely sufficient. The remaining minor gap is that it never clarifies the created-event return or duplicate behavior, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema fully documents the three parameters including the nested data object. The description's mention of optional start/end scheduling loosely maps to the start/end fields but adds no syntax or format detail beyond the schema, 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?

Clear specific verb+resource ('Add ... a museum, concert, restaurant, tour or activity') that concretely defines what an event is. It also distinguishes itself from add_destination by stating events belong to the variant rather than a single destination, though it does not explicitly separate itself from update_event or toggle_event.

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 context is implied ('Add something to do during the trip') and the variant-vs-destination routing hint helps. However, there is no explicit when-to-use vs when-not guidance relative to siblings like update_event, toggle_event, or add_destination.

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, destructiveHint=false, idempotentHint=false, and openWorldHint=false, covering the safety profile. The description adds the conceptual scoping of what an 'option' represents (a proposed local mobility choice) but does not state that this is a non-idempotent write (duplicates on repeat) or what happens to existing options. With annotations carrying the mutation/safety profile, a 3 is appropriate.

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

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

Two sentences, zero filler. The core purpose is front-loaded and the disambiguation from add_transport_option is stated in the same breath.

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

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

Given a fully documented schema and annotations that cover the mutation profile, the description supplies the conceptual scoping and sibling disambiguation an agent needs to route correctly. It does not address idempotency/duplicate behavior, a minor gap for a non-idempotent write.

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 data object is fully documented, including the type enum and notes field. The description adds semantic context for what the option means but no detail on parameters beyond what the schema provides. Baseline 3 is correct 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 action (propose how the traveller moves around locally) with the resource (getting-around option) and cites concrete examples (walking, public transport, rental car, bike, ride share). It explicitly distinguishes itself from the sibling add_transport_option by scoping to local mobility vs journey between destinations.

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 (local mobility budgets once at a destination) and when to use an alternative ('the journey between destinations belongs in add_transport_option'). The boundary condition and the named alternative are both stated directly.

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=false, destructiveHint=false, openWorldHint=false, and idempotentHint=false. The description adds real behavioral context beyond them: the server auto-detects whether the input is a name or URL and enriches the entry. It omits that repeated adds are not idempotent (likely creating duplicates), which is the main remaining gap.

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

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

Two sentences, both earning their place: the first defines the action and its input flexibility, the second gives the usage trigger. Nothing is redundant or buried.

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 mutation with no output schema, the description covers input handling and when to call it. It could go further on duplicate behavior given idempotentHint=false, but the essential information for correct invocation is present.

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 nested 'input' parameter, so the schema already documents the name-or-URL duality. The description restates the same fact without adding format, length, or validation 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?

States a specific verb (Add), resource (travel goal to the user's bucket list), and accepted input forms (plain name or URL). It is clearly distinguishable from siblings like add_destination or add_event, which target planning artifacts rather than aspirational bucket-list items.

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 usage trigger: the user mentions something they would love to do someday but is not planning right now. The contrast with planning-now implies add_destination/add_event as alternatives, but no sibling is named outright, so the routing 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 the safety profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower. The description adds real behavioral context: the operation is additive, multiple options are expected, and it clarifies the roundTrip cost semantics. It stops short of describing return values or auth, but this is solid added value over 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?

Three tight sentences, front-loaded with the purpose, then usage, then the sibling redirect. No filler; every sentence carries information the 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 a nested-object, no-output-schema tool, the description covers what the tool does, when to use it, and the key semantic field. Given the schema carries all required-parameter documentation, nothing critical is missing, though it does not hint at how the option is keyed or identified afterward.

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 a 3 would be the baseline. The description goes beyond it by explaining the meaning of roundTrip ('when the price covers the return leg too'), a non-obvious semantic not stated in the schema. It does not address the related roundTripReturn / outboundIncludesReturnCost fields, keeping it from a 5.

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 concrete verb and resource ('Propose a way of travelling TO a destination') and enumerates the transport modes covered. It explicitly contrasts with the sibling add_getting_around_option, so an agent can distinguish the two 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?

It states the when ('one option per candidate itinerary; add several so the user can compare price against travel time') and the when-not with the named alternative ('For moving around once there, use add_getting_around_option instead'). The routing decision is 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description wisely spends its words elsewhere: it explains the schema-drift phenomenon that motivates the call and confirms 'takes no arguments and changes nothing.' That causal explanation is real context an agent cannot get from the annotations.

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

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

Three sentences, front-loaded with the output (what it reports) before the trigger and the rationale. No sentence is padding — each adds either scope, trigger, or mechanism.

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, yet the description states what the caller learns (build identity and schema-match status), which is exactly the return-value information an agent needs. For a no-arg diagnostic tool this is fully 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?

Zero parameters, so the baseline is 4. The description reinforces this with 'takes no arguments,' which removes any doubt about whether an empty object is required or a payload is expected.

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 — reporting the connector build and whether its advertised tool schemas match the live API. The resource is unmistakably distinct from the trip-planning CRUD siblings and from `whoami`, which concerns caller identity rather than connector contract.

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 crisp, concrete trigger: call it when a tool rejects a field you expect to exist or accepts one with no effect. It supplies the causal rationale (clients cache schemas at connect time) so the agent understands why the trigger matters. It does not name when-not-to-call or point at a sibling alternative, so it stops 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 the write/non-idempotent/non-destructive safety profile, so the bar is lower; the description adds genuinely useful context that the trip is created *empty* and that it is the parent container for all downstream items. It does not mention auth requirements, rate limits, or what is returned, but covers the key behavioral trait beyond annotations.

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

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

Three sentences, front-loaded with the core purpose followed by the workflow and a practical tip; every sentence earns its place. Slightly long but 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 creation mutation with no output schema, the description conveys what gets created and how it fits the workflow, but it never states what the call returns or that the returned trip identifier is required for the next step (create_variant). That chaining detail is the main omission.

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 both name and coverPhoto with its own constraints, so the description need not carry parameter detail. The only added value is the operational note to ask the user for a name if absent, which is marginal — 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 (create) and resource (trip) and immediately frames it as 'the container everything else hangs off,' which distinguishes it from the add_*/update_* siblings that operate on an existing trip. An agent can tell this is the root creation step 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 positions the tool as 'step 1 of planning' and sequences it against concrete siblings (create_variant, add_destination, accommodation/transport/event options), so the when-to-use is clear. It stops short of naming when NOT to use it (e.g. update_trip for existing trips, duplicate_variant), so it is not fully exhaustive.

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 context beyond annotations: the link is public and read-only, and the operation refreshes an existing link rather than duplicating it (consistent with idempotentHint=true). It also discloses the return value (the shareable URL), which matters since no output schema exists. It stops short of explaining revocation or expiry of the link, which is the only notable gap.

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

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

Three short sentences, front-loaded with the action and its effect, then the return value, then the trigger condition. 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 single-parameter, no-output-schema tool this covers purpose, trigger, and return value. It could say more about link lifetime/revocation, but nothing essential for 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 coverage is 100% and tripId is documented in the schema, so the description adds nothing parameter-specific beyond referring to 'the trip'. 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+resource ('Create (or refresh) a public read-only link to the trip') and clarifies the effect (read-only, public). No sibling tool overlaps, and the refresh behavior is called out 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?

Gives clear triggering context: 'Use when the user asks to share, send or publish a trip.' No alternatives or exclusions are named, but none are needed since no sibling offers competing share functionality.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent mutation. The description adds genuine behavioral context beyond that: the ordering dependency on create_trip and the downstream constraint that destinations/options cannot exist without a variant. It omits the practical consequence of non-idempotency (calling twice creates two variants).

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 front-loaded sentences: purpose with examples first, then the prerequisite/sequencing, then the key dates constraint. Every sentence carries information and 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?

For a create tool with annotations and a rich nested schema, the description covers purpose, prerequisite, and the dates model. It does not state what the call returns (e.g. the new variant id needed for subsequent add_destination calls) and there is no output schema to fall back on, leaving 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%, so the schema already documents tripId, name, dates (both shapes), participants, and notes. The description only restates the dates duality ("exact start/end dates or a flexible window with min/max nights") that the schema already explains, adding no new syntax or format detail. 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+resource ("Add an alternative version of the trip") with concrete examples ("Beach option" vs "Mountain option") that make the concept unambiguous. It is clearly distinguishable from siblings like duplicate_variant, update_variant, and select_variant.

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 sequencing guidance: "create one right after create_trip" and the prerequisite that a trip needs at least one variant before it can hold destinations or options. It does not, however, mention alternatives such as duplicate_variant for copying an existing variant.

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, so the safety profile is known. The description adds genuinely new behavioral context: the deletion is permanent, deleting a variant/destination cascades to everything inside it, and user confirmation is required beforehand. It stops short of describing error modes or auth requirements, so not quite 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, front-loaded with the destructive scope, then usage routing, then the cascade warning. No filler and every sentence carries actionable information.

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

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

For a destructive, no-output-schema tool, the definition covers what it deletes, when to prefer it over siblings, the cascade risk, and the confirmation requirement. Combined with annotations and full schema coverage, an agent has everything needed to invoke 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 description coverage is 100% and the schema itself documents conditional requirements (kind for option, eventKey for event, destinationKey for destination/option) plus the optionKey/optionId naming quirk. The description adds only the target-type list, which the schema already covers, 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 (permanently delete) and enumerates the exact resources it applies to: variant, destination, destination option, event. This clearly distinguishes it from siblings like update_destination_option, toggle_event, and select_destination_option.

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 ('only when the user rejects something outright') and names the alternatives for the softer case ('deselect the option or toggle the event instead'). It also sets a prerequisite: confirm with the user first for cascading deletes.

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 state the safety profile (write, non-destructive), so the description earns credit for disclosing copy semantics: everything (destinations and options) is carried over and the source variant is preserved. It stops short of noting that repeated calls create additional variants (idempotentHint=false) or what identifier comes back for follow-up selection.

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

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

Two sentences, front-loaded with the action and scope, followed by the usage trigger with illustrative examples. No filler and every clause carries information.

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

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

For a two-parameter creation tool with no output schema, the description covers what is copied and why, which is enough to invoke it correctly. The one real gap is the return value (presumably the new variant id needed for select_variant), which has no output schema to fall back on.

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 tripId and variantId are documented in the schema with sourcing hints (list_trips, get_trip). The description only indirectly gestures at the same-trip constraint and adds no format or sourcing detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Copy a variant ... into a new variant on the same trip') plus the scope of what is copied (destinations and options). It implicitly distinguishes itself from the sibling create_variant by framing the action as a copy of an existing variant rather than creating a blank one, but it never names that sibling 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?

Gives a clear when-to-use condition with concrete examples ('same trip but a week later', 'same route, cheaper hotels') and the motivation ('without losing the original'). It does not name or exclude alternative tools such as create_variant or update_variant, so routing is still partly 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 already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description adds real value by disclosing the dependency semantics — that its returned keys are the inputs other tools require. It does not discuss pagination or size limits for a 'full trip' fetch, which is a minor gap.

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

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

Two sentences, both earning their place: the first defines the payload, the second defines the call ordering. The prerequisite is front-loaded and there is no redundant restatement of the title or schema.

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

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

With no output schema, the description carries the burden of describing return content, and it does enumerate the main object families returned. It could be slightly more complete about nesting or size of the response, but an agent has enough 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 tripId and includeAllOptions are already fully documented in the schema, including the 'set true when comparing alternatives' guidance. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch one trip') and enumerates the payload it returns (variants, destinations, accommodation/transport/getting-around options, events). This clearly separates it from the plural sibling list_trips 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 a strong, actionable prerequisite: 'Call this before changing anything — every other tool needs the variant ids, destination keys and option keys this returns.' That tells the agent exactly when to reach for it. It stops short of naming when not to use it (e.g. use list_trips to enumerate trips), so it is clear context rather than a full routing rule.

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 real domain context by explaining what each status means in lifecycle terms, which the 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?

Three tight sentences: identity first, then usage triggers, then the status legend. Every sentence carries distinct information and nothing is repeated from the schema.

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

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

For a read-only, no-required-param list tool with no output schema, this covers purpose, invocation context, and filter semantics adequately. It could optionally note the return shape (a list of goals) or that all three filters combine, but 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 the baseline is 3, but the description earns above baseline by defining the enum values semantically ('dreaming' = not planned, 'planning' = linked to a trip, 'visited' = done), turning bare enum strings into usable filter criteria. It adds nothing for tripId/collection 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 (list) and resource (the user's travel goals), then disambiguates with a concrete example ('See the Northern Lights'). This clearly separates it from the write-side sibling add_goal and from trip-oriented tools like get_trip/list_trips.

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

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

Gives explicit when-to-use triggers: 'inspiration when starting a new trip' and 'when the user asks what is on their list.' It does not name a competing alternative tool or state when-not to use it, so it stops 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the meaning of each status value and the default scope when no filters are supplied.

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, each doing work: scope, routing guidance, enum semantics, default behavior. The most actionable guidance (start here, resolve a name to an id) 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?

There is no output schema, so the description carries some burden for return values; it hints at the key one (trip ids for later use) but does not describe the returned fields. For a simple, zero-required-parameter list tool with full annotation coverage, this is nearly complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by defining what each enum value actually means ('planning' is actively worked on, 'ready' is planned but not taken, etc.), which the schema's terse 'lifecycle status' line does not convey. includeExample is left to the schema, which is acceptable.

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 (List) and resource (trips) with an ownership scope: trips the user 'owns or collaborates on'. This clearly distinguishes it from get_trip and the many mutating siblings (create_trip, update_trip, add_destination).

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 tells the agent when to reach for this tool: 'Start here whenever the user refers to a trip by name ("my Japan trip") so you can resolve it to a trip id.' It also states the no-filter default ('Call with no filters to see everything'), giving both a trigger and a fallback behavior.

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

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

Annotations already declare this is a non-read-only, non-destructive, idempotent mutation, so the safety profile is covered. The description's implicit point that reordering is preferable to delete-and-re-add adds some context, but it says nothing about partial-order semantics, error behavior, or permissions. The important detail that unspecified keys get sorted to the front lives in the schema, not here.

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, zero waste, with the action stated first and the usage guidance immediately after.

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 small, fully-documented, idempotent mutation with no output schema, the description plus schema covers what an agent needs to call it correctly. Minor gap: no statement of what happens on invalid keys or whether the full destination set must be supplied.

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%, including a nested 'order' array with its own explanation of how missing keys are handled. The description adds no parameter-level meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb (rearrange) plus resource (itinerary order of a variant's destinations), which distinguishes it from update_destination and add_destination in the sibling list. It does not explicitly name a sibling tool, but the resource 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 usage context ('use after adding stops out of order') and rules out a workaround ('instead of deleting and re-adding them'). Clear on when to use, though it never names an alternative tool or states prerequisites (e.g. trip/variant must exist).

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 non-read-only, idempotent, and non-destructive, and the description is consistent with all three. It adds real context beyond them: that it returns the destination state after the change, and that unselected alternatives are preserved for comparison rather than removed. It stops short of describing failure cases or permission needs.

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 front-loaded sentences covering action, parameter rule, return value, and the anti-pattern of deleting alternatives. Slightly dense but every sentence carries necessary 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?

With no output schema, the description correctly explains the return value ('the destination as it now stands'), the required kind, and the select/deselect mechanics. It is complete enough to invoke correctly; only error/edge behavior (e.g., invalid optionId) is unaddressed, which is minor for 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema doesn't state as directly: omitting optionId is the deselect path for the given kind, and kind is mandatory because an option key alone doesn't reveal which list it belongs to. That elevates it above the schema-only 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 precise verb+resource: marking a single accommodation/transport/getting-around option as the chosen one, or clearing that choice. It clearly differs from siblings like delete_trip_item and update_destination_option by naming the selection action and the three option domains.

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

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

Gives explicit operating rules: always pass the kind, pass optionId to select, omit optionId to deselect that kind. It also names an alternative behavior ('Prefer this over deleting the alternatives') and explains why, which is exactly the when-to-use/when-not guidance the dimension rewards.

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=false, so the safety profile is covered. The description adds genuine behavioral context beyond them: the choice is reversible and can be re-selected later, which reassures the agent about the consequences of the mutation.

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 core action front-loaded and the reversibility note following. 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?

For a simple two-parameter, no-output-schema mutation tool, the description covers purpose, trigger, and reversibility. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both tripId and variantId are already documented in the schema. The description implies variantId identifies the chosen plan but adds no syntax or format meaning beyond what the schema provides, making the baseline 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 and resource: 'Mark one variant as the trip's chosen plan.' This clearly distinguishes it from sibling write tools like create_variant, update_variant, and duplicate_variant without requiring the schema to be opened.

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

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

It gives clear usage context: 'Use when the user decides between alternatives.' This tells the agent the triggering scenario, though it does not explicitly name the alternative tools (e.g. update_variant) a variant selection might be confused with.

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=false, destructiveHint=false, idempotentHint=false, so the mutation profile is known. The description adds the meaningful lifecycle context that the event is preserved rather than removed, which is the key behavioral distinction from deletion. It does not clarify what a repeated toggle does to an already-set state, which is minor.

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

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

Two tight sentences: the action and its state pair come first, then the usage condition and the sibling contrast. 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 3-param mutation with full schema coverage and no output schema, the description supplies the action, the trigger, and the non-destructive lifecycle. It omits what the call returns or whether the flip direction is inferred from current state, but nothing essential to invoking it 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 all three params (tripId, variantId, eventKey) are documented in the schema with their source (list_trips/get_trip). The description adds no parameter-level syntax or semantics beyond that, so the baseline 3 applies.

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

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

States a specific verb (flip/toggle) and resource (event) plus the two concrete states it moves between ("we are doing this" vs "just an idea"). An agent can distinguish it from update_event and delete_trip_item 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 names the trigger condition (user commits to or backs out of an activity) and contrasts it with the alternative delete_trip_item, noting this keeps the event around. When-to-use and when-not-to-use are both 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 readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context (e.g. that omitted fields stay unchanged, that null clears a value, or any permission requirement) beyond what annotations and the schema already say.

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: the first front-loads what can be changed, the second supplies the usage rationale. 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 mutation tool with no output schema and solid annotation coverage, the description supplies purpose and usage rationale, and the nested 'data' object's partial-update contract lives in the schema. It is only slightly incomplete in not mentioning isReturnToHome among the changeable fields.

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 every parameter, including the null-to-clear semantics and the 'omitted fields are left as they are' contract. The description's field list mirrors three of the mutable fields but omits isReturnToHome, adding little beyond the schema. Baseline 3 applies.

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

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

The description states a specific verb ('Change') plus the mutable fields (place name, arrival/departure dates, notes) of a named resource, which is more than a restatement of the title. It does not explicitly distinguish itself from the nearby update_destination_option / update_variant / update_event siblings, but the field list makes the scope unambiguous.

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

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

It gives a concrete usage context ('once the dates firm up') and names an alternative workflow it replaces ('rather than deleting and re-adding the stop'). There is no explicit when-not guidance, but the routing signal is clear enough for an 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 idempotent=true, destructive=false, readOnly=false and openWorld=true. The description adds genuine behavioral context beyond them: 'Only the fields you send are changed' discloses PATCH-style partial-update semantics, which the annotations alone do not convey. It stops short of covering auth or conflict behavior.

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

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

Three tight sentences, front-loaded with the verb and scope, followed by concrete edit examples and then the required identifiers. Every clause earns its place 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 6-parameter, nested-body mutation tool with no output schema, the description covers the essentials: what is editable, that kind selects the applicable fields, that keys come from get_trip, and that the update is partial. It does not explain the coupling between 'kind' and which data fields are valid (left to the schema), leaving 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%, so every parameter (tripId, variantId, destinationKey, kind, optionKey) is already documented in the schema, including the optionKey/optionId aliasing note. The description reinforces that kind must be supplied and optionKey comes from get_trip, but adds no syntax or format detail 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 (Edit) and resource (an existing accommodation, transport or getting-around option), then grounds it with concrete edit examples (price, booking link, check-in dates). The word 'existing' plus the enumerated kinds distinguishes it cleanly from the sibling add_*_option 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 the key prerequisite explicitly — 'Say which kind of option it is and pass the option key from get_trip' — which routes the agent through get_trip before calling. It implies editing rather than creating, but never names the add/delete/select alternatives or states when not to use it, so it falls 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 already declare non-readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description reinforces that this is a partial edit rather than a full replacement, but adds no context on auth requirements, side effects, or what happens to fields not supplied (that detail lives in the schema, not the description).

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: the capability first, the triggering condition second, with a natural-language example. No filler and nothing buried.

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 partial-update tool with full schema coverage, an explicit annotation set, and no output schema, the description covers the essentials an agent needs to select and invoke it. It stops short of richer behavioral detail (permissions, conflict handling), which is the only gap.

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

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

Schema description coverage is 100%, so every parameter including the nested location object is already documented. The description's field list (time, price, location, booking link, notes) loosely maps to start/end, totalCost, location, link, notes but adds no syntax, format, or precedence 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 (Edit) and resource (existing event) and enumerates the concrete fields that can be changed: time, price, location, booking link, notes. This clearly separates it from add_event, which creates rather than edits.

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

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

Explicitly says when to use it — 'when the user has new information about an activity that is already on the plan' — and gives a concrete utterance example. It implies the boundary with add_event ('already on the plan') but does not name sibling alternatives like toggle_event or delete_trip_item for other operations on an event.

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=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the lifecycle state machine and the guarantee that variants, destinations and options are untouched.

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 action and scope; the exclusion clause is compact and every phrase carries information. 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 annotations, a fully described schema and no output schema, the description covers scope, fields and lifecycle adequately. Return behavior is unspecified but no output schema exists to require it, so the only minor gap is the absence of explicit preconditions.

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 tripId, name, status and coverPhoto fully. The description corroborates the fields and adds lifecycle meaning to 'status', which is a marginal gain over the schema baseline of 3.

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

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

The description names a specific verb (Change) and resource (top-level trip fields) and enumerates the concrete fields affected: rename, cover photo, lifecycle status. It also explicitly distinguishes this tool from siblings by stating it 'Does not touch variants, destinations or options'.

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 provides clear context for the lifecycle transition ('planning -> ready once the plan is settled, finished or cancelled afterwards') and implicitly routes field-specific edits to other tools via the exclusion clause. It lacks an explicit 'use this when / use X instead' statement, but the implied boundaries are strong.

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

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

Annotations already declare this is a non-destructive, idempotent mutation, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it states the tool returns the variant as it now stands and advises confirming the change via the response rather than assuming success.

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 mutation surface followed by the return-value guidance. No filler, 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 no output schema, the description usefully explains what comes back and that the caller should verify it, and the schema fully documents the nested inputs. It omits any note on permissions or the participants-replacement caveat (which lives only in the schema), so it is strong but not exhaustive.

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 nested data object already documents each field, including the exact-vs-flexi date structures and the replace-whole-structure semantics for participants. The description's 'exact dates or a flexible window' phrasing mirrors what the schema already states, so it adds little beyond the 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 and enumerates the exact editable fields (name, dates, notes, participants), so an agent knows precisely what it mutates. It does not, however, distinguish itself from close siblings like create_variant, duplicate_variant, or select_variant, leaving that inference to the agent.

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

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

Usage is implied by the field list ('Rename a variant, change its dates...'), but there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as duplicate_variant or select_variant. The only operative advice is to read the response to confirm the change.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds useful context beyond that: it is an authentication/identity check and a safeguard before mutations, which is not derivable from 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 no filler. The purpose is front-loaded and the usage guidance 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?

For a zero-parameter identity tool this is nearly complete. The only minor gap is that it never hints at what the response contains (account name/id/email), and no output schema exists to cover that.

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

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

Zero parameters, so there is nothing for the description to document; the baseline of 4 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: checking which MyNextAdventure account the current API key belongs to. No sibling tool performs identity resolution, so the agent can distinguish it 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 two concrete usage conditions: verifying the connection is authenticated, and confirming whose trips are about to be edited. Clear context, though it doesn't state when this tool is unnecessary or name any alternative (none really exists here).

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