Gingerguide: European city walking tours

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value by disclosing the data basis ('based on the sight catalog only') and the exclusion boundary, though it says nothing about result limits or failure behavior for invalid city ids.

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

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

Two sentences, front-loaded with the action and scope, followed by the output inventory and the exclusion. Dense but every clause carries information given there is no output 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 compensates by enumerating exactly what the response contains (sight counts, days needed, strongest interests, indoor share, winner per interest, distances). An agent knows both how to call it and what it will get back.

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 that by explaining that interests/periods are used to determine 'which city is stronger' and that trip_days drives how much of each city fits. It does not spell out the 2-4 city bound in prose, but the schema's minItems/maxItems already does.

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

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

States a specific verb (compare) and resource (two to four covered cities) with concrete examples of the question it answers. Clearly distinct from siblings like search_cities or get_city_guide because it is explicitly a side-by-side multi-city comparison.

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?

Examples ('Porto or Lisbon?') plus the explicit exclusion list ('not prices, weather, nightlife or beaches') tell the agent when this is and isn't the right tool. It stops short of naming a specific sibling to use for the excluded topics, which is the only gap.

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, non-destructive, closed-world behavior, and the description adds genuinely new operational context: the ranking criteria (distance, fit with interests/periods, fame), the straight-line distance metric, the deliberate omission of travel times with the reason, and the coverage constraint ('Only covered cities are listed'). These are exactly the caveats an agent needs to interpret results correctly.

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

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

Front-loaded with the resource and scope, followed by example queries, then ranking/metric caveats. Four sentences, none redundant, and the limitations are placed after the core definition rather than 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?

With no output schema, the description still conveys what comes back ('lists what to see there in one day', ranked) and flags the two things that could mislead an agent: straight-line distances without travel times, and the covered-cities-only restriction. 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 description coverage is 86%, so the schema already carries the parameter burden and baseline is 3. The description reinforces the role of interests and periods in ranking and clarifies that distances are straight-line (relevant to max_distance_km) and that the output is a one-day selection (relevant to hours_on_site), but adds no format or range detail beyond that.

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 ('Day trips from a base city to other covered cities and towns nearby') and pins the scope to destination-level cities, which separates it from attraction-level siblings like find_nearby_attractions. Example queries ('day trips from Florence', 'a day trip from Munich for castles') make the intent unmistakable.

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 phrasings give clear situational context for when to reach for this tool, and 'from a base city' establishes the required anchor. It does not explicitly name alternatives (e.g. recommend_destinations or find_nearby_attractions) or state when not to use it, so routing between siblings still requires 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 read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuine value beyond them: results are ordered by walking time and an empty radius triggers a nearest-covered-city fallback rather than an empty result.

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

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

Two sentences, no filler, with the primary behavior front-loaded and the fallback edge case trailing. Every clause 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?

With no output schema, the description usefully describes the result ordering and the fallback case, and pace/language are covered by schema descriptions. Remaining gaps (limit behavior, how multiple interests combine) are minor for a radius-search tool.

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

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

Schema coverage is only 38% across 8 parameters. The description clarifies that lat/lng anchor the search, that interests/categories act as optional filters, and that radius is a hard cutoff, but it says nothing about limit, ordering ties, or how pace affects walking-time sort.

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 with its scope: sights nearest a lat/lng, sorted by walking time, filterable by interests/category. This clearly separates it from text-based siblings like search_attractions or recommend_attractions, 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 parenthetical 'for example the traveler's hotel or current position' hints at when to reach for it, and the fallback sentence implies it is safe to call in sparse areas. But there is no explicit when-to-use vs. recommend_attractions/search_attractions guidance and no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered structurally. The description adds that responses are content-rich (photo, map links, coordinates), hinting at payload size, but says nothing about behavior on an unknown id or about language fallback.

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, and the returned-field list is front-loaded before the id-provenance instruction. Nothing is repeated from 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 return-value burden and does so by enumerating the payload fields, which is the key thing an agent needs. It leaves minor gaps around failure modes and language fallback, but the tool is simple and read-only.

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 extra credit by adding provenance for attraction_id (it must come from search_attractions or get_city_guide), which is meaning the schema's example string does not convey. The language parameter is left entirely to the schema, which already handles it adequately.

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 resource and scope: 'Full details for one sight,' then enumerates exactly what comes back (long description, fact, photo, coordinates, map links, visit minutes, nearby sights with walking minutes). This clearly distinguishes it from list-style siblings like search_attractions or find_nearby_attractions.

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

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

Explicitly states the prerequisite: 'Use the attraction id from search_attractions or get_city_guide,' which routes the agent through the correct discovery flow. It does not state exclusions or when to prefer a sibling instead, so it falls short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by explaining that it returns counts plus exact accepted filter values, though it does not describe response structure in detail.

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 two tight sentences. It front-loads what the catalog overview contains and follows with the key usage instruction, with no wasted text.

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

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

With no parameters, no output schema, and annotations covering safety, the description supplies enough context: it names the catalog coverage dimensions and the exact filter-value use case. Nothing materially necessary for selecting or calling the tool 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?

This tool has zero parameters, so parameter semantics are inherently simple. The description appropriately does not invent parameter details and instead clarifies that the tool exposes filter values accepted by other tools.

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 the exact resource and contents: catalog coverage including city/sight/country counts, supported languages, and accepted filter values for other tools. It distinguishes itself from the sibling tools as a reference/overview tool rather than a search or recommendation 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 usage guidance: 'Call it first when unsure whether a city or filter value is supported.' This directly tells the agent when this tool is the right choice and ties its use to validation of inputs for the other tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds real behavioral context beyond that: the response shape (category, coordinates, visit minutes, one-line description) and an explicit warning that setting detail to "full" yields a large response—valuable for a read tool whose main behavior risk is response 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 sentences, front-loaded with the resource and its contents, then the detail/full caveat. No filler, and the response-size warning is placed where it will be read before the call.

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

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

With no output schema, the description carries the return-shape burden and does so by enumerating the guide's sections and sight fields. Annotations cover the safety profile. Minor gaps: it doesn't mention the language parameter's effect on returned names/descriptions, but that is documented in the schema, so nothing critical 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 67%; city_id and language are documented in the schema, but the `detail` enum has no description there. The description fills that gap precisely, explaining that "full" adds the long description of every sight and produces a large response, which the schema alone does not convey.

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 exactly what the tool retrieves (one city's guide) and enumerates the contents: overview, headline sights, lesser-known sights, and every sight with category, coordinates, visit minutes and a one-line description. That's a specific verb+resource with enough detail to separate it from get_attraction or compare_cities, 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 only usage instruction is 'Set detail to "full"... (large response)', which is parameter guidance rather than when-to-use guidance. There's no statement like 'use this for a full city overview, use get_attraction for a single sight' and no prerequisites (e.g. getting city_id from search_cities is only in the schema). Usage is implied by the content list.

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 a safe, idempotent read, so the description's added values are meaningful: every fact carries a source and check date, prices and opening hours are deliberately excluded, and partially-covered cities return an explicit 'not covered yet' answer rather than failing silently. It does not describe response shape or how many sections come back by default, but the annotations lower that bar.

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 content inventory comes first, then the sourcing and exclusion caveats, so the tool's payload is front-loaded. The lead sentence is a long run-on list, but nearly every clause (source/check date, no prices, partial coverage) adds 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?

For a read-only lookup with full schema coverage and no output schema, the description supplies what the structured fields cannot: what topics exist in practice, what is intentionally absent, provenance of the facts, and the partial-coverage failure mode. Only the default section behavior and language handling are left entirely to the schema, which is acceptable.

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 parameters are documented, so the baseline is 3. The description's topic enumeration loosely maps to the `topics` enum and its coverage caveat hints at `city_id` behavior, but it adds no format details (e.g. id form, language effect) beyond the schema.

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

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

The description enumerates the exact content returned (best months, crowd seasons, airport/station/port transfers with typical minutes, city passes, free sights, booking requirements, closing days, dress codes), which makes the resource unmistakable. It does not name or distinguish itself from near siblings like get_city_guide or get_attraction, leaving the boundary to be inferred.

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 through the topic list and the scope exclusion 'No prices or opening hours', which steers an agent elsewhere for those facts, but no alternative tool is named and there is no explicit when-to-use/when-not-to-use statement. The coverage caveat ('Researched for some cities only') is a data property, not selection 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 establish that this is a safe, read-only, idempotent, closed-world listing. The description adds useful context that results include city ids, but it does not describe ordering, nesting, or whether the list is paginated.

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 waste. It gives the resource and the key return content 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, read-only catalog-listing tool with rich annotations, the description is largely complete. It clarifies the return shape at a high level by mentioning city ids, though it could say more about result structure without an output schema.

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

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

The tool takes zero parameters, so parameter semantics come from the absence of inputs rather than the description. Baseline for zero-param tools is 4.

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

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

States a specific verb and resource: list covered countries. It also clarifies that each country includes city ids, distinguishing it from city-search siblings, though it does not explicitly name an alternative.

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 name and description: use it to enumerate available countries. However, it does not say when to prefer this over siblings like search_cities or get_catalog_overview, nor does it mention exclusions.

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

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

Annotations already declare readOnly, idempotent and non-destructive behaviour, so safety is covered. The description's added value is the disclosed output structure (day groupings, transit hops, leftover sights), which matters because there is no output schema. It says nothing about response size, cost, or how bounds like the 7-day cap affect results.

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 output contract first, an illustrative example second. No filler, no repetition of the title, and the most decision-relevant information is front-loaded.

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

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

For a 10-parameter generative planning tool with no output schema, the description does well on return shape but skips the mechanics that would help: how days, hours_per_day and start_weekday interact (closed-day avoidance is only in the schema), and what happens when a city has too few sights for the requested duration. Adequate but incomplete.

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 70% and enums are self-documenting, so the schema carries most of the load. The description names no parameter at all — not days, pace, style, interests, periods, start_weekday — so it adds nothing beyond the structured fields and leaves the three undocumented params relying solely on the schema.

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

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

The description states the resource concretely — a multi-day plan for a single city — and even sketches the output shape: days built around one or two walkable areas linked by a transit hop, ordered as walking routes, with leftover sights appended. That is enough to tell it apart from plan_walking_tour and recommend_attractions, 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 example query ("three days in Vienna for art and music lovers") implies the intended use case, but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as plan_walking_tour or get_city_guide. The agent must infer that this is the multi-day planning entry point.

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 bar is low, and the description still adds real behavior: sight selection logic, ordering to minimize walking, and per-stop output (walking minutes, time on site, clock times, Maps link). It omits the caveat found only in the schema that closing-day filtering is researched for some cities only, which is a meaningful reliability qualifier an agent should know.

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

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

Two sentences, front-loaded with the core capability and example, then a tightly packed behavior/output sentence. No filler or restatement of the title.

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

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

No output schema exists, and the description compensates by enumerating what each stop returns, which is the main missing piece. For a 15-parameter tool it still leaves the start-point alternatives and the optional-array parameters unaddressed, 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?

At 67% schema coverage the schema carries most weight; the description adds meaning for the driving inputs (interests, periods, style, time budget) but says nothing about start_lat/start_lng vs start_attraction_id vs start_time precedence, must_include/exclude_ids, or pace/setting/language.

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 ('Build an ordered self-guided walking route') plus resource and scope ('in one city that fits a time budget'), with a concrete example. The 'one city / on-foot' framing implicitly separates it from plan_trip_itinerary and recommend_attractions without needing to name them.

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 ('a two-hour historical walk in Rome') implies when this tool is the right pick, but there is no explicit when-not guidance and no named alternative (e.g. plan_trip_itinerary for multi-city/multi-day, recommend_attractions for unsequenced lists). 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.

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restating. The description adds non-annotation context: results are ranked personalized picks that each carry a stated rationale, which tells the agent what the response items look like. No mention of result volatility or how an unknown city_id is handled.

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 capability statement leads, the output promise follows, and the sibling diversion lands last where it is easiest to act on.

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 telling the agent what comes back, and 'each pick says why it was chosen' does that at the right level of detail. Combined with 78% schema coverage and full annotations, an agent has what it needs to call this 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 78%, so most parameters are already documented inline, and the description mostly restates them in prose (interests, periods, headline vs hidden gems, indoor/outdoor, time available). It adds no syntax or behavioral detail beyond the schema, and never mentions limit, exclude_ids or language.

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 (personalized attraction picks in one city) with the ranking inputs named: interests, historical periods, must-see vs hidden gems, indoor/outdoor, time budget. It also adds an output promise ('Each pick says why it was chosen') that separates it from a plain filtered search such as search_attractions.

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

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

Explicitly routes the agent away with 'Use plan_walking_tour instead when the traveler wants an ordered route', giving both the alternative and the selecting condition. It leaves the search_attractions vs recommend_attractions boundary implicit 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 establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-structured information: results are ranked by count of matching sights and each recommendation is accompanied by a rationale, which tells the agent what kind of output to expect beyond the 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?

Two compact sentences: purpose first, then examples, then ranking behavior. Every clause earns its place and the actionable content is front-loaded.

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

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

With five optional parameters and no output schema, the definition covers what an agent needs: what the tool returns conceptually and why results are ordered as they are. It stops short of stating behavior for an empty-criteria call or default-ranking fallback, a minor but real gap for an all-optional-parameter tool.

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

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

Schema description coverage is 80%, including enum value lists and per-field notes, so the schema does most of the work. The description reinforces the interests/periods duality and that matching sight counts drive ranking, but adds no format or interaction detail (e.g. how country interacts with periods, or what happens with zero criteria).

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 ('Suggest covered European cities') plus the scope constraint ('covered', i.e. catalog cities) and the ranking logic. The two example queries make the intended input shape concrete and distinguish it from search_cities or recommend_attractions without ambiguity.

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

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

Clear context for when to use it: open-ended, interest- or period-driven city suggestions, illustrated with two example phrasings. It never names an alternative or an exclusion (e.g. use search_cities for a known city name), so it falls short of explicit when-not guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds return content (name, description, coordinates, visit minutes, page URL), which is valuable given no output schema; it does not mention rates, limits, or defaults, so not a 5.

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

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

Three tight sentences: capability and scope first, concrete examples second, return shape last. Each sentence earns its place; only the example sentence is slightly tangential but it is high-value for intent matching.

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

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

For a 15-parameter search tool with no output schema, the description supplies both the filter catalogue and the return fields. Minor gaps (no mention of pagination via limit, sorting semantics, or language switching) keep it from a 5, but the schema covers those adequately.

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%, so the structured field already documents most parameters. The description meaningfully maps filter dimensions to intent ('category, interests, historical period, indoor/outdoor, visit length, free entry or distance from a point'), covering most of the 15; sort, limit, country, and language are left entirely 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?

The description uses a specific verb ('Search') and resource ('individual sights'), plus the scope ('all cities or within one city'). It enumerates the filter dimensions rather than restating the name, but does not explicitly distinguish it from siblings like recommend_attractions (interest-based) or find_nearby_attractions (distance), which overlap with 'distance from a point'.

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-case context is clear: 'five Byzantine sights in Istanbul, Gothic churches in Spain, or free things to do in Rome' shows exactly when to reach for it. No when-not invocations or alternative tools are named, however, so the agent must infer the boundaries against recommend_attractions and find_nearby_attractions.

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 openWorldHint=false, so safety is covered. The description adds useful behavior by naming the return payload (id, sight count, summary, guide URL), but says nothing about the 'limit' cap (max 200, default 25) or truncation semantics on large result sets.

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 is found, then what is returned, then the zero-argument case. 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 steps in to enumerate return fields, which is the key missing piece for a discovery tool. The only residual gap for a 4-parameter search tool is result-limit 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 75%, and the description compensates meaningfully: it explains that query matches name, country or region and works across the six languages, and that an omitted query lists everything. The 'limit' parameter remains undocumented in both schema and description, which keeps it below 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?

States a specific verb and resource ('Find covered European cities by name, country or region') and names the returned fields. It also signals downstream use ('the city id needed by the other tools'). It doesn't explicitly distinguish itself from list_countries or search_attractions, 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?

Gives a clear usage rule — 'Omit query to list all cities' — which effectively also describes the no-argument browse mode. It lacks explicit exclusions or a pointer to a sibling (e.g. when to use list_countries instead), so it is clear but incomplete.

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