Yenta Directory

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

Beyond the readOnly and idempotent annotations, the description discloses a key behavioral nuance: recurring events' spans are not single dates and the agent should read their recurrence. This adds operational value and tells the agent what to expect, going beyond the structured 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 entire description is one efficient sentence with every word earning its place. The core action is front-loaded and followed by the date-window default and recurrence warning—no filler or redundant 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?

Given the high schema coverage and the presence of an output schema, the description provides sufficient context for an agent to call the tool correctly. It covers the destination parameter, date defaults, and key recurrence nuance. The only gap is explicit guidance on alternative tools or when to prefer other searches.

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 doesn't need to repeat parameter details. The description clarifies the destination parameter conceptually ('a named destination') and hints at the date semantics ('default from today'), but most parameter meaning is already in the schema, so a baseline score of 3 is appropriate.

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

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

The description states the exact operation: finding a named destination's events overlapping a date window, with a default start date. This clearly identifies the resource (destination events) and distinguishes it from sibling tools like destination_overview or search_destinations, none of which cover event search.

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 use the tool: when you need a destination's events over a date range. However, it does not explicitly compare with alternatives or state when not to use it, leaving the agent to infer the appropriate use from context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds that the values are 'valid' for the destination and names the three families, but does not disclose additional behavioral details such as behavior for unknown destinations or whether results are exhaustive. This meets the minimum bar for a read-only tool.

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

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

The entire description is a single front-loaded sentence with no filler. It states the action, the scope, and the result clearly and efficiently.

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?

This is a low-complexity, read-only list tool with complete parameter descriptions, an output schema, and annotations covering safety. The only notable gap is the lack of explicit distinction from the sibling facet_vocabulary, which could affect tool selection but not the correctness of a call once selected.

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

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

Schema description coverage is 100%, and both parameters already have meaningful descriptions: destination explains how to find one, and kind explains filtering and omission. The description's mention of 'area, category and tag' reinforces the enum but adds no parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('List') and clearly identifies the resource: a named destination's valid area, category, and tag filter values. This specificity distinguishes it from the content-oriented sibling tools like destination_guide or destination_events, even though it does not explicitly contrast with facet_vocabulary.

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 the tool should be used when you have a named destination and need its valid filter values, and the destination parameter points the agent to search_destinations to discover one. However, it gives no explicit when-to-use versus alternatives such as facet_vocabulary, leaving some selection guidance 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 cover readOnlyHint, idempotentHint, and destructiveHint=false, so the description needn't repeat safety traits. The description explains the search and filter behavior but does not add extra context such as pagination/ordering, though the schema's cursor parameter conveys the pagination mechanism.

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 sentence, front-loaded with the core action, and contains no filler. Every word 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?

Given the tool is a read-only simple search with an output schema and fully described parameters, the description is adequate for an agent to use it correctly. The only minor gap is that the destination parameter is not explicitly marked required in the description, but the schema's required list handles that.

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

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

Schema description coverage is 100%, with all parameters documented. The description's mention of 'filtered by text' overlaps with the 'query' field description and adds no new semantic value beyond what the schema already communicates.

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 'Search' with a named resource 'destination's FAQs' and an optional filter. It clearly distinguishes from the sibling 'venue_faq' by scoping to destination, so an agent knows which tool to pick without inspecting schemas.

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

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

The description clearly identifies the context: searching FAQs for a named destination. It does not explicitly mention when not to use this tool over siblings like venue_faq, but the destination scope and the schema's note to call search_destinations imply the right usage pattern.

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, and destructiveHint=false, and the description's 'Read' is fully consistent with those. The description adds the editorial-guide scope but no further behavioral traits such as response handling, filtering semantics, or prerequisites. It contradicts nothing, so a mid score is appropriate.

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

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

The description is a single front-loaded sentence with no filler: verb, resource, and illustrative topics. Every word earns its place, and the message is immediately parseable.

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 read-only tool with an output schema and fully documented parameters, the core purpose is adequately covered. However, the description leaves usage context thin: it does not mention optional query/topic filters, nor does it help an agent distinguish this from sibling destination_faq or destination_overview tools. Much of the missing context is recoverable from the schema, but the description alone is not fully self-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%, with all three parameters already documented, including the topic enum and the note to call search_destinations. The description's examples ('weather, getting here and safety') merely echo the schema's topic enum and add no meaning beyond it. Baseling 3 is correct when schema already carries the parameter documentation.

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 clear verb ('Read') and resource ('a named destination's editorial guides'), with concrete examples such as weather, getting here, and safety. It is not a tautology and is distinct from a generic 'get destination' tool, but it does not explicitly differentiate itself from sibling content tools like destination_faq or destination_overview.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no mention of sibling alternatives. The agent must infer from 'editorial guides' that this is the right tool for curated content. The only related pointer, calling search_destinations, appears in the schema rather than the description and concerns finding a destination, not choosing this tool over 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, and destructiveHint=false, covering safety. The description adds value by noting the result includes a live linked venue's mcp_endpoint and linked_venue_slug, which helps the agent understand the output's behavioral significance without contradicting 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?

The description is a single sentence that front-loads the core action and includes the most important output details. There is no redundant wording or repetition of schema content.

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

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

The output schema exists, so return value explanation is not required. The description covers the purpose, the key linked-venue data, and downstream usage with venue_* tools. The only minor gap is the title/description discrepancy around 'by name' versus 'by id,' which could confuse selection.

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 both parameters well. The description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool fetches one listing's full detail by id and mentions the linked venue data it returns. However, the title says 'by name' while the description and schema require a listing_id, creating a mild inconsistency, and it doesn't explicitly differentiate itself from the sibling destination_listings.

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 explains how the returned mcp_endpoint and linked_venue_slug can be used with the venue_* tools to read or book the venue. This gives useful downstream context, though it doesn't explicitly state when to prefer this tool over destination_listings or other destination 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 the operation as readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds a bit of behavioral context by noting the optional proximity search, but it does not disclose behaviors like cursor pagination, tag-ALL semantics, or nearest-first ordering—though some of those appear in the parameter descriptions.

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 efficient sentence that fronts the primary action and resource, then enumerates the filter dimensions compactly. No filler or redundant elaboration.

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 existing output schema, full parameter documentation, and strong annotations, the description covers the core search intent well. The main completeness gap is the lack of explicit relationship to sibling tools, but the short description plus schema make the tool callable for a well-scoped destination search.

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 explains all parameters. The description adds a helpful high-level summary of the main filters, but it does not provide additional semantic detail beyond what the input schema already specifies.

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 action ('Search') and resource ('a named destination's listings'), and lists the key filter dimensions: text, category, area, and tags. It could be more explicit about how it differs from sibling tools like destination_listing or search, but the core purpose is unambiguous.

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

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

The description gives no guidance on when to use this tool versus alternatives such as destination_listing, search, or destination_facets. It notes that facet slugs come from destination_facets and that destinations come from search_destinations (in the schema), but it does not provide when-to-use or when-not-to-use context.

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

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

The readOnlyHint, idempotentHint, and openWorldHint annotations already cover the main behavioral guarantees dates; the description adds that the result is a summary with category, currency, and timezone counts. No additional behavioral disclosure is offered beyond that, which is acceptable for a simple read-only tool.

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

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

The description is a single, compact sentence that puts the core action and key output content up front. It wastes no 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?

For a simple read-only lookup with full schema coverage, an output schema, and strong annotations, the description is sufficient. It could improve slightly by positioning the tool relative to get_destination, but this is not a major gap.

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

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

The schema already fully describes the destination parameter, including how to find a value via search_destinations, so the description does not need to compensate. The tool description adds little beyond implying the destination is identified by name, which the schema already conveys.

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 fetches a summary of a named destination with specific content (counts by category, currency, timezone). It distinguishes itself from sibling destination tools by framing the output as an overview, though it doesn't explicitly contrast with get_destination.

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

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

No guidance is given about when to prefer this tool over alternatives like get_destination or destination_facets. The parameter description usefully says to call search_destinations to discover a destination, but this is a lookup hint rather than usage guidance for the tool itself.

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 signal read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context beyond annotations by clarifying that values are 'live' and aggregated 'across published venues', and that the vocabulary is 'closed'. No contradictions 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 a single dense sentence with no filler and is front-loaded with the key term 'closed facet vocabulary'. It is slightly run-on and uses the vague 'and more', but overall it is efficiently written.

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 zero parameters, read-only annotations, and an output schema, the description provides enough context: what the tool returns and how it relates to search_venues filtering. The only minor gap is not explicitly stating the return shape, but the output schema covers that.

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

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

The tool has zero parameters, so the schema is trivially complete and the description has no parameter burden. It still usefully names example facet dimensions like vibe, cuisine, and dietary, which helps an agent interpret the returned data.

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: the closed facet vocabulary plus today's live values, and ties it to the exact values that search_venues filters accept. This helps distinguish it from destination-scoped siblings like destination_facets, though it lacks an explicit verb such as 'returns' or 'provides'.

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 'the exact values search_venues' matching filters accept' gives a clear use case: call this tool to discover or validate allowed filter values for search_venues. It does not explicitly name alternatives or say when not to use it, but the context is reasonably clear.

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

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

The readOnlyHint and non-destructive annotations already establish safety. The description adds useful behavioral detail by specifying it returns a summary and a 'live mcp_endpoint', and only for published destinations. No contradiction between description and 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?

One compact sentence states the action, resource, filter, and lookup key. There is no filler, redundant phrasing, or contextual preamble for the agent to wade through.

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 a complete parameter schema, read-only annotations, and a description stating both the input (slug) and expected return fields (summary and live mcp_endpoint), the agent has enough to call the tool correctly. It does not cover error cases like an invalid slug, but for a simple getter that is a minor gap.

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

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

The single parameter destination_slug has full schema coverage, including how to obtain it via search_destinations. The tool description adds no new parameter meaning beyond 'by its slug', so it mainly repeats the schema rather than enhancing 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?

The description is specific: 'get one published destination's summary and live mcp_endpoint by its slug.' It names the exact resource, the lookup key, and the returned output. This is enough for an agent to distinguish it from search-style or overview siblings even without naming 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 description implies the tool is for fetching a single known destination rather than searching, and the schema guides agents to obtain the slug from search_destinations. However, the description itself does not state when to prefer this over siblings like destination_overview or destination_guide, and it includes no exclusion criteria.

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, and destructiveHint=false, so the safety profile is covered. The description adds that it returns a 'summary, capabilities and live mcp_endpoint', which is useful. It doesn't mention potential errors (e.g., not found) or rate limits, but with strong annotations, a 3 is appropriate.

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

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

One sentence, front-loaded with the action and resource, and includes the key output fields. No 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?

For a single-parameter read tool with an output schema and strong annotations, the description is nearly complete. It could mention what happens if the venue is not found or if the slug is invalid, but the output schema likely covers the return shape. The reference to search_venues for slug acquisition is a nice touch.

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 venue_slug. The description adds that the slug is 'as returned by search_venues', which is helpful context but not substantial beyond the schema. Baseline 3 is correct.

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 retrieves a single published venue's summary, capabilities, and live mcp_endpoint by slug. It distinguishes itself from siblings like get_venues and search_venues by focusing on a single venue and specific fields, though it doesn't explicitly name those siblings.

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

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

The description implies usage: use this when you have a venue_slug and need a single venue's details. The parameter description references search_venues as the source of the slug, providing context. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough.

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 adds real value beyond them: the base view is always returned, include opts into heavier reads, items come back in requested order, duplicate slugs fraction resolved once, and not_found lists unresolved slugs. These behavioral guarantees materially affect how an agent interprets results, and none contradict 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?

The description is front-loaded with the core purpose and then packs scoping, invocation and semantics into subsequent clauses with no wasted words. It is one long, dense sentence—splitting it would aid readability—but 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 an output schema present and 100% parameter schema coverage, the description only needs to cover behavior and selection logic, which it does thoroughly: base vs. include views, ordering, dedup, unresolved-slug reporting, and the use case. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds beyond the schema: it documents the ordering guarantee, that unresolved duplicates resolve once, and the not_found listing behavior. These are parameter-level semantics (for slugs and include) not present in the schema, raising the score above 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 states a specific verb and resource — 'Get several published venues' summaries in ONE call by their slugs' — and explicitly differentiates from the sibling get_venue by framing it as 'the batch counterpart.' An agent can immediately distinguish this from search_venues and venue_profile without opening schemas.

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

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

The description clearly establishes when to use this tool: 'a shortlist from search_venues needs no per-slug round-trip,' naming the alternative (get_venue) and the driving scenario. It does not explicitly say when NOT to use it (e.g., for a single venue or for venue-specific menu search), so it stops just short of full when/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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent already knows the operation is safe. The description adds the filter for published venues, which is behavioral context not in the annotations. However, it does not mention pagination behavior or that only cities with published venues are included, which is the key filter. The added context is useful but minimal beyond the safety profile.

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, efficient sentence that front-loads the core purpose. Every word is functional, with no redundancy or filler.

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

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

Given the tool is a simple list with an output schema and fully documented parameters, the description is nearly complete. The main missing piece is explicit guidance on when to choose this over similar search tools, but that is a minor gap for a low-complexity 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 100%, so the schema fully describes both parameters (limit and cursor). The description adds the filter on published venues, which affects which cities appear in results, but it doesn't add further parameter-level detail beyond the schema. Since coverage is high, the baseline of 3 is raised because the description adds a meaningful semantic constraint.

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 verb 'list' and the resource 'cities', and specifies the exact criterion: cities with at least one published venue. This distinguishes it from siblings like search_destinations or list_* tools that may have different scopes.

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 clear context on what it returns (cities with published venues) but does not explicitly discuss when to use this tool versus alternatives. Given siblings like search_destinations exist, more guidance on choosing this simple list over search would improve the score.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond those flags: only published items are searched, results are tagged with kind, and city only narrows venues, not destinations.

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 core purpose, then adds scoping parameters and routes to alternatives. No filler or repetition; 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?

Given the rich annotations, fully documented schema, and existing output schema, the description covers everything needed to call the tool correctly: what it searches, how results are tagged, how to scope, and when to switch to a sibling tool.

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

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

Schema coverage is 100% and each parameter already has detailed descriptions, so the schema carries the semantic burden. The description adds a useful high-level summary of kind, query, and city, but does not introduce new parameter meaning beyond what the schema states.

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: 'Search published venues and destinations together in one call', and clarifies that each result is tagged with its kind. This clearly distinguishes it from type-specific siblings like search_venues and search_destinations.

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

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

Explicitly tells the agent to use search_venues or search_destinations when type-specific filters like cuisine, hours, or area are needed. It also explains when to pass kind, query, and city, leaving little 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 carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds beyond that: the 'published' pre-filter scope and the behavioral fact that each result carries an mcp_endpoint to be traversed for listings, events, and guides. No contradiction with annotations; it could add pagination-limit behavior but the cursor mechanism is already in the 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?

One sentence with zero waste: core verb/resource first, then the conditional listing behavior, then the forward-linking instruction that arranges the results. Every clause earns its place and the most important 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?

Given the output schema covers return shape, annotations cover the safety profile, and the schema documents all params and pagination, the single sentence is nearly sufficient for an agent to invoke it correctly. The only gap is that it doesn't mention a natural 'when to prefer get_destination vs search_destinations', so a small edge remains.

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 fully documents limit, query, and cursor including defaults, ranges, and the 'omit to list all' note. The description only restates the query param's same behavior and adds nothing material about the other parameters, so the baseline 3 is correct; the description neither fails to compensate nor elevates beyond the schema.

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

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

States a specific verb and resource ('Search published travel destinations by name') plus a clear condition ('omit the query to list all'). The mcp_endpoint note differentiates it from sibling content tools like destination_listings, destination_events, and destination_guide, which fetch what this tool points to. An agent can identify what this tool does and what it is not without opening schemas.

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

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

Gives one concrete usage condition (omit query to list all destinations) and a follow-up action (connect to each result's mcp_endpoint). However, it never states when not to use this tool relative to the 21 siblings such as search, get_destination, search_venues, or list_cities, so the switch/selection logic 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 establish this as read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: results are limited to published venues, and each result carries its venue so an agent can rank venues. No contradiction exists between the description and 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?

A single, dense sentence that front-loads the core action and scope, then specifies filters and the output purpose. There is no filler, repetition, or redundant detail; 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 detailed input schema, output schema, and safety annotations, the description is nearly complete. It covers the essential scoping ('all published venues') and the key output behavior (venue-tagged results), though a brief note about pagination or an explicit pointer to venue_menu_search for single-venue searches would make it fully self-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 baseline is 3. The description summarizes query, city, dietary_tags, and allergens in plain language but does not add meaning substantially beyond the schema's existing per-parameter descriptions. Pagination parameters are left entirely to the schema, which 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 clearly states the action ('Search menu items'), the resource ('across all published venues'), and the key filters (text, city, dietary tags, allergens). The phrase 'each result tagged with its venue' further explains what the tool returns and distinguishes it from venue-scoped siblings like venue_menu_search.

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 communicates a clear usage context: cross-venue menu search for ranking venues in one call. It does not explicitly name alternatives or state when not to use the tool, but the 'across all published venues' scope gives a strong contextual distinction from single-venue menu search.

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

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

The description extensively discloses behavior beyond the annotations: filters exclude non-matches, soft preferences never drop results, venues with no coordinates or published hours are excluded, and each result carries capabilities plus mcp_endpoint when live. This is far richer behavioral disclosure than the readOnly/idempotent/destructive annotations alone.

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 long run-on sentence, which hurts readability, but every clause carries distinct, useful information and the core purpose is front-loaded. It could be broken into shorter sentences without losing content, but it has no filler.

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

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

For a complex 18-parameter search tool, the description is remarkably complete: it explains filter semantics, exclusion criteria, result payload highlights, and vocabulary references. With a full output schema and strong annotations, nothing necessary 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?

The input schema already provides 100% parameter descriptions, but the description adds meaning beyond them by framing the hard/soft distinction, including facet token syntax and aggregation behavior, and explaining that soft parameters rank-only and never drop. This exceeds baseline because it resolves ambiguity the schema alone leaves open.

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

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

The description states a specific verb and resource ('Search published venues') and enumerates the many supported axes, with explicit hard-filter versus soft-preference semantics. This clearly differentiates it from siblings like search_menus or get_venues.

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 for when this tool is appropriate — searching venues by name/description and applying filters — and precisely explains which filters are exclusive versus preferential. However, it doesn't explicitly say when to prefer alternatives like get_venues or search, leaving the routing 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 cover read-only/idempotent/non-destructive behavior; the description adds the key behavioral detail that tags/allergens are returned in the exact spellings used for literal matching.

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

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

One front-loaded sentence communicates the purpose and the key matching behavior without 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?

Given simple required/optional parameters, complete schema descriptions, rich annotations, and an output schema, the description covers everything needed to invoke 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?

Input schema already fully describes both parameters, so the description adds no additional parameter-level meaning; baseline 3 applies.

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

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

States a specific action and resource ('List a named venue's declared dietary tags and allergens') and differentiates itself from siblings by highlighting exact spellings for venue_menu_search.

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

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

Clearly signals its role as the source of literal dietary tag spellings used by venue_menu_search, implying when it is useful. It does not explicitly name alternatives or 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, and non-destructive, and the description's 'Search' is consistent with them. It adds modest context by limiting results to 'published' FAQs and noting optional text filtering, but it does not disclose further behavior such as pagination semantics or closed-world limitations. Those details are left to the 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?

The entire description is a single front-loaded sentence with no filler. It states the action, resource, and optional filter efficiently, earning every word.

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 input schema (all parameters documented, including city disambiguation, cursor pagination, and venue discovery via search_venues) and the presence of an output schema, the brief description is complete enough for invocation. It need not repeat return-value details. The only missing element is explicit sibling routing, which is a usage-guideline issue rather than a completeness gap.

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

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

The input schema describes all five parameters with 100% coverage, so the baseline is 3. The description adds no extra semantics beyond mirroring the query ('text') and venue scope ('named venue'); all parameter details are already in the schema.

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

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

The opening verb 'Search' names the action, and 'venue's published FAQs' names a specific resource that is distinct from sibling tools like destination_faq, venue_profile, and search_venues. The optional text-filter qualifier further narrows scope. An agent can tell this tool is for retrieving FAQ content of an already identified venue.

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 conveys the core use case—retrieve published FAQs for a named venue, optionally filtered—so an agent can infer when to call it. However, it offers no explicit routing guidance, such as 'use destination_faq for destination FAQs' or 'call search_venues first to resolve a venue.' Thus the when-to-use guidance is implied 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond annotations: it specifies that only 'published' links are returned and clarifies that booking is performed via the mcp_endpoint, which is not apparent from the schema or 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. It front-loads the main action and resource ('Get a named venue's published booking and other links') and then appends the parenthetical clarification about the mcp_endpoint. There is no redundant wording or filler.

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

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

For a simple two-parameter tool with a documented output schema and annotations covering safety, the description is complete. It explains what the tool returns (links), the qualifier (published), and the next step (connect to mcp_endpoint to book), covering everything an agent needs 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?

The input schema has descriptions for both parameters (100% coverage), including the hint to call search_venues and list_cities. The tool description itself does not add any parameter-specific meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action (Get), the specific resource (a named venue's published booking and other links), and distinguishes this tool from siblings like get_venue by focusing on links. It also adds the important nuance that actual booking happens via the mcp_endpoint, making the tool's role unambiguous.

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

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

The description provides clear context: use this when you need a venue's booking links, and it notes that booking itself is done via mcp_endpoint. However, it does not explicitly mention alternative tools (e.g., get_venue) or state when not to use it, so it lacks explicit exclusions or comparisons.

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, and destructiveHint=false, so the safety profile is fully covered. The description adds the useful behavioral detail that dietary_tags are ANDed ('Require ALL') and allergens are exclusionary ('Exclude items declaring any'), which goes beyond the schema. However, it does not disclose pagination behavior or the meaning of next_cursor, though the schema covers cursor mechanics. With annotations carrying the safety burden, a 3 is appropriate.

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

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

One sentence with zero waste. The core action and filtering dimensions are front-loaded, and the prerequisite call is appended as a clear directive. Every word 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?

For a read-only search tool with a 100%-covered schema, an output schema, and annotations declaring safety, the description is nearly complete. The only minor gap is that it does not explicitly state that results are paginated or that cursor should be used for subsequent pages, but the schema's cursor description covers this. The prerequisite guidance and filter semantics make it fully actionable.

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 7 parameters. The description adds the key semantic that dietary_tags are ANDed and allergens are exclusionary, which is valuable. But it does not add meaning for query, limit, cursor, or city beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description states a specific verb ('search'), a specific resource ('a named venue's menu'), and the three filtering dimensions (text, dietary tags, allergens). It also names the prerequisite sibling (venue_dietary_options), which distinguishes it from search_menus and other venue tools. This is a clear, non-tautological definition.

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 instructs the agent to call venue_dietary_options first for exact spellings, which is a concrete when-to-use directive. It also implies this tool is for menu-specific searches as opposed to the broader search_menus or search_venues siblings. The guidance is actionable and leaves little 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, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read. The description adds the 'published' nuance, indicating the task returns the public profile summary rather than internal data, but it doesn't describe any additional behavioral traits such as field subsets or edge cases. The description is consistent with the annotations and provides some value beyond them.

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, front-loaded sentence that starts with the action ('Get a named venue's published profile summary') and ends with the parameter format. There is no redundant wording, and 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?

The output schema and the annotations carry most of the richness, so the description doesn't need to explain return values. It explains the lookup modalities and points to list_cities/search_venues for discovery. A small gap is that with sibling get_venue in the same namespace, the description could state the distinction between 'published profile summary' and whatever get_venue returns, but the overall tool is still sufficiently complete to invoke 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 description coverage is 100 percent: venue is described as a name or slug, and city is described as disambiguating a name and being ignored for a slug. The description restates 'give its name (and city) or slug' but adds no new meaning beyond what the schema parameters already guarantee; the baseline of 3 is appropriate when schema does the primary parameter documentation.

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

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

The description states a specific verb and resource: get a named venue's published profile summary. It also communicates the input alternatives (name plus optional city, or slug), which distinguishes it from collection-returning siblings like search_venues and get_venues. However, it does not explicitly differentiate from get_venue, so a linking agent might still be unsure which one to pick for a single venue.

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 useful context: to obtain a single venue's published profile you supply a name (and city) or slug. The schema also points to list_cities for disambiguation and search_venues for discovery. It lacks explicit when-not-to-use guidance versus siblings like get_venue or venue_links, so an agent must infer which tools are alternatives.

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