OohWeGo

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so credit here goes to extra context: adding to a lane affects only the people in it, times are local to the place, and flights/transports carry a separate arrival point with its own local time. That is real behavioral detail beyond the annotations.

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

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

Three sentences, front-loaded with the core action and the lane caveat, and each sentence carries distinct information about scoping, time zones, and multi-leg trips. It's dense and slightly run-on, but nothing is wasted.

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

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

With 15 parameters, annotations, and an output schema, the description covers the non-obvious parts: lane targeting, local-time semantics, and arrival places. Minor gaps remain — no mention of how date/endDate interact for multi-day stays, or of validation behavior.

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 80%, so the baseline is 3, but the description adds provenance and semantics the schema doesn't: laneId comes from get_trip's splits, placeProviderId from search_places, and that place's time zone is used unless overridden. The endPlaceProviderId/endPlace pairing for flights is also explained.

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 uses the specific verb 'Adds' with the resource 'activity' and immediately scopes it: the shared plan by default, or a lane for a subset of people. That lane/whole-plan distinction also separates it from update_activity and move_activity, which operate on an existing activity.

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 routes the agent to other tools for the data it needs — laneId 'from get_trip's splits', placeProviderId 'from search_places' — and explains when to leave laneId out ('for everyone'). It doesn't state when to prefer this over update_activity or a list/wishlist tool, but the intent is clear.

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

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

Annotations already declare a non-destructive, closed-world write, so the description doesn't need to restate that. It adds real behavioral context instead: sensible defaults for payer, date and currency, and the invariant that exact shares must add up to the total, which tells the agent how the record will be populated when fields are omitted.

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

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

Front-loaded with a vivid example, then dense but purposeful sentences covering amount format, shares semantics, and defaults. Slightly long with some overlap between description and schema, but 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?

With 10 parameters, an output schema, and annotations present, the description covers the tricky parts (amount units, share splitting, defaults) well. It never mentions the category or notes fields, which is a minor gap given the schema documents them.

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 80%, so the schema already explains amount units, method enum, paidBy/paidOn defaults and share amounts. The description adds a useful cross-tool reference ('person id from get_trip') and reiterates the equal-vs-exact behavior, but largely mirrors what the schema documents, so baseline 3 is appropriate.

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

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

States a specific verb ('Records') and resource ('something someone paid for on the trip') with a concrete example ('Add the A$60 ramen Zayd paid for the three of us'). The resource is clearly distinct from siblings like add_activity or add_list_item, though it never addresses how it relates to the potentially overlapping create_split.

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 example and defaults make the intended usage context inferable ('paid by the user, today, in the trip's currency, unless said otherwise'), but there is no explicit when-to-use/when-not guidance and no pointer to an alternative such as create_split for different splitting scenarios.

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, closed-world mutation, so the safety profile is covered. The description adds useful semantics about optional linkages (assignees, due date, activity), but says nothing about failure modes (e.g., invalid listId/tripId mismatch) or whether adding an item triggers notifications.

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

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

A single front-loaded sentence with zero filler. The stacked parenthetical is dense but every clause carries information; only the example wording is slightly redundant.

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

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

The output schema covers return values and annotations cover the mutation profile, so those gaps don't count against it. However, for a 7-parameter mutation at 43% schema coverage, the description should clarify title/notes and the activityId linkage, which it does not.

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

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

Schema coverage is only 43%, and title, notes, and activityId have no schema description at all. The description partly compensates by explaining assignees, dueDate, and activityId as optional linkages, but leaves title/notes and the activityId relationship entirely 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 and resource ("Adds an item ... to one of the trip's lists") and concretizes the item types with examples (to-do, packing, activity booking). It implies separation from list-level siblings (create_list, add_to_wishlist) but never names an alternative to distinguish against.

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 parenthetical examples hint at when this tool applies rather than a sibling such as add_activity, but no explicit when/when-not rule or prerequisite is given. An agent must infer from the examples and from the schema's "from get_lists" hints.

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

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

Annotations already establish this is a non-destructive write in a closed world, so the bar is lower. The description still adds real behavioral context beyond them: the category is inferred from the place unless explicitly supplied, and a note carries the rationale. It stops short of disclosing duplicate handling (re-pinning an existing place) or failure modes, keeping it out of 5 territory.

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

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

Two short sentences, no filler. The core action and source tool come first, followed by the optionality/derivation rule, which lets an agent stop reading early if it only needs the basics.

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

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

With an output schema available and annotations covering safety, the description supplies what remains: the source of the place identifier, the purpose of the optional note, and the default category behavior. Nothing essential for a correct invocation is missing, though duplicate-handling behavior would be a nice extra.

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 60%: tripId, placeProviderId and sourceUrl are documented, but note and category are not. The description compensates for exactly those gaps, explaining that note is "why" the place is being pinned and that category is derived from the place unless explicitly provided (matching the enum-override pattern).

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 ("Pins a place ... to the trip's wishlist") and identifies the upstream source tool (search_places), which separates it from get_wishlist, search_places, and planners like add_activity/add_list_item. The collaborative intent ("for the group to vote on") further disambiguates it from the other add_* 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?

Usage is implied rather than stated: placeProviderId must come from search_places, and the "group to vote on" framing hints this is a pre-planning, aspirational step before add_activity. However, there is no explicit when-to-use/when-not guidance versus add_activity or add_list_item, and no prerequisite statement about trip membership.

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, closed-world mutation, so the safety profile is covered. The description adds real value by disclosing the visibility model (shared vs. personal, only the user sees it), but omits whether names must be unique, whether lists can be reordered later, or any 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?

A single front-loaded sentence with no filler; the operation leads and the visibility distinction follows immediately. Every clause carries information an agent would otherwise have to guess.

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

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

An output schema exists, so return values need not be explained, and annotations carry the mutation profile. Still, for a 5-parameter creation tool with only 20% schema documentation, the description is thin on the optional appearance parameters and on any constraints around list creation.

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 20% (tripId alone is documented), so the description is expected to compensate. It does explain the 'personal' flag's effect in domain terms, but leaves icon, color, and name constraints entirely to the schema, where they too are undescribed.

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

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

Specific verb + resource ('Adds a list to the trip') with the visibility scope folded in, so an agent can distinguish it from get_lists or add_list_item. It stops short of naming any sibling explicitly, so differentiation is inferential rather than stated.

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

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

The sentence implies the operation (create a list on a trip) but gives no when-to-use guidance, no prerequisites such as existing trip membership or tripId sourcing, and no pointer to alternatives like add_list_item. Nothing tells an agent when this is the wrong tool.

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

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

The annotations already declare that this is a write operation that is neither read-only nor destructive. The description adds substantive semantics beyond that: the 3-lane cap, that lanes reconvene, and that people in no lane continue with the shared plan. It doesn't explain what happens to existing plans in the time window or what the required start/end times constrain.

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 what a split is, then the mechanics. 'For a while' is the only vague phrase; the time window is implied rather than stated, but nothing is wasted.

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

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

An output schema exists, so return values needn't be explained, and annotations cover the safety profile. The description supplies the conceptual model and the follow-up step an agent needs; only the time-window semantics of the required date/startTime/endTime are left implicit.

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

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

Schema description coverage is 86%, so the schema already documents tripId, date, times, timeZone and the lane/people structure. The description reinforces the lane shape (name + people) but adds nothing about the time-window parameters or the optional endDate/timeZone, so its value over the schema is marginal.

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 concrete verb and resource: it splits the group into up to 3 lanes that do different things for a while and then reconvene. It also distinguishes the tool from the sibling add_activity by naming it as the required follow-up step for populating each lane.

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

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

It gives a clear workflow: create the split with named lanes and their people, then add each lane's activities with add_activity and its laneId. It doesn't state when NOT to use this, for example, a single-activity or single-destination plan, so it falls short of explicit alternatives.

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

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

Annotations already establish read-only and non-destructive behavior. The description adds substantial domain context beyond annotations: amount formatting as decimal strings in major units, currency context, that planned expenses are unpaid activity costs, and that hidden surprises should not be guessed at.

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 returned data and primary use cases, followed by compact formatting and edge-case notes. Every sentence adds useful information without 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?

Given the output schema, annotations, and single fully documented parameter, the description supplies the remaining domain semantics an agent needs. It covers return content, amount format, planned expenses, and the surprise edge case.

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?

There is only one parameter, tripId, and schema coverage is 100%; the schema already documents it as coming from list_trips. The description does not add further parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description precisely states the resource and outputs: a trip’s expenses, everyone’s balances, and the minimal set of settlement payments. It clearly supports “who owes whom?” and “what have we spent?” and is distinct from the sibling add_expense tool.

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 use-case triggers (“who owes whom?” or “what have we spent?”), which clearly signal when to call it. It does not name exclusions or alternatives such as add_expense, so it falls short of the highest bar.

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 read-only, closed-world, non-destructive call, so the burden is low. The description earns credit for disclosing the result composition beyond the schema: lists come back with their items, and visibility is scoped so shared lists appear alongside the caller's private lists that only they can see.

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

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

One front-loaded sentence that puts the resource first and the visibility caveat second. No waste, though it is terse enough that a key usage hint is absent.

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

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

An output schema exists, so return-shape explanation is not required, and visibility scoping is covered. What is missing for a list-fetch tool is practical context such as ordering, whether empty lists are returned, or how the returned list ids feed add_list_item/update_list_item.

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 100% schema coverage on the single tripId parameter, the schema already documents the format and even the source ('from list_trips'). The description adds nothing about the parameter, 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 the resource concretely — the trip's lists (packing, to-dos) together with their items — so an agent knows exactly what comes back. It does not differentiate from siblings like create_list or add_list_item, and the verb is implied rather than stated, but the read intent is obvious.

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

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

There is no guidance on when to call this versus get_trip, get_plan, or create_list, nor any note that it must be called before add_list_item (which needs a list id). The agent must infer usage entirely from the tool name.

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

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

Annotations already establish readOnly/destructive safety, but the description adds a genuine behavioral quirk: surprises render as "Surprise" with only times and the agent is told not to probe or guess. That is information an agent could not get from annotations or schema and directly prevents a misuse.

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

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

Three sentences with no filler: return shape first, default scoping second, surprise caveat last. Each sentence carries distinct decision-relevant 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?

An output schema exists, annotations cover the safety profile, and the description covers the non-obvious case (surprise activities) that the schema cannot express. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by explaining the semantic consequence of `person` (defaults to the current user's own plan) rather than just repeating the parameter's type. It does not add format details, but the schema already supplies those.

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 exactly what is returned: one person's ordered activities on a trip, including lane-specific activities where the group splits. It also clarifies whose plan is fetched by default, so an agent knows the resource and scope without opening the schema.

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

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

Clearly defines the default case ('The user's own plan unless `person` is given'), which tells the agent when to pass the optional parameter. It does not name alternatives such as get_trip for trip-level structure, so routing guidance is context-complete but not 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The description does add genuine domain context — that member/guest ids are the referents used by plans, lanes and to-dos, and that people in no lane follow the shared plan — but says nothing about failure behavior (unknown tripId) or result size.

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 that front-load the entity and its contents, with jargon (splits, lanes) defined inline rather than assumed. The trailing sentence about people in no lane is useful domain semantics rather than filler, though the noun-phrase framing makes it read more like a data glossary than a tool 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?

With an output schema present, the description need not enumerate return fields, and it correctly focuses on the domain relationships an agent cannot infer from the schema. Nothing critical is missing for a read-only single-entity fetch; only error handling for an invalid tripId is unaddressed, which is minor.

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

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

Schema description coverage is 100%: tripId is typed as uuid with a format pattern and documented as coming from list_trips. The description adds no parameter-level information beyond that, so the baseline 3 applies — the schema, not the prose, does the work here.

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 the resource's distinctive contents — people (members and guests) and splits with lanes — which lets an agent distinguish it from get_plan, get_lists and list_trips, whose scopes are different slices of the same trip. It never states a verb ('retrieves a single trip by id'); the read intent is carried by the name and title rather than the description text.

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

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

Usage is only implied: one required tripId and the notion of getting one trip's detail vs the list_trips enumeration the schema points at. There is no explicit 'use this when you need X' or 'do not use this for Y', and no sibling is named in the description even though list_trips, get_plan and get_lists overlap conceptually.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and closed-world scope, so the safety profile is covered. The description adds the composition of the result (votes, who's in, planned activity) but says nothing about ordering, empty wishlists, or access requirements; with an output schema present, this is modest added value.

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

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

A single front-loaded sentence that enumerates the returned fields with no filler. Slightly dense phrasing ('the activity each was planned as, if any') but every clause carries information.

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

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

For a read-only, single-parameter list retrieval with an output schema, the description is largely sufficient: it conveys what a wishlist entry contains and that membership/planning may be absent. It omits ordering and pagination, which matters less here given the output schema.

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

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

Only one parameter, and the schema documents it at 100% coverage with the helpful note that tripId comes from list_trips. The description adds no semantics about tripId beyond what the schema states, 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 names the concrete resource — places the group pinned as candidate activities — and enumerates its payload (votes, participants, planned activity). It is clear what data comes back, but it never distinguishes this tool from the sibling get_wishlist_fits, whose purpose an agent must guess.

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

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

There is no explicit statement of when to call this versus alternatives, no prerequisites, and no mention of get_wishlist_fits or add_to_wishlist as the related read/write counterparts. Usage is only inferable from the tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real behavioral context: results exclude already-planned places, and default scope is the calling user's plan rather than another person's. It says nothing about cost, latency, or result size, which matters for a per-item computation across the wishlist.

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 result shape and closed with the recommended action. The first sentence is dense and enumerates return fields that the output schema already covers, but nothing is padded or repetitive in a harmful way.

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

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

An output schema exists, so return values need not be explained, yet the description frames them helpfully. Scope rules and the purpose of the call are both covered. Minor gap: no note on what happens when a wishlist place has no feasible fit, which is the interesting edge case 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 meaning beyond the schema by stating the default behavior of `person`: the user's own plan is used when it is omitted. That is exactly the semantic an agent needs and it is not in the schema, which only says the value comes from get_trip's people.

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 resource (wishlist places not yet planned) and a specific computation (where each fits: day, nearest activity, travel time, free time). That is far more than a restatement of the name. It doesn't explicitly name a sibling to contrast with (e.g. get_wishlist vs get_plan), so the differentiation is implicit rather than stated.

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

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

'Use it to suggest what to add, and when' gives a clear usage context, and 'The user's plan unless `person` is given' clarifies default scoping. There is no guidance on when not to use it, no mention of alternatives such as get_wishlist or get_plan, and no prerequisites.

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, non-destructive, closed-world, so the safety profile is covered. The description adds real context beyond that: result ordering (newest first) and what each entry contains (dates, the user's role), though it says nothing about result volume or whether archived/inactive trips are included.

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

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

A single sentence with zero filler; the scope and ordering are front-loaded before the per-trip contents.

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

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

An output schema exists, so return-value explanation is unnecessary, and with zero parameters the input side is fully covered. The only real gap is whether the list is filtered or paginated, which would matter for an agent planning what it can rely 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?

The tool takes zero parameters, so there are no parameter semantics to explain; the baseline applies. Nothing in the description misrepresents the input contract.

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

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

Specific verb (lists) plus resource (trips), with scope ('the trips the user is on'), ordering ('newest first'), and returned content ('dates and the user's role'). The plural listing is clearly distinguishable from the singular sibling get_trip.

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 only implied: an agent can infer it should call this to enumerate the current user's trips, but the description never names alternatives such as get_trip for a single trip's detail, nor states when not to use it.

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 a non-read-only but non-destructive write, and the description adds real behavioral detail beyond them: default ordering is last on the target day unless index places it, and a null date unschedules the activity. It does not cover permissions, effects on the positions of other activities, or what a partial move (date same, lane changed) does.

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

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

A single tight sentence that front-loads the move and then the ordering default; every clause carries information. The stacked parentheticals make it slightly dense to scan but nothing is wasted.

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

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

For a 5-param mutation with annotations and an output schema, the description covers the non-obvious semantics (unset date, index default, lane vs shared plan) that an agent would otherwise have to guess. Remaining unknowns, such as reindexing side effects, are minor.

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

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

With only 40% schema coverage, the description compensates well for the ambiguous params: it defines index semantics (0 = first, default = last), laneId semantics (lane vs shared plan vs omitted = unchanged), and date's null meaning. tripId and activityId carry no description-level clarification, but tripId already notes its source (list_trips) in the schema.

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

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

States a specific verb and resource (move an activity) plus the exact scope of the change: another day, null for unscheduled, into a lane or back to the shared plan. This clearly separates it from update_activity (field edits) and add_activity (creation) without needing 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?

Usage context is implied by the described capability (rescheduling, lane reassignment), but there is no explicit statement of when to prefer this over update_activity or remove_activity, and no prerequisites or failure conditions mentioned.

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 mark this as destructive and not read-only, and the description adds important behavioral details beyond them: it affects everyone on the trip, removes associated routes, is irreversible, and requires user confirmation. This is exactly the kind of context an agent needs for a destructive operation.

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

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

Two short sentences, with the destructive scope and irreversibility front-loaded before the confirmation requirement. Every sentence earns its place.

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

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

The description covers the critical behavioral context for a destructive delete, and an output schema exists to explain return values. The main remaining gap is the undocumented activityId parameter, but otherwise an agent has enough information to invoke the tool 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?

Only tripId has a schema description ("from list_trips"); activityId is undocumented in the schema, and the tool description does not clarify its meaning or source. With 50% schema description coverage, the description should compensate for the missing parameter guidance but does not.

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

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

The description uses a specific verb and resource: "Deletes an activity." It also states the scope ("from the trip for everyone") and cascade behavior ("with its routes"), which clearly distinguishes it from update_activity, move_activity, and remove_list_item.

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 by warning that the action cannot be undone and instructing the agent to confirm with the user first. It does not explicitly name alternatives such as update_activity for non-deletion changes, but the deletion context is clear.

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 readOnlyHint=false, so the baseline is covered. The description adds genuinely useful context beyond that: the action is irreversible and requires user confirmation, which shapes agent behavior on a mutating call.

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

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

Two short sentences with zero waste. The irreversible nature and the confirmation requirement are front-loaded where an agent will act on them before calling.

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

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

An output schema and rich annotations reduce what the description must carry, and the destructive/irreversible framing is present. However, with two of three parameters undocumented and no explanation of how tripId, listId, and itemId relate, an agent must infer the addressing scheme.

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 only 33% — only tripId is documented ('from list_trips'), while listId and itemId carry no explanation anywhere. The description mentions no parameters at all and does not compensate for the coverage gap, leaving the containment hierarchy (trip > list > item) 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 (deletes) and resource (item from a list), which cleanly separates it from add_list_item and update_list_item in the sibling set. It never explicitly names those siblings, so it falls short of a 5.

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

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

The description gives an operational rule ('confirm with the user first') but no guidance on when to prefer this over update_list_item or how it relates to removing a whole list. Usage is implied by the tool name rather than explained.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely non-annotated behavior: results are geographically biased to trip destinations and ranked nearest-first, and results expose a providerId usable for chaining. It does not mention result limits or freshness, keeping it below a 5.

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

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

Two tight sentences with no filler: the first front-loads what is found and how results are scoped, the second covers the follow-up action. 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 two-parameter, read-only search with a full output schema, the description covers purpose, geographic bias, ranking, and how to consume the result via providerId. Return-format details are legitimately left to the output schema, so 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 description coverage is 100%, so the baseline is 3; the description earns an extra point by clarifying that tripId drives the geographic scoping and ranking ('around the trip's destinations and nearest the trip first') rather than being an arbitrary filter. It also frames 'query' as a place-name search, complementing the schema's example.

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 ('Finds real places') and enumerates concrete entity types (restaurants, sights, hotels, addresses), so the agent knows exactly what comes back. It also names the scoping/ranking behavior ('around the trip's destinations and nearest the trip first'), which distinguishes it from any of the write-oriented siblings.

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

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

The second sentence gives a clear downstream context: use a result's providerId to add an activity or pin to the wishlist, which implicitly tells the agent this search is the lookup step preceding add_activity/add_to_wishlist. It stops short of naming those siblings or stating exclusions (e.g., when not to search vs. browse the wishlist), so it is clear context without explicit alternatives.

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

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

Adds substantial behavior beyond the annotations: only provided fields change, null clears a field, concurrent changes are preserved unless they touch the same field, and hidden/surprise items cannot be changed. This is exactly the kind of mutation and conflict behavior an agent needs before calling the tool.

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, front-loaded with purpose and partial-update semantics, then the sibling alternative, concurrency behavior, and the hidden-item restriction. No sentence 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?

For a mutation tool with an output schema and safety annotations, the description covers purpose, partial update behavior, conflict handling, and a key restriction. It is not fully complete on field-level parameter semantics, but the core invocation behavior is adequately described.

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 only 20% across 15 parameters, so the description must compensate. It usefully explains partial-update and null-clearing semantics, but does not clarify the many field-level parameters such as timeZone, endTimeZone, provider IDs, or end fields beyond what their sparse schema entries say.

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: changes an activity's details, with precise partial-update semantics. It explicitly routes movement/reordering to move_activity, so the agent can distinguish it from the most confusable sibling without opening schemas.

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

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

Gives a clear condition for using update_activity (changing details) and names move_activity as the alternative for moving to another day/lane or reordering. It does not discuss when to prefer add_activity or remove_activity, but the alternative for the main ambiguity is explicit.

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=false and destructive=false, so the description's real contribution is behavioral: partial-update semantics ('only the fields given change') and that null clears a field. These are non-obvious traits an agent would otherwise get wrong, though write-permission needs and assignee-replacement behavior are unstated.

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

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

A single tight sentence with the toggle behavior front-loaded and the null-clearing caveat trailing. Zero wasted words.

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

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

An output schema exists so return values needn't be described. For a mutation of this size, the description covers the key surprises (partial update, null clears), leaving only assignee-list semantics as a notable 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 coverage is very low (13%), so the description must compensate, and it does partially: it explains `done` toggling and null-clearing. But it leaves `assignees` (whether it replaces or merges), `dueDate`, `title`, and `notes` field semantics unaddressed beyond the schema's format hints.

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: toggling `done` on a list item or changing its details. It's clearly a mutation of an existing item, distinguishing it from `add_list_item`/`remove_list_item`, though it doesn't name those siblings explicitly.

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

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

Usage is implied by the examples (tick off/on, edit details) but there is no explicit guidance on when to use this versus `add_list_item` or `remove_list_item`, nor any prerequisites or exclusions.

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