NYCfoodie

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

Annotations declare readOnlyHint=true, and the description adds useful behavioral context by stating that output is structured comparison data. It does not mention side effects, but none are expected given the read-only annotation; the description meaningfully supplements the annotation by revealing result shape.

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, front-loaded with the core purpose and output format, followed by a clear usage example. Every sentence contributes value and there is no 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?

Despite lacking an output schema, the description lists the key returned fields (rating, price, tags, review summary) and the schema fully documents parameters. It is adequate for correct invocation, though it could briefly mention sibling alternatives for non-comparison queries.

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% description coverage for both parameters. The description reinforces the '2–3' cardinality and 'named restaurants' expectation, but adds little beyond the schema's property descriptions. 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 and resource: 'Compare 2–3 named restaurants head-to-head' and lists the output dimensions (rating, price, tags, review summary). It also clearly identifies the triggering scenario, distinguishing it from generic restaurant search or retrieval 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?

Explicit usage guidance is provided: 'Use when the user asks to choose between specific places', with a concrete example. It does not name sibling alternatives or state when not to use the tool, but the context is clear enough for an agent to route correctly.

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 the description adds behavioral detail beyond that: the tool returns ranked entries with blurbs, and include_entries=false changes the response to guide metadata only. This helps the agent predict output behavior without overpromising.

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 focused sentences: purpose with an example, usage guidance, and a practical parameter tip. Every sentence 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?

The description adequately describes the return content (ranked entries, blurbs, linked restaurants), the optional response mode via include_entries, and when to use the tool. With no output schema, this is sufficient for a read-only query tool, though it could mention pagination or ordering behavior.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds a little extra context, especially for include_entries, but does not substantially enrich parameter meaning beyond what the schema provides.

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 ('Find curated editorial guides'), explains what it returns (ranked entries, blurbs, linked restaurants), and distinguishes itself from sibling tools by explicitly contrasting with 'individual restaurant picks'.

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 explicitly says when to use the tool: 'Use when the user wants the editorial lists themselves rather than individual restaurant picks.' It does not name alternative sibling tools or provide when-not-to-use exclusions, but the usage context is clear.

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

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

The readOnlyHint annotation already establishes this as a safe read operation. The description adds useful behavioral context about scoring logic and name-based lookup ('a named one'), but does not disclose result ordering or return structure. With annotations covering safety, this is adequate but not rich.

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 no filler. The first sentence states the core action and scoring criteria; the second gives direct usage guidance. Everything earns its place and is front-loaded.

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

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

For a simple read-only similarity lookup, the description plus fully documented schema gives the agent the required id/city fields, limit default, and the nature of the result (scored similar restaurants). No output schema exists, but the description's mention of scoring provides enough expectation-setting.

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 input schema already documents id, city, and limit, including the fact that id can be a name and city is always required. The description does not need to restate these; the baseline of 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 announces the operation: 'Find restaurants similar to a named one' and adds how similarity is scored (shared cuisine, occasion, neighbourhood tags, guide co-occurrence). This is specific enough to distinguish it from sibling tools like search_restaurants or compare_restaurants without needing to open the schema.

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

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

'Use for 'like X' or 'alternatives to X' requests' explicitly states when to invoke this tool. It does not name excluded cases or alternative siblings like search_restaurants, but the trigger condition is concrete and actionable.

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 annotation already covers the safety profile. The description adds useful behavioral details beyond that: default output is headline plus summary, full prose is opt-in via include_prose, and review.headline may be null with review.summary as the descriptive fallback. This meaningfully clarifies output semantics.

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 dense and front-loaded: purpose, returned content, usage trigger, then parameter nuance. Every sentence contributes meaningful information without repetition 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 read-only single-restaurant lookup with no output schema, the description supplies a strong inventory of returned fields and clarifies the headline/summary behavior. The phrase 'booking intel' is slightly vague, and there is no mention of error cases, but overall the definition is sufficiently complete for 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 description coverage is 100%, so the baseline is 3. The description adds extra value by explaining the default behavior of include_prose and what it toggles. The id and city parameters are already well documented in the schema, so the description does not need to repeat them.

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

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

The description opens with a clear verb and resource: 'Get the full picture for one restaurant in one call.' It enumerates exactly what is returned, and the line 'Use when the user names a specific restaurant' distinguishes it from sibling tools like search_restaurants.

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 states when to use the tool: 'Use when the user names a specific restaurant.' It provides clear context but does not explicitly name alternatives or state when not to use it, so it stops just short of full routing guidance.

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

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

The readOnlyHint annotation already covers the safety profile. The description adds useful behavioral context by clarifying that ranking is based on the count of distinct guides and that results can be filtered by theme. It does not disclose pagination, result shape, or aggregation details beyond that, but the annotations lower the burden here.

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

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

Three short sentences, each earning its place: the core functionality, the intended use case, and the differentiation from a sibling. The most important information is front-loaded and there is zero 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 read-only ranking tool with fully documented parameters and no nested objects, the description is nearly complete. It explains the ranking semantics, optional filtering, and the intended use case. The only minor gap is that no output shape is described, but for a simple list-returning tool this is a low-cost omission given the clear semantics.

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% for all three parameters, so the schema fully documents city, limit, and theme. The description only reiterates that theme is optional and that ranking is by guide consensus, adding no syntax or format detail beyond the schema. Baseline 3 is appropriate because 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 ('Rank'), resource ('restaurants'), and ranking criterion ('how many distinct guides feature them'), plus an optional theme filter. It also explicitly distinguishes this tool from find_guides by noting the difference in return type, so an agent can tell them apart 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 gives clear use cases ('where can't I go wrong', safest-bet picks) and names find_guides as the alternative, explaining that this returns ranked restaurants while find_guides returns guides. It lacks explicit 'when not to use' comparisons against other siblings like top_rated or search_restaurants, but the provided context is sufficient for typical routing.

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 annotation already signals safety, and the description adds substantial behavioral context: free-text matching covers names, tags, review prose and guide blurbs; known-closed venues are excluded by default; coverage is limited to NYC metro within 30 km; and an empty query returns highest-rated venues. These details go well beyond the annotation.

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 dense but every sentence earns its place: action and primary use case come first, followed by matching behavior, return fields, default filtering, coverage, and no-query behavior. No filler or redundant restatement of schema fields.

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 13 parameters, no output schema, and only a readOnly annotation, the description compensates well by stating return fields, default exclusions, coverage boundaries, and degenerate-query behavior. The input schema covers parameter constraints, so the description is complete enough for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by clarifying that free text matches 'names, tags, review prose and guide blurbs' and by grouping location-related parameters as 'optionally near a point.' This enriches the query semantics without needing to repeat every 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 searches restaurants by multiple criteria and differentiates it from lookup-by-name tools by saying it is for when the user 'describes what they want... rather than naming a specific restaurant.' It also specifies the return contents (rating, price tier, address, tags), making the purpose 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?

It gives an explicit when-to-use instruction with concrete examples ('Italian date night in the West Village', 'ramen near me') and an implicit exclusion for named-restaurant queries. However, it does not explicitly name the alternative sibling tool for that case, so the guidance is strong but not fully explicit about 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 only mark the operation as non-read-only and non-idempotent. The description adds meaningful side-effect context: each call stores a new feedback entry and changes nothing the user sees, which aligns with and enriches the annotation hints.

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

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

Three short, information-dense sentences cover purpose, usage trigger, required content, and side effects with no filler. The essential constraint is front-loaded.

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

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

For a simple 3-parameter tool with no output schema, the description covers purpose, when to use it, side effects, and content rules. The main gap is the unclear requirement status of the 'tool' parameter and the absence of any success/return signal, but both are minor at this complexity level.

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 documents all three parameters, so the baseline is 3. The description adds the important validation rule that at least one of rating/comment is required, which the schema itself does not express. However, it leaves the 'tool' parameter's requirement ambiguous.

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: 'Record feedback on a tool result', and spells out the rating/comment fields plus the at-least-one constraint. This clearly distinguishes it from sibling tools that search, compare, or retrieve restaurant data.

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 explicitly says to use it 'after showing the user a recommendation to log what was good or wrong,' which provides a clear trigger. It does not discuss exclusions or alternatives, but no sibling tool serves this feedback-logging purpose.

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

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

The annotations already declare readOnlyHint=true, so the description does not need to restate safety. It adds useful behavioral context beyond the schema: the Infatuation rating scale, strict rating ordering, and the implicit no-free-text constraint. This is more than a bare read, but it does not disclose pagination or error conditions (though those are partly in 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?

Three sentences, front-loaded with the core action and scale, then a clear usage directive, then a differentiation note. No wasted words; every sentence earns its place.

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

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

Given the tool has 11 parameters but a fully descriptive schema, and annotations cover read-only behavior, the description provides the essential extra context (scale and ordering). Nothing needed for correct invocation is missing—the lack of an output schema is acceptable for a list 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 already documents every parameter in detail. The description mentions 'cuisine, neighbourhood and price filters' but adds little beyond the schema; the scale reference ties to min_rating, but overall it does not compensate beyond the baseline for high coverage.

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 ('List'), a clear resource ('highest-rated restaurants'), and the rating scale (Infatuation 0–10). It also explicitly distinguishes itself from the sibling search_restaurants by noting the absence of free-text query and strict rating order, so an agent can immediately tell it apart.

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

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

The description gives an explicit use case ('Use for "best in the city" requests') and names the key alternative (search_restaurants) along with the differentiating condition. This tells the agent when to choose this tool over its closest sibling without ambiguity.

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