Search nearly 20,000 verified restaurants and bars across 24 cities plus the New Mexico region, with venue detail and curated lists.
Scored across 9 tools
fetch and get_venue both return the full Dim Hour record for a single venue, with get_venue simply adding Iconic 50 stories. search and search_venues are near-duplicates of the same catalog search, and find_places overlaps with both while claiming a different use case.
list_* and get_* tools follow a clear verb_noun pattern, but search vs search_venues are confusingly similar and fetch/find_places introduce inconsistent verb styles. The naming is readable but not predictably uniform.
Nine tools is within a reasonable range for a venue guide, but at least four of them are effectively redundant pairs. The count would be stronger if the duplicates were consolidated.
The read-only catalog surface covers discovery, search, venue details, hours, curated lists, cities, and new additions. Minor gaps exist, such as no direct tool for browsing all venues in a city or acting on reservations, but agents can work around these.
Get the full Dim Hour record for one venue by the id returned from search: description, signature dishes, address, hours, phone, happy hour, reservation platform, awards, website and Instagram.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Venue id from `search`, in the form 'city:id' e.g. 'nyc:1367' |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| url | Yes | |
| text | Yes | |
| title | Yes | |
| receipt | Yes | |
| metadata | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about the returned fields and input provenance, but does not disclose behaviors such as error handling, no-result responses, or any rate limits. No contradiction exists.
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 one compact sentence with no filler. The most important facts—what is fetched and where the id comes from—are front-loaded, followed by a concise field list.
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 one-parameter read-only fetch with an output schema, the description plus annotations are largely sufficient. The main gap is not explicitly routing the agent away from the similar-sounding sibling get_venue.
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 provides 100% coverage of the single `id` parameter, including its format 'city:id'. The description mainly restates that the id comes from `search`, adding little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the resource: the full Dim Hour record for one venue, and lists the fields returned. It also tells the agent that the id comes from `search`. However, it does not explicitly distinguish itself from sibling get_venue, which sounds like a similar fetch-by-id operation.
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 by specifying that the tool takes the id returned from `search`, which implies a post-search lookup workflow. It does not explicitly state when not to use it or name alternatives, but the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find places for a specific occasion in one city — the task-shaped entry point. Give the city and what the evening needs (a cuisine, a neighborhood, a budget, a vibe) and it returns ranked, citable venues with a freshness receipt. Prefer this over search_venues when you are planning rather than browsing.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | City name or key from list_cities | |
| limit | No | Max results, default 6 | |
| max_price | No | Max price tier 1-4 | |
| looking_for | No | What the occasion needs, e.g. 'omakase', 'patio', 'birthday dinner' | |
| neighborhood | No | Narrow to a neighborhood |
| Name | Required | Description |
|---|---|---|
| city | Yes | |
| note | No | |
| venues | Yes | |
| receipt | Yes | |
| showing | Yes | |
| total_matches | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it returns 'ranked, citable venues with a freshness receipt', which tells the agent about the output's nature and data freshness. 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?
Two sentences with no filler. The primary purpose and scope are front-loaded, followed by the input/output summary and the alternative routing. 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?
With an output schema present, the description does not need to explain return values. It covers the purpose, input hints, and usage alternative. Given five parameters (one required) and safe annotations, nothing essential is missing for an agent to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all five parameters. The description adds usage examples ('a cuisine, a neighborhood, a budget, a vibe') that map to parameters like looking_for, neighborhood, and max_price, giving the agent concrete guidance on how to populate them beyond the schema's minimal descriptions.
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 ('Find') and resource ('places') with a clear scope ('for a specific occasion in one city'). It explicitly differentiates itself from search_venues by calling itself the 'task-shaped entry point', making the purpose unambiguous and distinct from 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?
It gives explicit usage guidance: 'Prefer this over search_venues when you are planning rather than browsing.' This names the alternative and the condition that selects this tool, leaving no ambiguity about when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Opening hours for one venue, from the Dim Hour catalog. ALWAYS returns as_of and never claims to be live — hours are catalog data, not a live feed, and the receipt says how old they are. Measured 2026-09-16, 82% of venues carry hours; when a venue has none this ABSTAINS and says so rather than guessing. Confirm with the venue before relying on it.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Venue id from search_venues | |
| city | Yes | City name or key | |
| name | No | Venue name (used if id not given) |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| url | Yes | |
| city | Yes | |
| name | Yes | |
| hours | Yes | |
| receipt | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds rich behavioral context: hours are catalog data, not live; always returns as_of; may abstain for venues without hours; advises confirmation. This goes well beyond readOnlyHint annotation by disclosing staleness and abstention. 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?
Three sentences, each carrying weight: purpose, staleness, abstention, and confirmation advice. No fluff, front-loaded with purpose. Efficient and well-structured.
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 lookup tool with output schema, the description covers critical behavioral aspects (staleness, abstention) and safety (readOnlyHint). An agent has everything needed to call it correctly, including when to be cautious.
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 all parameters are already documented. The description adds no extra parameter-level detail, only contextual information about the catalog. Baseline of 3 is appropriate given 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?
States it returns opening hours for one venue, specifying it's catalog data from the Dim Hour catalog. Clear and specific, but doesn't explicitly differentiate from sibling tools like get_venue or search_venues, though the 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?
No explicit guidance on when to use this tool vs alternatives. It implies it's for opening hours, but doesn't mention using search_venues to find id or get_venue for broader venue details. The schema references id from search_venues, but the description itself lacks routing context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full Dim Hour record for one venue: description, signature dishes, address, hours, phone, happy hour, reservation platform, awards, website, Instagram, and (for Iconic 50 venues) the long-form story.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Venue id from search_venues | |
| city | Yes | City name or key | |
| name | No | Venue name (used if id not given) |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| lat | No | |
| lng | No | |
| url | Yes | |
| name | Yes | |
| tags | Yes | |
| hours | Yes | |
| phone | Yes | |
| price | No | |
| score | No | |
| story | No | |
| awards | Yes | |
| dishes | Yes | |
| iconic | No | |
| opened | No | |
| address | Yes | |
| cuisine | Yes | |
| receipt | Yes | |
| website | Yes | |
| photoUrl | Yes | |
| trending | No | |
| city_name | Yes | |
| Yes | ||
| happy_hour | Yes | |
| highlights | No | |
| price_tier | No | |
| description | Yes | |
| reservation | Yes | |
| neighborhood | Yes | |
| other_locations | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so safety behavior is covered. The description adds value by specifying exactly which fields are returned and noting the special case of Iconic 50 venues with a long-form story. This goes beyond structured annotations, though it doesn't discuss error handling or response format, which is acceptable given the output schema exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that efficiently communicates the tool's purpose and the full scope of returned data. There is no wasted phrasing, and the core action is stated first, followed by the list of fields. It is concise without sacrificing clarity.
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 tool is a straightforward fetch operation, and an output schema exists, so return-value details are not needed. The description covers the primary use case, the fields, and a special condition (Iconic 50 venues). Parameters are documented in the schema. Nothing essential for an agent to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for all three parameters (id, name, city) with descriptions. The description does not add extra meaning beyond the schema; it only reiterates 'one venue' without clarifying parameter precedence or required conditions. Since schema coverage is high, the baseline 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 a specific verb ('Get') and a clear resource ('the full Dim Hour record for one venue'), enumerating the fields returned. This explicitly distinguishes it from sibling tools like get_hours (hours only) and search_venues (listing venues), giving an agent a precise understanding of the tool's scope.
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 indicates this tool is for retrieving a single venue's full record, and the mention of 'id from search_venues' suggests a typical workflow. While it doesn't explicitly name alternatives or state when not to use it, the context makes the usage clear. A small improvement would be an explicit 'use this when you need complete details for a known venue rather than a list or hours.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the 24 cities Dim Hour covers, with the city key to pass to the other tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| cities | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds value beyond annotations by explaining that the output includes city keys intended for use with other tools, giving behavioral context about the purpose of the return value.
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 15-word sentence that is front-loaded with the action ('List') and resource, followed by purpose. No redundant words, no restating of the title, and everything 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 no-parameter, read-only listing tool, the description covers all necessary invocation context: what it lists, the scope (24 cities), and how the output is used (keys for other tools). The presence of an output schema handles return details. Nothing essential 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?
With 0 parameters, the schema trivially covers everything (100%). Baseline for 0 params is 4. The description doesn't need to add parameter semantics, but it does clarify the meaning of the output (city keys), which is relevant to how the tool is invoked and used.
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 a specific verb ('List'), a resource ('the 24 cities Dim Hour covers'), and the purpose ('with the city key to pass to the other tools'). This distinguishes it from siblings like search, get_hours, and get_venue, which are about specific operations or filters rather than a catalog of cities.
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 implies when to use it by noting the city key is 'to pass to the other tools', establishing it as a prerequisite or reference step. However, it doesn't explicitly say 'use this before other tools' or name alternatives, leaving some inference to the agent. It does provide clear context for its role.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dim Hour's editorial themed lists for a city (e.g. 'Unmarked Doors' speakeasies). Without list_id: returns all list titles. With list_id: returns that list's venues with editorial notes.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | City name or key | |
| list_id | No | A list id from the no-arg call |
| Name | Required | Description |
|---|---|---|
| id | No | |
| city | Yes | |
| note | No | |
| lists | No | |
| title | No | |
| venues | No | |
| receipt | Yes | |
| subtitle | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds value by specifying the two output modes (list titles vs. venues with editorial notes), which is behavioral context not present in the annotations. It does not contradict the annotations. Since the bar is lower given annotations, this is strong.
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 zero waste. The core purpose and the two usage modes are front-loaded, and the example clarifies the concept immediately. 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 that an output schema exists, the description does not need to explain return structure. It covers the conditional behavior, the required city parameter, and the optional list_id. For a read-only, non-destructive tool with a simple parameter set and an output schema, this is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are described ('City name or key' and 'A list id from the no-arg call'). The description adds meaningful provenance for list_id (it comes from the no-arg call), which goes beyond the schema. It also reinforces that city is required for filtering. This exceeds the baseline of 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 states a specific verb ('list'), a resource ('Dim Hour's editorial themed lists'), and a scope ('for a city'), with a concrete example ('Unmarked Doors' speakeasies). It also distinguishes the tool from sibling list_cities and list_new_venues by emphasizing the 'editorial themed' nature, so an agent can 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 provides explicit conditional usage: 'Without list_id: returns all list titles. With list_id: returns that list's venues with editorial notes.' This tells the agent the two modes. However, it does not name any alternatives or state when not to use this tool versus siblings like search or find_places, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Venues recently added to the Dim Hour catalog — across all 24 cities or one city. Use for 'what's new on Dim Hour' / new-opening alerts / weekly digests. Scored places to eat and drink come first; hotels, malls, museums and landmarks carry no score and follow them. Recency orders within each group. Dates earlier than 2026-06-06 are estimates reconstructed from history.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | Optional city name or key; omit for all cities | |
| days | No | Look-back window in days, default 30 (max 90) | |
| limit | No | Max results, default 25 |
| Name | Required | Description |
|---|---|---|
| city | Yes | |
| venues | Yes | |
| receipt | Yes | |
| showing | Yes | |
| total_new | Yes | |
| window_days | Yes | |
| feed_generated | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a safe read-only operation. The description adds meaningful behavior beyond that: ordering by scored venues first, non-scored venue groups following, recency ordering within groups, and the warning that pre-2026-06-06 dates are estimates reconstructed from history.
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 dense sentences with no filler: purpose, use cases, and behavioral caveats are each covered efficiently. Important constraints like date estimation and ordering are included without bloating the description.
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 list-style tool with no required parameters, a full input schema, and an output schema present, the description covers everything an agent needs: what it lists, when to use it, ordering semantics, and the reliability caveat about estimated dates. Nothing important 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 city, days, and limit. The description reinforces the city scope but adds no parameter-level detail beyond the schema, which matches the baseline for full schema 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 uses a specific verb and resource: listing venues recently added to the Dim Hour catalog, and distinguishes itself from general search/list siblings by focusing on newness. The scope (all 24 cities or one city) and the "what's new" positioning make its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states intended use cases: 'what's new on Dim Hour' alerts, new-opening digests, and weekly digests. It does not name alternatives or state when not to use it, so it misses the top bar, 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.
Search Dim Hour's restaurant, bar and venue catalog across all 24 cities. Returns ranked venues with a dimhour.com link for each. Use for questions about where to eat or drink — by cuisine, dish, neighborhood, city, vibe, or award.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to look for, e.g. 'best ramen in NYC', 'michelin dallas', 'rooftop bar miami' |
| Name | Required | Description |
|---|---|---|
| receipt | Yes | |
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds that results are 'ranked' and include a dimhour.com link per venue, which is useful behavioral context. However, it doesn't mention pagination, result limits, or how ranking works; these are not declared in annotations either. So description adds some value beyond annotations but isn't 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?
The description is concise: two sentences that front-load the purpose and scope, then provide usage guidance. Every sentence adds value; no fluff or redundancy. It's well-structured for quick scanning by an agent.
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 there is an output schema and only one simple parameter, the description covers essential aspects: purpose, scope, usage, and return key detail (ranked venues with links). It doesn't mention limitations like the exact list of cities or whether the search is full-text, but for a simple query tool, this is mostly sufficient. Slight gap on not listing the cities or stating that it covers all venues, but the description says 'all 24 cities' which is enough.
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 'query' parameter is already well-documented with examples. The description adds context by clarifying that the query is for where to eat or drink and lists example query typeshols, but this is largely overlapping with the schema examples. Since coverage is high, a baseline 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 searches Dim Hour's catalog of restaurants, bars, and venues across 24 cities, and mentions the return of ranked venues with links. It distinguishes itself from siblings like 'find_places' and 'search_venues' by specifying the scope (all 24 cities) and the type of content (restaurant, bar, venue catalog).
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 when-to-use guidance: 'Use for questions about where to eat or drink' and lists example facets (cuisine, dish, neighborhood, city, vibe, award). It does not explicitly state when not to use it or mention alternatives, but the purpose is specific enough to guide selection. Lacks a note on when to use siblings like 'search_venues' or 'find_places', so not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Dim Hour's restaurant, bar and venue catalog. Pass city to search one city, or OMIT city to search more than 20,000 venues across every city at once (e.g. 'best ramen anywhere', 'michelin spots'). Returns ranked matches with score (0-100 quality), price tier, neighborhood, happy-hour info, and a dimhour.com link. Free-text query matches each content word individually across cuisine, dish, vibe, and name (filler like 'best' or 'tonight' is ignored) - one strong keyword beats a sentence; combine with filters.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City name or key, e.g. 'NYC', 'dallas'. OMIT to search ALL cities at once. | |
| sort | No | Result order. Default score_desc (highest quality first). | |
| limit | No | Max results, default 10 | |
| query | No | Free text; every content word must appear in name, cuisine, neighborhood, tags, dishes, or description (filler like 'best'/'tonight' is ignored). One strong keyword beats a full sentence. | |
| fields | No | Return only these fields on each venue, to keep a result small. `id`, `name` and `url` are always included — `url` is the citation link. | |
| cuisine | No | Filter to a cuisine (substring match) | |
| max_price | No | Max price tier 1-4 ($-$$$$) | |
| min_score | No | Minimum quality score 0-100 | |
| iconic_only | No | Only 'Iconic 50' venues (NYC has these today) | |
| neighborhood | No | Filter to a neighborhood (substring match) | |
| trending_only | No | Only trending venues | |
| awards_contains | No | Only venues whose awards field matches, e.g. 'michelin', 'james beard', 'bib gourmand' | |
| happy_hour_only | No | Only venues with happy hour info |
| Name | Required | Description |
|---|---|---|
| city | No | |
| note | No | |
| scope | No | |
| venues | Yes | |
| receipt | Yes | |
| showing | Yes | |
| total_exact | Yes | |
| total_matches | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond the schema: filler words are ignored, content words are matched individually across fields, and the city-omission behavior changes scope dramatically. It also discloses that `url` is the citation link, which is useful for downstream agent behavior. Minor gap: no mention of pagination or rate limits, but the description is strong for a read-only search 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 compact and front-loaded: the core purpose and the critical city-omission behavior appear in the first two sentences, followed by return-value summary and query strategy. Every sentence earns its place, and the most decision-relevant information (scope switch) is placed first.
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 13 well-documented parameters, an output schema, and annotations covering safety, the description is complete. It explains the global-vs-local scope distinction, the matching semantics, the return payload, and the citation link. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 13 parameters thoroughly. The description adds strategic meaning (e.g., 'one strong keyword beats a sentence', 'filler like best/tonight is ignored') that complements the schema's per-parameter descriptions, but it doesn't need to repeat parameter details. Baseline 3 is appropriate because the schema carries the heavy lifting and the description adds modest strategic value.
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') and resource ('Dim Hour's restaurant, bar and venue catalog'), and distinguishes the tool's scope from siblings by explaining the city-omission behavior that searches all 20,000+ venues. It also names the return payload (ranked matches with score, price tier, neighborhood, happy-hour info, link), which makes the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: pass `city` for one city, omit `city` for a global search, and provides example queries ('best ramen anywhere', 'michelin spots'). It also explains query strategy (one strong keyword beats a sentence) and how to combine with filters, which is actionable guidance an agent can use immediately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.