TableJourney food travel

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description reinforces and extends this by disclosing the exact result shape: one entry per partner, only verified pickup facts, a tracked booking link, and an empty list when no partner covers the city. This adds meaningful behavior beyond the annotations with no contradiction.

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 well-paced sentence that front-loads the core purpose, then adds output semantics and the empty-list case. There is no filler, repetition of schema details, or 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?

Given an output schema already exists, the description does not need to enumerate return fields. It covers the selection rationale, result shape, and empty-case behavior, while the required parameters are fully documented in the 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?

Both parameters are fully described in the input schema with 100% coverage, so the description does not need to explain country/city semantics. The description adds little beyond the word 'city' and correctly does not duplicate schema details.

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

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

The description states a specific resource ('Car hire partners that verifiably cover a city') and a concrete output: one entry per partner with checked pickup facts and a tracked booking link. The read-only qualifier and empty-list behavior clearly distinguish it from sibling travel 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?

The description implies when to call this tool (when the agent needs car hire coverage for a city), but it does not explicitly state when to use it versus alternatives like search_places or stays. There are no exclusions or named sibling conditions.

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, and non-destructive behavior. The description adds value beyond those annotations by clarifying that the returned slugs are the ones other tools accept, which is important integration context not present in the annotations.

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

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

Two short, purposeful sentences with no filler. The tool's purpose, return contents, and usage hint are all front-loaded and immediately actionable.

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 low-complexity tool with one optional parameter, rich annotations, and an output schema, the description covers the essential operational guidance: what it returns and when to call it. 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 description coverage is 100%, and the schema already explains the optional country filter with an example. The description adds minor context by mentioning country and city slugs, but the schema carries the parameter-documentation burden.

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 clearly identifies this as the list of every city the site covers, and specifies that it returns the country slug, city slug, and hub page URL used by other tools. It is not a tautology and is clearly distinct from the sibling tools, which operate on specific content types rather than city coverage.

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 explicit directive 'Call first when unsure of coverage' tells the agent exactly when to use this tool, positioning it as the discovery/reference step before using other tools. This is strong usage guidance for a simple list 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?

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description adds value by disclosing that results are ranked by editorial score, venues are resolved to IDs and page URLs, and each item includes a citation page. These are behavioral and enrichment details beyond the structured fields.

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 sentences with the primary purpose front-loaded and the output characteristics summarized compactly. 'Read-only' is slightly redundant with the annotations, but it does not meaningfully hurt conciseness.

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, full parameter documentation, and safety annotations, the description covers the essential purpose, ranking basis, and result composition. It is slightly incomplete only in not routing the agent away from overlapping sibling tools like search_places or places.

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 parameters are already documented in the input schema, and the description need not repeat them. The prose does not add extra meaning about city, query, country, or limit beyond what the schema says, keeping this at baseline.

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

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

The description identifies a specific resource — signature dishes of a city and their venues — and orients the agent with 'where to eat them' and 'ranked by editorial score.' It does not use an explicit verb like 'list' or compare against sibling tools such as search_places, so sibling 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?

The phrase 'Signature dishes of a city' implies when to call the tool, but there is no explicit when-not-to-use guidance or mention of alternatives among siblings. The query/country parameters hint at broader usage, but exclusions are 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=true and idempotentHint=true, and the description reinforces this with 'Read-only.' It goes beyond annotations by disclosing ranking behavior ('Ranked by relevance to query when given, otherwise by popularity') and the presence of a tracked 'book' link. This gives the agent useful behavioral context not present in structured metadata.

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 three short sentences with no filler. It front-loads the core purpose, then adds read-only status, output highlights, and ranking logic in a compact and scannable 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?

Given the presence of an output schema, complete parameter descriptions in the input schema, and read-only/idempotent annotations, the description covers all essential behavior an agent needs to invoke and interpret the tool correctly. 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 description coverage is 100%, so the schema fully documents parameters like city, limit, query, country, and food_only. The description adds value by clarifying how query affects result ranking and by summarizing the returned item fields, which helps an agent anticipate how parameters shape the response.

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 clearly identifies the resource: bookable experiences like food tours, cooking classes, tastings, and tickets for a city. It distinguishes itself from siblings such as stays, car_hire, and search_places by focusing on bookable activities rather than lodgings, vehicles, or general places.

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 clear context about what the tool is for—bookable experiences in a city—and how results are ranked depending on the query parameter. However, it does not explicitly say when to avoid this tool or name an alternative, so the selection guidance is implied rather than direct.

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 idempotentHint=true, covering the safety profile. The description adds valuable behavioral context: it returns 'starts_on/ends_on for the next edition, the organiser source URL and the page to cite,' which explains what the output contains and that dates are resolved. It also mentions the read-only nature redundantly, but this does not contradict annotations. The extra detail about output fields goes beyond annotations.

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

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

The description is a single, well-structured sentence that leads with the core purpose ('Food festivals with their next resolved dates'), then lists the filters and output fields. It is concise, with no wasted words, and front-loads the most important information. Every clause earns its place, making it easy for an agent to parse quickly.

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 that an output schema exists (not shown here) and annotations cover safety, the description sufficiently explains what the tool does, its filtering options, and the nature of its results. It does not need to enumerate return types or edge cases, as those are documented elsewhere. The description is complete enough for an agent to understand when to call it, though it could mention pagination or defaults, but these are already in the 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?

Schema description coverage is 100%, with each parameter having a detailed description, including examples (e.g., city slug or name, default values, and behavior like 'did_you_mean' for unknown cities). The description's mention of filtering by 'city, country, a date window and text' is a high-level summary that adds no new semantics beyond the schema. Since the schema already carries the parameter burden, 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 clearly states the tool provides 'Food festivals with their next resolved dates' and mentions filtering by city, country, date window, and text. It identifies the specific resource type (food festivals) and its output (starts_on/ends_on, source URL, citation page). It does not explicitly differentiate from sibling tools like 'experiences' or 'place', but the domain is distinct enough that an agent can infer the purpose. Score 4 because it is clear but lacks explicit sibling 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?

The description provides no guidance on when to use this tool versus alternatives. It simply describes its functionality without mentioning any conditions for selection or exclusions. For example, it doesn't say 'use this for food festivals; use experiences for other events.' The agent must infer usage solely from the tool name and description, which is insufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds useful behavioral details beyond those: every venue is resolved to id, address, hours, and page URL, and an empty list is returned when the city has none. No contradiction with 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?

The description is two dense sentences that front-load the purpose and include only relevant behavioral details. The phrase 'read-only' is redundant with the annotations, which is a minor blemish.

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 rich annotations, a 100%-covered input schema, and the presence of an output schema, the description is sufficiently complete. It covers empty-list behavior and resolved venue fields, while parameter semantics are already handled by the 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?

Schema description coverage is 100% and the parameter descriptions already include examples and did_you_mean behavior. The description adds no extra parameter information, 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 clearly identifies the resource as editorial day-by-day food itineraries for a city and specifies what each venue resolves to. It is more specific than the tool name alone, but it does not explicitly contrast with sibling tools like plan_day or experiences.

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

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

It provides clear context for when to use the tool: when retrieving city food itineraries. However, it does not mention alternatives or state when not to use it, so it stops short of full 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, non-destructive. The description adds error behavior (returns {error: ...} for malformed/unknown id) and enumerates return content, which is useful beyond annotations. No contradiction; adds context on failure modes.

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 that front-loads the purpose and enumerates key return fields and error case. Zero fluff; every clause 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?

With no output schema, the description compensates by listing the expected return fields and the error format. For a simple id-based lookup, it covers all needed operational details. Sibling tools are distinct and the description fully equips an agent to call it correctly.

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

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

Schema coverage is 100%, so the description need not explain the id parameter further. The description mentions 'by id' but adds no semantic detail beyond the schema's example. Baseline 3 is appropriate since the schema fully documents the parameter.

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 clearly states the tool's function: retrieving one venue in full by id, read-only. It enumerates the specific content (fields, provenance, hours, open_now_utc, booking link, nearby venues) which distinguishes it from sibling tools like search_places (list) or cities/dishes (other resources).

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

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

The description implies usage when you have an id and need full venue details, and the schema explicitly ties id to 'search_places returned'. However, it does not explicitly state alternatives or conditions when not to use this tool, though the sibling list and schema hint at the lookup workflow. Lacks 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context beyond these: it specifies the selection algorithm (one best-scored open venue per slot), the availability check (every stop open on the given date), the inclusion of a bookable experience, and the behavior of also listing itinerary titles. This is rich, non-redundant behavioral disclosure that helps the agent predict outcomes.

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 a single, information-dense sentence that front-loads the core action and criteria, then appends the alternative guidance. There is no filler or repetition; every clause adds value. It is appropriately sized for the tool's complexity.

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 tool's complexity (6 parameters, no output schema, no nested objects), the description covers what the agent needs to call it correctly: what it returns (venue-per-slot plan plus a bookable experience and itinerary titles), when to prefer the alternative, and the filters. It does not explain return formats, but the absence of an output schema makes the description's summary of results sufficient.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description repeats the filter concepts (neighbourhood, dietary need, price tier) but adds no syntax, formatting, or edge-case details beyond what the schema provides. It does not compensate for anything missing, so the 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?

The description states a specific verb ('Compose'), a precise resource ('a food day for one city'), and enumerates the selection criteria (best-scored open venue per slot, filtered by neighbourhood, dietary need, price tier, open on date, plus one bookable experience). It also names the sibling alternative (`itineraries`) and the condition that selects it, making the purpose unambiguous and distinct from the other 9 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?

The description explicitly says the editorial itineraries are 'the better plan when one exists' and directs the agent to fetch them with `itineraries`. This is an explicit when-to-use/when-not-to-use directive with a named alternative, exceeding the minimum bar for usage 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, and non-destructive behavior, so the description doesn't need to restate safety. It adds genuinely non-obvious behavior: ranking by relevance then editorial score, result provenance (source URL, checked_on, open_status), hours, tracked booking links, a hard 'limit' cap, and the did_you_mean response for unknown cities. This goes well beyond the annotation baseline.

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-load the core purpose and then bundle filters and result characteristics without wasted language. The only minor redundancy is 'read-only' repeating the annotation; otherwise every clause earns its place, though the long second sentence is slightly dense.

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 result shape, ranking, unknown-city fallback, and the result cap, and it pairs well with the rich schema and existing output schema. It doesn't explain offset/pagination or how filters combine, but those details are already present in the parameter descriptions, leaving no critical gap for invoking the tool correctly.

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

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

The input schema has 100% coverage with detailed per-parameter descriptions (including examples for city, kind, open_at, and radius_km). The top-level description summarizes the filter categories but adds no new parameter-level meaning, so the baseline of 3 is appropriate 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 opening phrase 'Search verified venues (read-only)' names a specific verb and resource, and the description enumerates the full filterable surface (text, city, kind, cuisine, dietary, price tier, opening time, near). It is instantly clear what this tool does and how it differs from siblings like 'place' (a singular lookup) or 'dishes'.

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 clearly frames when to use this tool: when an agent needs to find venues by various criteria and wants ranked, provenance-annotated results. It does not explicitly list sibling alternatives or exclusions (e.g., use 'place' for a single venue by ID), but the resource and filter context is strong enough for an agent to infer the main use case.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description only needs to add context beyond those. It adds that each hotel listing has a tracked booking link, that partner search links are included, and that prices are deliberately not returned. This is useful behavioral detail with no contradiction.

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

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

Two sentences with the main resource and read-only nature front-loaded, followed by the exact result contents and the price limitation. There is no filler or redundant repetition of the schema.

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

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

With no output schema, the description explains what is and is not returned: hotel listings with tracked links, partner search links, and a clear price caveat. It relies on the schema for parameter details, which is acceptable for a simple read-only tool; only a brief note on when to prefer a sibling 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?

Schema description coverage is 100%, so city, country, and limit are already documented in the input schema. The description's phrase 'for a city' restates the main scope but adds no parameter-level meaning beyond what the schema provides, keeping it at the baseline 3.

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

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

The description clearly identifies the resource as hotels/stay partners for a city and frames it as read-only, with hotel listings and partner search links. It does not use an explicit verb like 'list' or 'search' and does not name a sibling tool, 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?

The context 'for a city' plus 'hotels and stay partners' implies the intended use case, but there is no explicit guidance about when to choose this over siblings like experiences or car_hire. No alternatives or when-not conditions are given.

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