Num places

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds context annotations cannot: the response always includes booked=false and mode="deeplink", no inventory is held, and a fallback phone number appears for venues without a platform. Nothing contradicts the readOnlyHint.

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 core warning is front-loaded and every sentence is functional, though the platform enumeration (OpenTable, Resy, Tock, SevenRooms, Square and others) and heavy all-caps emphasis add minor noise to an otherwise tight definition.

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?

There is no output schema, and the description compensates by naming the exact response fields (booked: false, mode: "deeplink") plus the no-platform fallback. An agent has everything needed to call it and to interpret the result safely.

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 date/time/party/place_id formats are already documented in the schema. The description only restates that these values are pre-filled into the link, adding no format or constraint detail beyond structured data — the baseline 3 for full 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 precisely what the tool produces — a pre-filled booking page (deeplink) for one place — and immediately distinguishes it from a reservation-making tool. An agent can tell exactly what it gets back versus what it would get from a real booking action.

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 when-to-use framing, explicit when-not-to (do not present as a confirmation, do not claim a table is held), and an alternative path when no booking platform exists (offer the returned phone number instead of implying the venue can't be visited).

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?

Beyond the annotations, the description discloses important behavior: answers are grounded in a verified directory, the tool never substitutes a different city, it reports lack of coverage rather than guessing, it does not book/charge/collect personal details, and the returned attribution must be displayed. These are concrete behavioral and compliance traits the agent would not know from 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 front-loaded with concrete examples and then layers scope, grounding, and compliance constraints. Despite its length, each sentence carries useful selection or invocation 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?

There is no output schema, but the description explains the return shape: a short concierge answer plus structured data for named places. It also covers attribution requirements and safety constraints, making it 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 description coverage is 100%, so all four parameters are already documented. The description reinforces that questions should be in the traveller's own words and gives an example of the `near` area, but it does not add substantial semantic detail 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 states a specific verb and resource: ask a natural-language travel question and receive a short concierge answer grounded in NUM's verified directory, including structured place data. It also clarifies scope boundaries (answers about the asked place, never substitutes another city) that make it distinguishable from sibling lookup 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?

It gives clear usage context: use it for traveller-style questions such as where to eat or which beach to visit, and it explicitly excludes bookings, charges, and personal details. It does not explicitly name alternatives like search_places or place_details, so the when-to-use guidance is strong but not fully comparative.

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 cover the safety profile (readOnly, idempotent, non-destructive); the description adds substantial context beyond them: closed places are excluded, `trading: null` means unchecked rather than closed, page size caps with and without a partner key, and a mandatory `attribution` display obligation. These are exactly the behavioral and legal traits an agent cannot infer from structured fields.

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

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

Front-loaded with the core purpose and every sentence carries information (scope, exclusions, omissions, attribution requirement). It is dense and long-ish, with several clauses chained per sentence, which slightly hurts scannability, but nothing is 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?

There is no output schema, yet the description compensates fully: it describes the item shape (search_places fields plus cuisine, lat, lng, booking_platform), the `attribution` field and the `next_cursor` field. Combined with the safety annotations, an agent has everything needed to call and consume this 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?

Schema coverage is 100% and the parameter descriptions already explain limit tiers, cursor provenance and destination slugs, so baseline would be 3. The description adds genuine value on top: results are ordered by place_id and the cursor loop terminates when next_cursor is null, which clarifies how `cursor` is actually driven.

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 — "Bulk, paged sync of every place NUM lists in one destination" — and explicitly contrasts it with the sibling search_places ("instead of searching it call by call"). An agent can distinguish it from search_places and place_details without opening any 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?

Gives an explicit when-to-use (keeping your own copy of the directory current), a named alternative it replaces (call-by-call searching), and out-of-scope siblings to route elsewhere (get_menu, get_reviews, place_details for menus/reviews/photos). Pagination is spelled out procedurally: pass next_cursor back as cursor until null.

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, so the safety profile is covered; the description still adds a lot beyond that. It discloses provenance (written by the venue in its dashboard, not scraped), price fidelity and null-price handling, empty-sections fallback, the exclusion of age-restricted items, and a mandatory attribution display obligation.

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?

Lead sentence front-loads what is returned, and the remaining sentences each carry distinct operational rules (price caveat, null handling, empty fallback, attribution). It is dense but runs long with some clause-heavy phrasing; a tighter split would read better without losing 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?

No output schema exists, so the description carries the full burden of describing the response, and it does: sections/grouping, price object with formatted amount, currency code and minor units, price:null with optional note, empty sections plus a note, and the attribution field. An agent could consume the result correctly from this text alone.

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?

There is a single parameter and schema coverage is 100%, with the schema itself explaining that place_id comes from search_places, place_details or directory_feed. The description adds no further meaning about the parameter, so the baseline of 3 for fully documented schemas 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 opens with a precise statement of the verb and resource: it returns the venue's own published menu of offerings grouped by the venue's own sections and order. It is unambiguous about what comes back, but never names a sibling (e.g. place_details or directory_feed) to differentiate, so an agent must infer when this is the right call over those 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?

Usage is implied by the content rather than stated: nothing says when to prefer this over place_details, or that a place_id must be resolved first. What guidance exists is post-call handling ('never tell a traveller their bill will be that figure', 'do not estimate', 'never invent dishes'), which is valuable but not selection 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?

Annotations already declare read-only, idempotent, closed-world, non-destructive, so the bar is lower, yet the description still adds substantial behavior: the free-tier cost model, the exact verification criterion (booked through NUM and scanned the venue's own code), exclusion of comped/partner guests, and the 5-rating publishing threshold below which all numbers are null with an explanatory `note`. That is context an agent could not infer from 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 core limitation and return shape are front-loaded in one dense paragraph with no filler topics. Minor waste in the redundant parenthetical 'free (included in the no-fee free tier)', but overall every clause carries real 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?

There is no output schema, so the description correctly documents the return surface: `external` with its `source`, `num_verified` with average/count/star distribution, the `note` on suppression, and the required `attribution`. Combined with the tier and eligibility rules, an agent has everything needed to call and correctly interpret the result.

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 the single `place_id` parameter already documents its own provenance ('From search_places, place_details or directory_feed'), so the schema does the heavy lifting. The description adds no additional meaning about the parameter itself.

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 names a specific resource and verb-equivalent ('a rating SUMMARY for one place') and immediately scopes what it is NOT: no review text, no reviewer identities. This distinguishes it from the review-like expectations set by its name 'get_reviews', though it never explicitly contrasts with sibling tools like place_details or open_places.

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

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

Usage is implied rather than stated: you fetch ratings for a known place. There is real guidance on how to use the output ('Keep the two numbers separate; do not average them together') and a hard requirement ('You MUST display the returned attribution'), but nothing says when to pick this over place_details or directory_feed.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely new behavioural context — that the list is a curated, maintained directory rather than a bulk dump — though it says nothing about ordering or size limits of the response.

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

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

Three short sentences, front-loaded with what you get, then when to call it, then the trust caveat. No sentence is redundant, and the rationale for the caveat earns its space.

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

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

For a zero-param, no-output-schema tool, the description supplies exactly what the schema cannot: the shape of the return (destination + verified place count), the intended call timing, and the data-quality guarantee. Nothing an agent needs in order to call 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?

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies no filtering arguments are needed.

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 exactly what is returned: the destinations covered plus the count of verified places in each. The second sentence implicitly separates it from search_places/open_places by framing it as a coverage lookup rather than a place lookup.

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?

'Call this FIRST when you do not know whether a city is supported' gives an explicit trigger condition, and 'cheaper than a failed search' names the alternative behaviour it replaces. The agent knows when to reach for it and when not to bother.

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 the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely non-derivable behavior: businesses with dead domains/404s are excluded entirely, results are timezone-local to the destination, and only venues with verified hours appear so a short list signals thin coverage rather than an empty city. That last point directly prevents a downstream hallucination.

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

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

Front-loaded with the core definition and the sibling routing up front, and every sentence carries information. It loses a point for redundancy: 'a short list means thin hours coverage, NOT an empty city' and 'Never tell a traveller nothing is open' make the same point twice, and the all-caps emphasis is doing work that tighter wording could.

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

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

With no output schema and no annotations covering data shape, the description compensates well on the caveats that matter most (coverage thinness, exclusion of defunct businesses). It does not describe result ordering or whether distance from 'near' is reflected, which an agent might want when picking a limit, but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, so all five parameters (near, limit, category, destination, bookable_only) are already documented in the schema. The description adds only indirect meaning — that 'destination' drives the timezone used for the open-now computation — and says nothing about limit, category, or bookable_only semantics. Baseline 3 applies 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?

States a specific verb+resource+scope: places that are open right now in a destination, with the computation basis (destination's own timezone). It also explicitly names the sibling it is not — 'Use search_places for the full directory' — so an agent can distinguish it from search_places without opening either 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?

Explicit routing: use this for what's confirmed open now, use search_places for the full directory. It also gives a hard usage constraint — never tell a traveller 'nothing is open' based on this tool — which is a when-not-to-use rule an agent could not infer from the schema.

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?

Though annotations already declare readOnly/idempotent/closedWorld, the description adds substantial behavior beyond them: the meaning of `open_now` null ("NOT that it is closed"), the strict verified-only return policy, the mandatory `attribution` display requirement for photos, and the 8-photo cap. These are the kind of traps that cause agent errors, and each is disclosed.

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 critical scoping and provenance arrive first, and nearly every clause carries actionable information (null semantics, attribution, verification policy). The cost is a single very long run-on sentence that is harder to parse than it needs to be.

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?

There is no output schema, so the description must describe return values — it does so field by field, including edge cases (null hours, missing fields meaning unknown). For a one-parameter read tool this leaves no meaningful gap for an agent to fill by guessing.

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 100% schema coverage on a single parameter, the baseline is 3. The description repeats provenance ("by place_id from search_places") which is already in the schema's parameter description, and adds no format or constraint detail beyond 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 opens with a specific verb+resource+scope ("Everything NUM holds on one place, by place_id from search_places") and then enumerates the returned fields, making it clearly distinguishable from siblings like get_reviews or booking_link, which cover subsets of this 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 gives an explicit trigger ("Use before showing a detail page or handing a traveller a phone number") and routes the agent to search_places for the id. It doesn't explicitly name a when-not or a direct alternative, so it falls short of a 5, 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?

Annotations already cover read-only/idempotent/non-destructive/closed-world, and the description adds genuinely new behavioral facts: the ranking formula (rating weighted by review volume, distance blend), the exact field set returned, the guarantee that it never invents a place, and a hard obligation to display the `attribution` string. These are obligations an agent could not infer from structured fields.

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

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

Front-loaded with purpose, then the two `near` modes, then the return contract and the attribution mandate — a logical order with no filler. The 4.8★/'unrated snack bar' illustration is slightly verbose, though it does convey the ranking blend 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?

With no output schema, the description carries the return contract and does so explicitly (name, category, area, rating, review count, phone, address, hours) plus the conditional `distance_m`. Combined with annotations covering safety and a fully documented schema, nothing an agent needs to call 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 baseline is 3; the description earns above that by explaining the consequence of each `near` form (radius cap, distance_m presence/absence) and by clarifying the quality-vs-distance ranking tradeoff. `query` and `category` are left to the schema, but that is acceptable given full 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 a specific verb and resource ('Find real, currently-operating places in a destination') and enumerates the categories covered. It is clearly distinct from siblings like place_details or open_places, which are not described as destination-scoped 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?

Gives concrete context for the two modes of `near` (coordinate → ~5 km, distance-blended ranking with `distance_m`; neighbourhood → area filter, no distance) so an agent knows which form to supply. It never names the sibling alternatives (place_details, get_reviews, open_places) or states when not to use this tool, so it stops short of a 5.

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