GeoTok Trips

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: results are user-saved from short-form video platforms, are 'verified', and include the dish to order. It omits return-volume and pagination behavior, which is a minor gap given the limit parameter's default of 8 and cap of 15.

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: the first front-loads the resource and data source, the second gives the usage hook. There is no filler, though the em-dash aside plus the provenance list makes the opening sentence dense enough to require a careful read.

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

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

With no output schema, the description carries the burden of explaining what comes back, and it does so ('verified places with the dish to order'). Combined with annotations covering the safety profile, an agent has enough to call it correctly; only result-count expectations are left unstated.

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

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

Schema coverage is only 33%: 'craving' is documented in the schema, but 'city' and 'limit' have no schema descriptions. The description implies the city scoping ('in a city') and the dish-oriented nature of the query, which partially compensates, but it never mentions the limit parameter or its 1–15 range and default, leaving that meaning to the schema alone.

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

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

The description names a concrete resource set (restaurants, cafés and bars in a city) and its provenance (places saved from TikTok, Instagram and YouTube food videos on GeoTok), so an agent knows exactly what kind of result comes back. It does not explicitly contrast itself with siblings like find_things_to_do, but the food/venue domain makes the distinction inferable.

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 quoted example 'where should I eat in X' gives a clear triggering context for when to call this tool. It stops short of naming exclusions or pointing to alternative sibling tools for adjacent needs (activities, hotels, flights), so routing is implied rather than spelled out.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond them — results include coordinates and booking links — but says nothing about result count, ranking, pagination or rate limits for a read tool whose output shape is otherwise undocumented (no output schema).

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

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

A single dense sentence with no filler, front-loading the result categories before the secondary detail about coordinates and booking links. Nothing repeats the tool name or title.

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

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

For a simple two-parameter read tool with rich annotations and no output schema, the description covers the return payload well, but the required city parameter's meaning and the interests filter's effect remain unaddressed, which is a real gap given the low schema coverage.

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

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

Schema coverage is only 50%: 'interests' is documented in the schema, but the required 'city' parameter has no description there. The description only implicitly touches city ('in a city') and never mentions the optional interests filter or how terms like 'kids' or 'nightlife' shape results, so it does not compensate for the coverage gap.

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?

Concrete resource list: 'Top sights, museums, parks, viewpoints and other attractions in a city' states exactly what the tool returns, and the mention of coordinates plus tour/ticket booking links makes it distinguishable from find_food_spots or search_hotels by content. It never explicitly contrasts itself with those siblings, so it stops short of a 5.

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

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

No explicit when-to-use or when-not-to-use statement; the agent must infer from the attraction vocabulary that this is the sightseeing branch rather than the food, flights or plan_trip branches. Usage is implied by the content but never stated as 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 read-only, idempotent, open-world, non-destructive behavior, but the description adds genuinely new context: fares are recently-seen cached prices rather than live quotes, and hotel prices are excluded so the per-night figure is residual budget. That staleness caveat is exactly the kind of disclosure an agent needs before presenting results as bookable. It stops short of noting rate limits or result pagination.

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?

It opens with the motivating query, then lists what is returned, then closes with the two caveats that matter most. Dense but front-loaded and free of filler; the final two clauses could be tightened slightly but every sentence carries signal.

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 9-parameter tool with no output schema, the description usefully enumerates the response contents (fare, budget left per night, booking links, count of verified food spots). Only the filtering knobs – limit and direct_only – go unmentioned, which is a minor gap against an otherwise complete picture.

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 description clarifies the semantics of budget (total for flights plus hotel, all travellers) and how nights/travellers feed the derived per-night figure. With schema coverage at only 56%, the undocumented parameters (limit, direct_only, currency interplay with origin) get no additional explanation in the description, so it only partly compensates.

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 finds destinations whose cached round-trip fare fits a budget – and anchors it with a realistic user query ("€500, flying from Madrid, anywhere is fine"). That framing implicitly separates it from search_flights/search_hotels, which require a known destination, though no sibling is named explicitly.

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

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

The quoted example conveys the intended situation (open-ended budget-first inspiration rather than a targeted search), and the month/depart_date fields hint at date flexibility. There is no explicit when-not guidance or named alternative, so selection between this and plan_trip or search_flights is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered without description help. The description adds that results bundle coordinates and booking links from multiple sources, which is useful, but it says nothing about latency, result limits, or whether booking links carry commercial terms.

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

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

A single front-loaded sentence that states the payoff first and then lists outputs, with no filler or restated name/title. 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 multi-source aggregator with no output schema, the description does sketch the return payload (hotels, sights, food, booking links), which is the right instinct. However, with five parameters at 20% schema coverage and no output schema, an agent still lacks the parameter guidance and response-shape detail needed to call it confidently.

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% — check_in is the sole documented parameter, and the description adds no parameter meaning whatsoever. Nothing explains what values 'interests' accepts, how 'days' interacts with the returned itinerary length (default 3, max 14), or how 'travellers' affects hotel options, leaving the description to compensate for a real gap that it ignores.

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 concrete deliverable (a day-by-day itinerary) and enumerates its contents: hotel options, sights, food spots with coordinates, and booking links. The phrase 'in one call' implicitly distinguishes it from the single-purpose siblings (find_food_spots, search_hotels), though it never names them 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 only implied: an agent can infer this is the aggregator to reach for when a full itinerary is wanted instead of several individual find_* calls. There is no explicit when-to-use statement, no exclusion of cases where a targeted search would be cheaper, and no prerequisites such as a required city.

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, openWorld=true, idempotent=false and destructive=false, so the description's job is to add context — and it does: it discloses that a public link is created (an external exposure the annotations don't convey), that missing coordinates trigger a name-based lookup, and that personal details are prohibited. It stops short of saying what happens on a repeat save, which matters given idempotentHint=false.

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

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

A single dense paragraph that front-loads the action and result, then the item rules, then the privacy constraint. Every sentence carries information, though the run-on structure makes the item-optionality clause slightly harder to scan than a short list would be.

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

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

With no output schema, the description does state the key return value (a public link) and the downstream effect of opening it. For a three-parameter write tool with nested items, the remaining gap is the response shape and duplicate-save behavior, which is a modest omission rather than a blocking one.

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

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

Schema coverage is only 33%, so the description must compensate, and it does for the item fields: name is required, lat/lng, address, kind, note and day are optional, and items without coordinates are geocoded by name. It does not explain trip_name or city, nor the 40-item cap or the day 1-30 range, leaving some gaps.

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 ('Save a trip ... to GeoTok') plus the concrete outcome (public link, places pinned on the user's map, proximity reminders). This clearly separates it from the sibling search/plan tools, which retrieve or draft rather than persist a shareable artifact.

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 outcome (you save a trip once you have places to keep), but there is no explicit when-to-use or when-not guidance and no mention of the obvious alternative, plan_trip. An agent must infer that this is the persistence step after planning.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive, so the safety bar is lower. The description adds genuinely useful behavior beyond that: it returns airport codes, booking comparison links to Aviasales/Kiwi/Skyscanner/Google Flights, and recently seen cheapest fares, and it warns that quoted prices fluctuate and the authoritative live price is on the booking site.

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 what the tool does, followed by what it returns and the key caveat about live pricing. No wasted wording.

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

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

With no output schema, the description must explain return values, and it does: airport codes, booking links, and cheapest-seen fares. Combined with 83% schema coverage and rich annotations, this is nearly complete, only missing explicit one-way/round-trip and passenger-count framing.

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 83%, so the schema itself documents origin, destination, dates, currency, and adults well. The description adds little parameter-level meaning beyond "for given dates" and does not elaborate on currency, passenger count, or one-way behavior — baseline 3 is appropriate 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?

The description opens with a specific verb and resource: "Find flights between two cities or airports for given dates." The resource (flights) is clearly distinct from siblings like search_hotels and search_transfers, though it does not explicitly name a sibling it displaces.

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 spelled out — an agent can infer this is the tool for flight lookups, and the note that prices change and live fares live on the booking site gives useful context about the results' nature. However, there is no explicit when-to-use/when-not guidance, no mention of one-way vs round-trip handling beyond what the schema implies, and no routing to 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the bar is lower; the description still adds real value by disclosing what comes back (addresses, coordinates, booking links prefilled with the dates) and the prices omission. It does not cover result-count limits or how open-world lookups behave, which keeps it from a 5.

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

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

Two sentences, zero filler, with the core capability and the return payload front-loaded and the price caveat placed last as a qualifier. 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 no output schema, the description properly should describe returns, and it does (addresses, coordinates, booking links with dates prefilled). It stays silent on result volume and on what 'style' and 'adults' actually change in the results, which a six-parameter tool could reasonably spell out.

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 67%, and the description reinforces only city, near (area or landmark), and the dates' role in prefilling booking links. It says nothing about 'style' (the one enum) or 'adults', leaving those to the schema alone. This is adequate given partial schema documentation but adds limited meaning beyond it.

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

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

States a specific verb and resource ('Find hotels in a city') plus the return payload (addresses, map coordinates, prefilled booking links). The resource is unambiguously distinct from siblings like search_flights, find_food_spots, and search_transfers, so an agent can select it without opening the schema.

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

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

The optional 'near' clause signals the near-a-landmark use case, and 'Does not show prices — the booking links do' draws a clear boundary telling the agent not to use this tool to answer price questions. There is no explicit statement of when to prefer another tool, but no sibling competes for the same hotel search, so the gap is minor.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine value beyond that by disclosing what the tool returns — resolved endpoints, straight-line distance, directions links, and a pre-booking link — which matters since there is no output schema.

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

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

A single sentence with the core action front-loaded and the return contents following. No filler or redundancy.

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

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

With no output schema, the description usefully summarizes the return payload, which is the main completeness risk here. Minor gaps remain — it doesn't say how date or passengers influence results — but nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 80%, so the schema already documents most parameters. The description adds only the notion that both ends are 'resolved', which hints at geocoding behavior but gives no format or constraint detail beyond the schema. 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 and resource ('Get from A to B on arrival — e.g. airport to hotel') and enumerates the concrete outputs (distance, transit/driving links, pre-booking link). This clearly separates it from siblings like search_flights and search_hotels, which book the legs rather than the ground transfer.

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 'on arrival' framing implies the use case (getting from an arrival point to lodging), but there is no explicit when-to-use vs. when-not guidance and no named alternative among the siblings. Usage is inferable rather than stated.

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