Local businesses for AI agents: what they sell, prices, delivery quotes, order and booking links.
Scored across 15 tools
Most tools have distinct purposes, but the set contains explicit synonyms (get_business/get_card, get_offering/get_product) and three overlapping discovery tools (find_business, search_catalog, list_cards) whose boundaries require careful reading. An agent can usually choose correctly from the descriptions, but misselection is plausible.
Names are consistently snake_case and mostly follow a verb_noun pattern (book_slot, find_business, place_order, search_catalog). The status tools order_status and request_status are noun_status rather than verb_noun, a minor deviation.
Fifteen tools is within a reasonable range for a local-business discovery, ordering, and booking assistant. The count is slightly inflated by synonym pairs and multiple discovery entry points, but each tool still maps to a meaningful operation.
The surface covers discovery, business/card retrieval, offering lookup, availability, booking, ordering, quoting, owner requests, and status polling. Minor lifecycle gaps remain, such as canceling or modifying an order/booking, but core workflows are covered.
For a service whose business’s card shows a book action with method connected and no book in its
cannot (a door the platform refuses for this account is marked there, with the reason, at every sync). Take a start_at
from check_availability (slots) and the platform books it for the named customer; the answer is the
platform’s own status (created = on the calendar awaiting confirmation · confirmed · declined). A time
the platform does not offer is an unavailable error and nothing is booked. Idempotent by
idempotency_key like place_order. Get the user’s explicit yes first.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| customer | Yes | ||
| start_at | Yes | ISO date-time with an offset, as check_availability gave it | |
| variant_id | No | the service variation when the card lists several | |
| business_id | Yes | ||
| offering_id | Yes | the service, from the card | |
| idempotency_key | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the write/non-destructive/open-world profile, and the description adds genuinely new behavior: the returned platform statuses (created/confirmed/declined), that an unoffered time yields `unavailable` and books nothing, and that idempotency only holds when `idempotency_key` is supplied. That last point sits in mild tension with idempotentHint=false, but it reads as clarifying conditionality rather than contradicting the hint.
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?
Nearly every sentence carries real information, but the ordering is off — the purpose arrives after a dense precondition full of platform-internal jargon (`book` action, `cannot` list, method `connected`) that is never defined. Backtick-heavy inline syntax and an odd mid-sentence line break make it slower to parse than its length warrants.
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 mutating, open-world tool with a nested customer object and no output schema, the description supplies the status model, the failure mode, consent requirements and retry semantics. What remains unstated is what happens after a `declined` status or whether the business in `business_id` must match the card inspected, but these are secondary.
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?
At 43% schema coverage the description must compensate, and it does for the pivotal parameters: `start_at` must be the ISO value previously returned by check_availability, and `idempotency_key` carries retry-safety semantics. It adds nothing for `note`, `variant_id` (beyond the schema's own note) or `business_id`, so coverage is partial rather than complete.
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 title plus 'the platform books it for the named customer' make the verb and resource unambiguous (booking a calendar slot for a customer), and the tool is clearly distinguished from place_order and check_availability. However, the description opens with a gating precondition about card `book` actions rather than a front-loaded purpose statement, so the core purpose is inferred from the second clause.
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 states the exact enabling condition (card shows a `book` action with method `connected` and no `book` in `cannot`), the prerequisite source of input ('Take a `start_at` from check_availability'), and a hard consent rule ('Get the user's explicit yes first'). It even covers the failure branch (unavailable error means nothing is booked), 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.
Only for a business whose card shows live_data (its items come from its connected Shopify or Square,
not from a page read). For a product: the platform’s stock right now — state: confirmed | refuted | unknown (unknown = the platform does not track stock, which is not «no»). For a service on a platform
with bookings: the free slots between from and to (default: the next 7 days), each with a
start_at that book_slot takes as it is — on the business’s own clock with its offset
(timezone names the zone; start_at_utc is the same instant). If the card’s cannot lists book,
the slots are information only and the answer says so. A business without a connection answers not_connected.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | slots: the window’s end, ISO with an offset | |
| from | No | slots: the window’s start, ISO with an offset | |
| quantity | No | how many — stock is judged against it | |
| variant_id | No | the variant (the card lists them when there are several) | |
| business_id | Yes | the business id from the card | |
| offering_id | Yes | the offering id from the card |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly/openWorld; the description adds substantive behavior well beyond them: the `state` tri-state with the explicit warning that `unknown` is not «no», the `not_connected` answer, the default 7-day window, and the guarantee that `start_at` can be passed to book_slot unchanged with `start_at_utc` as the same instant. That is exactly the kind of non-structured context annotations can't carry.
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-loads the most decision-relevant constraint (the `live_data` gate) before any field detail, and every clause carries information. It is one dense paragraph, though, and the product/service/tz clauses could be split into short lines for faster scanning.
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 still tells the agent what comes back in each branch — `state` values, `slots` with `start_at`/`start_at_utc`/`timezone`, `not_connected` — plus the informational-only caveat. Nothing needed to call it correctly or interpret the response 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 already 100%, so the baseline is 3; the description goes further by supplying the `from`/`to` default (next 7 days), clarifying that `quantity` is the stock threshold, and explaining that `start_at` is on the business's own clock with `timezone` naming the zone. Minor gap: no guidance on maximum slots returned.
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 pair (check availability) and splits it into the two concrete cases it covers: product stock state and free booking slots. It also names the gate that distinguishes it from generic catalog reads (`live_data` cards only), so an agent can tell it apart from get_product/get_offering without opening 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?
Explicitly scopes use to businesses whose card shows `live_data`, and adds the caveat that when the card's `cannot` lists `book`, returned slots are informational only — a real when-not rule. It stops short of naming a fallback sibling (e.g. what to call for a non-connected business), leaving that to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The business the user NAMED, by name matching only: case, punctuation, possessives and articles are
ignored, the words may come in any order, a part of the name is enough («Bern’s» finds «Bern’s Steak
House»), up to two typos per word, and Cyrillic is transliterated. No meaning, no ranking: found is
ordered by exactness, then — with a location — inside the radius first and nearer first. Several
places with one name all come back with their addresses; without a location and across cities the
answer asks which place. found: [] means the business is NOT in this catalogue; then
nearby_in_same_niche lists up to five cards of the trade the name suggests, every one marked
not_the_requested_business: true — never present them as the business asked for.
The best matches carry task_card (≤ 2.5 KB): time for needed_by (else hours_today), up to 5 items
under query, terms, deliver_to, and next {promise[], candidate[], action}. intent (book / order /
quote / info) chooses the action. The full menu is get_card.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | the business name as the user said it | |
| query | No | the thing under the task («red roses», «ribeye»): picks the ≤ 5 items on the card | |
| intent | No | what the user means to do with this business | |
| location | No | a postcode, a city or "lat,lng" — orders the matches by nearness and bounds the nearby list | |
| needed_by | No | when: «sunday», «tomorrow 19:00», «now», «tomorrow after 15:00» — read on the business’s own clock, three ways (on_day / open_at / slot_after) | |
| deliver_to | No | where it must be brought (a postcode is best): the card says confirmed / refuted / unknown | |
| radius_miles | No | Default 25. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply readOnlyHint and openWorldHint; the description adds substantial behavior: ordering by exactness then proximity, same-name disambiguation asking which place, `found: []` semantics, the ≤2.5 KB task_card payload with its fields, and the hard constraint that nearby_in_same_niche cards must never be presented as the requested business. That last point is an operational guardrail no structured field carries.
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-loads the identifying clause, then layers matching rules, ordering, disambiguation, empty-case handling, and payload in a logical sequence. It is dense and long, with some detail (two typos per word, Cyrillic transliteration, KB ceiling) that is useful but packed tightly.
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 well (found, task_card fields, nearby_in_same_niche). The exact envelope keys for the disambiguation response ('the answer asks which place') remain implicit, which is the only meaningful gap for a 7-parameter 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%, so the baseline is 3; the description still adds real meaning beyond the schema — location affects both ordering (exactness, then radius, then nearness) and the bounds of the nearby list, and query/intent jointly determine which items and which action appear on the card. radius_miles itself is only restated as 'Default 25'.
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?
Opens with a precise verb+resource and an explicit scope restriction: 'The business the user NAMED, by name matching only'. The matching rules (case, punctuation, possessives, word order, partial name, two typos, Cyrillic transliteration) make it unmistakable versus search_catalog or get_business.
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?
States the selecting condition clearly — use this when the user gave a name, not a meaning — and routes onward to get_card for the full menu and to nearby_in_same_niche when found is empty. It stops short of naming sibling alternatives (search_catalog, get_business) for the cases where this tool is wrong, leaving that to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SYNONYM of get_card, kept for agents that already know this name.
Free. One business in full, in the same shape for every trade: who it is (name, trade, address,
telephone, e-mail, opening hours, time zone), everything it sells (up to 60 offerings, cheapest first),
the six actions with their links and required_fields, how the thing reaches the buyer (delivery,
pickup, on_site, at_customer — with the published area, the fee and the order deadline), and how fresh
each part of that is. live_data (platform, synced_at) when the shelf is the business’s own connected
system: then every offering carries source: connector with its variants (each with inventory: units in
stock as the platform counts them, null = unknown), and an action with method
connected is taken through place_order / book_slot on this door.
Use it when the user asks «can they deliver to me», «are they open now», «what else do they do», or when search_catalog offered a business with nothing listed and the next step is a telephone call.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | the business id from search_catalog |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true and openWorldHint=false; the description goes far beyond by disclosing cost ('Free'), the response shape (up to 60 offerings cheapest-first, six actions with required_fields), fulfillment modes with area/fee/deadline, freshness metadata, and the live_data/connector/inventory semantics (null = unknown) including how connected actions route to place_order/book_slot. That is exactly the kind of behavioral context annotations cannot carry.
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 synonym relationship, cost, and scope before the dense response-shape paragraph, so an agent gets the key routing fact first. The middle paragraph is information-dense but slightly overstuffed with prose like 'how the thing reaches the buyer' and 'how fresh each part of that is' that could be tightened.
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 returns — and it does: identity fields, offering count and ordering, actions and required_fields, fulfillment modes, freshness, and the live_data variant. Combined with the documented single parameter and read-only annotations, an agent has everything needed to call and interpret it.
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 only one parameter and schema description coverage is 100% ('the business id from search_catalog'), so the schema already does the work. The description adds no further detail about the id (format, where to source it, failure behavior), so the baseline 3 for fully-covered 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?
Opens with 'SYNONYM of get_card, kept for agents that already know this name' — an explicit verb+resource plus a direct sibling relationship, so an agent immediately understands this is a full single-business read and how it relates to get_card. The following sentence enumerates exactly what 'in full' contains (identity, offerings, actions, fulfillment, freshness).
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?
Names the alternative (get_card) and the condition that selects this one ('agents that already know this name'), then gives concrete trigger phrases ('can they deliver to me', 'are they open now', 'what else do they do') plus a workflow case (search_catalog returned a business with nothing listed → next step is a telephone call). Little 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.
Free. One business in full, in the same shape for every trade: who it is (name, trade, address,
telephone, e-mail, opening hours, time zone), everything it sells (up to 60 offerings, cheapest first),
the six actions with their links and required_fields, how the thing reaches the buyer (delivery,
pickup, on_site, at_customer — with the published area, the fee and the order deadline), and how fresh
each part of that is. live_data (platform, synced_at) when the shelf is the business’s own connected
system: then every offering carries source: connector with its variants (each with inventory: units in
stock as the platform counts them, null = unknown), and an action with method
connected is taken through place_order / book_slot on this door.
Use it when the user asks «can they deliver to me», «are they open now», «what else do they do», or when search_catalog offered a business with nothing listed and the next step is a telephone call.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | the business id from search_catalog |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description adds substantial operational context: it is free, returns up to 60 offerings cheapest first, includes freshness metadata, and explains live_data, connector-sourced offerings, inventory null meaning unknown, and that connected actions route through place_order or book_slot. This is rich transparency 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 front-loaded with purpose and return shape, and the detail is justified because there is no output schema. It is dense but mostly earns its length, though parenthetical lists and phrases like 'in the same shape for every trade' add minor clutter.
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 must carry the burden of explaining return values, and it does so thoroughly: business identity, offerings, actions with required_fields, delivery/pickup/on_site/at_customer details, freshness, and live_data connector behavior. An agent has enough information to call it correctly and interpret the response.
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 id parameter has 100% schema description coverage and is already documented as the business id from search_catalog. The description reinforces that source but adds no additional format, constraints, or edge-case semantics 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 that this tool returns one business in full and enumerates the payload: identity, offerings, actions, reach methods, freshness, and live_data. It does not explicitly distinguish itself from the sibling get_business, so the verb/resource is clear but sibling differentiation is incomplete.
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 concrete use cases such as checking delivery, opening status, additional services, and following up when search_catalog returned a business with nothing listed. It names search_catalog as a related tool but does not state when to prefer or avoid sibling tools like get_business or find_business.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free. One offering in full, with ONE live request to the shop asking for that item’s price and stock
right now (live_check). Call it before you quote a price to a person: a catalogue read yesterday is
yesterday’s price. One business is asked at most once every ten minutes however many of its offerings
you open, so walking a shop is one request and not twenty; from_cache and checked_at say which.
A price list, a menu or a quote form has no single-item door to ask (ok: false with the reason) and
the stored reading stands with its date.
Hand action_url to the user as it is, ref=versum included.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | the offering id from search_catalog |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses a per-business rate limit ('at most once every ten minutes however many of its offerings you open'), the caching semantics (from_cache, checked_at), the failure mode with ok:false and a reason, and that the call is free. It also tells the agent to pass action_url through verbatim with ref=versum, which is operationally important.
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 'Free' and the core behaviour, then proceeds in a logical order: why to call it, rate limit, failure mode, and the action_url handoff. It is dense and a couple of sentences are long, but essentially 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?
With no output schema, the description does useful work naming return fields (live_check, from_cache, checked_at, ok, action_url) and the degraded path when no live check is possible. A fuller picture of the overall response shape would close the remaining gap, but an agent has enough 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?
There is only one parameter and schema coverage is 100%, with the schema already noting it is 'the offering id from search_catalog.' The description adds no further guidance on the id itself; its added value is confined to return fields rather than input semantics, so the baseline 3 holds.
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 clearly: 'One offering in full, with ONE live request to the shop asking for that item's price and stock right now.' The live-check behaviour distinguishes it from a plain catalogue read. It does not, however, distinguish itself from the sibling get_product, which an agent could reasonably confuse it with.
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 says 'Call it before you quote a price to a person: a catalogue read yesterday is yesterday's price,' and explains the fallback when a shop has no single-item endpoint (price list, menu, quote form → ok:false, stored reading stands). What's missing is any mention of when to prefer get_product or search_catalog instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SYNONYM of get_offering, kept for agents that already know this name. A «product» is just an offering whose kind is product; the same id works in both.
Free. One offering in full, with ONE live request to the shop asking for that item’s price and stock
right now (live_check). Call it before you quote a price to a person: a catalogue read yesterday is
yesterday’s price. One business is asked at most once every ten minutes however many of its offerings
you open, so walking a shop is one request and not twenty; from_cache and checked_at say which.
A price list, a menu or a quote form has no single-item door to ask (ok: false with the reason) and
the stored reading stands with its date.
Hand action_url to the user as it is, ref=versum included.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | the offering id from search_catalog |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/openWorld annotations: discloses a per-business rate limit (once every ten minutes, shared across all offerings of that business), the caching signals (`from_cache`, `checked_at`), and the soft-failure shape (`ok: false` with reason) when no single-item endpoint exists. It does not describe the response shape beyond those named fields, which keeps it just short of a 5.
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 synonym relationship, then behaviour, then the rate limit, then the `action_url` handling contract. Slightly long and fragmented ('Free.'), but nearly every clause carries operational 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?
No output schema, yet the description names the return fields an agent must act on (`live_check`, `from_cache`, `checked_at`, `ok`), plus the downstream instruction to hand `action_url` to the user intact. Only the full response shape is left unstated, which is acceptable for a single-item read.
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?
Only one parameter at 100% schema coverage, so the baseline is 3. The description adds one useful fact the schema does not — the same `id` works in both get_product and get_offering — but otherwise repeats that it comes from search_catalog.
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 the specific verb+resource ('One offering in full') and immediately disambiguates from the sibling get_offering: it is an exact synonym, and a product is an offering whose kind is `product`. An agent can pick between the two 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?
Gives an explicit call condition — 'Call it before you quote a price to a person' — with the reason (stale catalogue prices), names the synonym alternative, and describes the failure case where the live check cannot run. When-to-use, when-not, and alternative are all present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
\uD83D\uDD34 THE TASK CARD IS THE DEFAULT (≤ 2 KB): id, name, distance_miles, phone; time for needed_by (or
hours_today); items — up to 5 under query (3 for intent book), placeholders («Info», «Menu») never;
budget; terms — the deal’s conditions as published; asked — your properties (confirmed /
refuted / unknown); deliver_to; and next {promise[], candidate[], action {do: order | book |
check_slot | quote_order | call, via, url | phone | tool, needs[]}}. intent (book / order / quote / info)
shapes the items and the action. With properties the answer carries property_counts over the whole
niche here and says it plainly when none confirm. detail: "shelf" gives the older shelf card below.
needed_by is read THREE ways and says which (needed_by.read_as): on_day («sunday», «today» = the day,
not 23:59), open_at («tomorrow 19:00», «now»), slot_after («after 15:00»: open after then; a free slot is
never confirmed by hours). With max_price the order is in_budget → budget_unknown → over_budget, each by
distance.
THE OLDER SHELF CARD (detail: "shelf") CARRIES offering — the thing under query (else the cheapest main thing of the niche) with
its title, price, price_type, unit, kind, a one-line note in the page’s own words, match_level
(exact = the query’s words AND the question’s kind; kind = the kind alone; partial = the words alone, not the
kind; none = nothing) and action_url (ITS OWN
basket or page, or null). With a query and no row that matches, offering is null and offering_note says
no_match — nothing is substituted. A price written inside the title that disagrees with the price column
is shown as price_conflict with both figures and their sources. A price far from every price of its kind
across the index is suspect_price: true and never decides a budget. And
properties — what this business publishes of every fact any business on the page publishes (confirmed <value>, or refuted for an ask), with properties_unknown naming the page’s other keys it does not
(properties_on_page is the full list; a key there and not in a card’s properties is unknown for it).
All the cards of one niche inside radius_miles of location, 20 a page (limit up to 50; follow
next_page — a stable token, no duplicates, no skips). THE ORDER IS FIXED AND IS NOT A RANKING: plain
businesses first, then chains, then marketplaces (nothing is left out); inside each group by distance.
For a trade that travels to the customer (movers, plumbers …) the businesses whose PUBLISHED service
area covers the place come first, then the ones that say nothing, then the ones that refuse. You choose.
niche is a key from list_niches or your own words («barbershop», «flowers», «pizza»): the answer
always says matched_niche, confidence, matched_by and the nearest neighbours; when the words are
not clearly one niche you get NO cards and the candidates to put back to your user. query only
chooses which offering is SHOWN on each card (the cheapest main offering that fits the words; without
query, the cheapest main offering of the niche) — it never changes the order. deliver_to adds
can_deliver_to: confirmed | refuted | unknown per card from the published area; needed_by adds
open_at: yes | no | unknown from the published opening hours (which know nothing about free slots or
tables) — and FILTERS: a card leaves only when the business cannot do it by then (closed at that moment for
a trade done on site; a published deadline passed for delivery or pickup); a trade that travels to the
customer is never judged by its office hours; hours alone with an online door = unknown, kept, marked
time. EVERYTHING a filter leaves out is in excluded — id, name, one phrase from the data («closed
Sunday (Sunday: Closed)») — the first five always, the rest cut by the answer budget (excluded_cut). A
needed_by behind us is an error of the question (needed_by_in_past), not an exclusion. max_price
groups the cards in_budget · budget_unknown · over_budget (compared with FIXED prices in the same
currency, or a per-unit price with its quantity; a «from» price is a lower bound: above the budget it is
over, under it unknown), excludes nobody, and reports in_budget_count; an over_budget
card shows no offering (no_match_under_budget). properties (the argument) asks for keys with min/max/equals and adds their three-state answer
(confirmed | refuted | unknown) to the card’s properties, filtering nothing. tags FILTERS: only the
cards carrying one of the niche’s own tags (list_niches hands them out — Google’s type words such as
«steak house», «italian», or a kind on the shelf) are listed, in the same order; a free-text niche that is
itself a tag («steakhouse») applies it. Each card is ≤ 1 KB: id, name, niche, offering {id, title, price,
price_type, unit, action_url}, distance_miles, phone, type, price_range_primary, can[] (confirmed actions
with method widget | form | link | phone | connected — a form and a telephone are two entries; connected =
the business’s OWN system takes it through this door: place_order / book_slot / check_availability), can_unknown[], properties
{key: "confirmed "} (a CONDITION of the deal — a deposit, a minimum, a cancellation rule — is never
cut from a card; descriptive keys go first when the card is over its byte budget), properties_unknown [keys],
checked_at,
owner_verified, chain, marketplace, and live_data {platform, synced_at, trust} on a business whose items,
prices and stock come from its own connected system rather than a page read (confirmed by the system, not
a paid placement; the three states still hold — stock the platform does not track is unknown). total: 0 always says why (not scanned here / outside the radius
with nearest_beyond_radius / no card with the tag / niche unknown) and is logged (gap_logged).
Niches on the shelf today: restaurant (1042) · florist (316) · hair salon (274) · gas station (253) · barber (230) · pizza (202) · nail salon (201) · print shop (180) · grocery (168) · bakery (159) · oil change (148) · pharmacy (147) · medical clinic (145) · storage (142) · ev charging station (141) · catering (138) · bar (124) · pet grooming (123) · auto repair (120) · hotel (107) · optometrist (106) · fuel delivery (100) · clothing store (96) · tire shop (95) · beauty salon (94) · liquor store (92) · massage (92) · auto parts store (91) · parking (91) · veterinarian (88) · coffee shop (86) · furniture (82) · truck tire service (82) · locksmith (80) · movers (80) · party rental (79) · towing (79) · event venue (78) · plumber (78) · body shop (77) · shipping and packing store (76) · dentist (75) · electrician (73) · appliance repair (72) · phone repair (67) · real estate agent (66) · jewelry (65) · car wash (64) · notary (64) · urgent care (64) · insurance agent (63) · pool service (63) · tutoring (63) · boat rental (62) · accountant (60) · car rental (59) · garden center and nursery (59) · hvac (59) · chiropractor (57) · jewelry and watch repair (57) · photographer (57) · music lessons (56) · physical therapy (56) · wedding planner (56) · tattoo studio (55) · travel agency (54) · septic and well service (53) · roofer (52) · tailor (52) · bike repair (51) · landscaping (51) · pressure washing (49) · dance studio (48) · elder care and home care (48) · auto glass (47) · fishing charter and boat tours (46) · ice cream shop (46) · lawyer (46) · mattress (42) · tree service (41) · pet boarding (40) · yoga (40) · handyman (39) · window cleaning (39) · carpet cleaning (38) · driving school (38) · dry cleaner (38) · hardware store (36) · windows and doors (35) · cleaning (34) · daycare (34) · car dealer (32) · thrift store (32) · garage door (30) · pet store (27) · funeral home (26) · butcher and seafood market (25) · dog walking and pet sitting (25) · medical equipment rental (25) · truck repair (24) · junk removal (20) · swim school (20) · bike and jet ski rental (15) · golf course (15) · juice bar (15) · med spa (14) · cinema (13) · general contractor (13) · escape room (11) · kids play center (11) · painter (11) · pest control (11) · meal prep (10) · tennis and sports courts (10) · bowling and billiards (8) · shooting range (8) · babysitting and nanny agency (7) · specialty grocery and farmers market (6) · computer repair (4) · kids sports and activities (4) · martial arts (4) · taxi and transfer service (4) · shoe repair (3) · museum (2) · aquarium (1) · butcher (1) · motel (1) · transportation service (1); known but not scanned anywhere: candle shop, confectionery, garden center, gift shop, party shop, toy store.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | the `next_page` token of the previous answer | |
| tags | No | FILTER by the niche’s own tags, as list_niches gives them («steak house», «italian», «dish»): a card without one of them is left out; the order does not change. Spelling is folded («steakhouse» = «steak house»). | |
| limit | No | cards per page. Default 10. | |
| niche | Yes | a niche key from list_niches, or the trade in your own words | |
| query | No | words that pick the offering SHOWN on each card («red roses», «balayage»); the order of the cards does not depend on it | |
| detail | No | task (default): the short card under the task; shelf: the older ≤ 1 KB shelf card | |
| intent | No | what the user means to do: shapes the items shown and the ONE action in `next` (book → book / check_slot / call; order → order / quote_order / call; quote → quote_order / call; info → call) | |
| location | Yes | a 5-digit US postcode (best), a city ("Tampa, FL") or "lat,lng". Required: the shelf is a place. | |
| max_price | No | the most for ONE offering, in USD: groups the cards in_budget · budget_unknown · over_budget (nobody is left out) and picks the shown offering inside it (exact, then kind, then partial matches); fixed prices compare; a «from» price above the budget is over, under it budget_unknown | |
| needed_by | No | when: «sunday» / «today» / «2026-11-08» (open that day), «tomorrow 19:00» / «now» (open at that minute), «after 15:00» / «tomorrow after 3pm» (open after then; a free slot only where the source knows slots) — on each business’s own clock; adds `time` {asked_as, day, hours, state, why} and LEAVES OUT only the cards refuted for the way the trade is done (see excluded) | |
| deliver_to | No | where it must be brought (a postcode is best): adds can_deliver_to per card — confirmed when the published area names the place, refuted when the business says no, unknown otherwise | |
| properties | No | facts to read off each card without filtering: property_states {key: "confirmed <value>" | "refuted" | "unknown"} | |
| radius_miles | No | Default 10. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, openWorldHint), the description discloses a great deal an agent could not otherwise know: the order is fixed and explicitly NOT a ranking (plain → chain → marketplace, then distance), traveling trades sort by published service-area coverage, every filtered-out card appears in `excluded` with a reason phrase, `total: 0` is always explained and logged (`gap_logged`), a past `needed_by` is a caller error (`needed_by_in_past`) rather than an exclusion, and price conflicts / suspect prices are flagged and never decide a budget.
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 text is roughly 1,500+ words in a single undifferentiated block, opening with card-field minutiae instead of the tool's purpose. Most damaging, it inlines a ~140-entry niche inventory with counts and a 'known but not scanned' tail despite explicitly directing the agent to `list_niches` — pure redundancy that crowds out the load-bearing sentences.
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 13-parameter, no-output-schema tool this is more than complete: return shapes (`next`, `excluded`, `property_counts`, `live_data`, `checked_at`), ordering rules, three-state property answers, byte budgets, and reason codes for empty results are all spelled out. An agent has everything needed to invoke it correctly, even if it must wade through the volume.
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 goes further by explaining cross-parameter behavior the schema can't — `needed_by` parsed three ways with the `read_as` it reports, `max_price` ordering in_budget/budget_unknown/over_budget with the 'from'-price lower-bound rule, `query`-vs-order independence, and `properties` producing `property_counts`. It largely restates per-parameter text that already lives in the schema, so it does not reach a 5.
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 does state a specific verb and resource — 'All the cards of one niche inside `radius_miles` of `location`, 20 a page' — with pagination semantics and a reference to `list_niches` for niche keys, which separates it from the single-entity siblings (get_card, get_business). However, the actual purpose sentence is buried ~800 words in, after a long block about card field contents, so an agent's first impression is 'output format documentation' rather than 'list businesses of a trade near a place'.
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 dense, explicit guidance on when each mode applies: `detail: "shelf"` for the older card, `query` only selects the shown offering and never reorders, `needed_by` filters only refutable cards, `max_price` excludes nobody but groups, `tags` filters but preserves order, `properties` filters nothing. What is missing is any comparison against the query-style siblings (find_business, search_catalog) — the agent is never told when to reach for this list tool versus those.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The niches (trades) this catalogue has read, each with its key, its other names, its TAGS (Google’s own
type words and the kinds of thing on its shelves — e.g. a restaurant niche tagged with the cuisines its
businesses carry) and how many businesses and cards it holds. With location: only the niches that have
cards inside the radius, plus known_not_scanned_here — niches the catalogue knows but has not read
there (a honest «no» before you search). Use a key, a name or a tag as niche in list_cards.
conditions: the keys of the deal (a deposit, walk-ins, emergency service, new patients…) with how many
cards confirm each and how many say nothing — the three most published per niche, every one with niche.
Every niche
carries coverage: complete (every city passed cell by cell, no cell at Google’s cap) or partial with
count (the cards it holds) and why — a partial niche may have businesses the catalogue has not read.
Current coverage: restaurants in Apollo Beach, Carrollwood, Gibsonton, Lutz (+10 more); florists in Austin, Aventura, Brickell, Gibsonton (+19 more); jewelrys in Tampa; furnitures in St. Petersburg, Tampa; nail salons in Apollo Beach, Gibsonton, Lutz, Riverview (+3 more); jewelry and watch repairs in St. Petersburg, Tampa, Temple Terrace; bike repairs in Apollo Beach, St. Petersburg, Tampa; mattresss in St. Petersburg, Tampa; clothing stores in Carrollwood, Hollywood, Tampa; party rentals in Lutz, Riverview, Ruskin, Tampa; hair salons in Gibsonton, Riverview, Ruskin, St. Petersburg (+3 more); garden center and nurserys in Ruskin, St. Petersburg, Tampa; pet groomings in Riverview, St. Petersburg, Tampa; car dealers in Tampa; boat rentals in St. Petersburg, Tampa; truck repairs in Tampa; tailors in St. Petersburg, Tampa; liquor stores in Lutz, Tampa; shooting ranges in St. Petersburg, Tampa; unknown trades in Tampa; barbers in Apollo Beach, New York, Riverview, St. Petersburg (+2 more); massages in St. Petersburg, Tampa, Temple Terrace; phone repairs in Apollo Beach, Tampa; landscapings in St. Petersburg, Tampa; plumbers in Brandon, Gibsonton, Lutz, Riverview (+1 more); medical equipment rentals in Gibsonton, Riverview, Tampa; coffee shops in Chicago, Tampa; carpet cleanings in Tampa; moverss in Tampa; pizzas in Tampa, Temple Terrace; bakerys in Tampa, Temple Terrace; medical clinics in Apollo Beach, Tampa; print shops in Tampa, Temple Terrace; accountants in Greater Northdale, Lutz, Tampa, Temple Terrace; HVACs in Apollo Beach, St. Petersburg, Tampa; dentists in Apollo Beach, Tampa; meal preps in St. Petersburg, Tampa; spas in St. Petersburg, Tampa, Temple Terrace; optometrists in Apollo Beach, Tampa; roofers in Tampa, Temple Terrace; elder care and home cares in Tampa; electricians in Apollo Beach, Odessa, Tampa; locksmiths in Greater Northdale, Riverview, Tampa; cleanings in Riverview, St. Petersburg, Tampa; veterinarians in Lutz, St. Petersburg, Tampa, Thonotosassa; oil changes in Gibsonton, Riverview, Ruskin, Tampa; wedding planners in St. Petersburg, Tampa; tree services in Odessa, St. Petersburg, Tampa; car rentals in Tampa; yogas in Apollo Beach, Ruskin, St. Petersburg, Tampa; hair-salons in St. Petersburg, Tampa, Temple Terrace; cafes in St. Petersburg, Tampa; chiropractors in Tampa; pressure washings in Apollo Beach, Tampa, Temple Terrace; barber-shops in Riverview, St. Petersburg, Tampa; shipping and packing stores in Tampa; kids play centers in Brandon, Tampa; travel agencys in St. Petersburg, Tampa; event venues in Lutz, Tampa; appliance repairs in Brandon, Clearwater, Gibsonton, Riverview (+2 more); handymans in Apollo Beach, St. Petersburg, Tampa; daycares in St. Petersburg, Tampa; physical therapys in St. Petersburg, Tampa; notarys in Gibsonton, Riverview, Sun City Center, Tampa; pool services in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; septic and well services in Apollo Beach, Gibsonton, Lutz, Tampa; caterings in Riverview, Tampa, Temple Terrace; driving schools in Tampa, Town 'N' Country; photographers in Apollo Beach, St. Petersburg, Tampa; insurance agents in St. Petersburg, Tampa; body shops in Tampa; specialty grocery and farmers markets in St. Petersburg, Tampa; pet boardings in Apollo Beach, Tampa; music lessonss in St. Petersburg, Tampa; auto glasss in Tampa; painters in Kissimmee, St. Petersburg, Tampa; dance studios in Tampa; car washs in Riverview, Tampa, Temple Terrace; tattoo studios in Tampa; braids-locss in Tampa; real estate agents in Apollo Beach, St. Petersburg, Tampa, Westchase; funeral homes in Tampa; juice bars in Riverview, Tampa; cleaning services in Ruskin, Tampa; med spas in Tampa; butcher and seafood markets in Tampa; fishing charter and boat tourss in Ruskin, St. Petersburg, Tampa; tutorings in Gibsonton, St. Petersburg, Tampa, Westchase; fuel deliverys in Gibsonton, Riverview, Tampa; golf courses in St. Petersburg, Tampa; auto repairs in Tampa; lawyers in Tampa; storages in Tampa; truck tire services in Tampa; pet stores in Tampa; dog walking and pet sittings in Riverview, Tampa; towings in St. Petersburg, Tampa; junk removals in St. Petersburg, Tampa; bowling and billiardss in St. Petersburg, Tampa; garage doors in Tampa; taxi and transfer services in Tampa; parkings in Tampa; bike and jet ski rentals in Apollo Beach, Tampa; shoe repairs in Tampa; babysitting and nanny agencys in Tampa; EV charging stations in Tampa; bars in Tampa; gas stations in Gibsonton, Riverview, Sun City Center; window cleanings in Gibsonton, Riverview, St. Petersburg, Tampa; hotels in Tampa; urgent cares in Temple Terrace; kids sports and activitiess in St. Petersburg, Tampa; swim schools in Tampa; aquariums in Tampa; cinemas in Riverview, Ruskin, Tampa; dry cleaners in Tampa; grocerys in Tampa; thrift stores in Tampa; tennis and sports courtss in St. Petersburg; escape rooms in Tampa.
| Name | Required | Description | Default |
|---|---|---|---|
| niche | No | one niche (a key or your words): only it, with EVERY key of the deal it publishes (`conditions`: {key: {confirmed, refuted, unknown}} over the cards inside the radius) — the key to pass as list_cards `properties` | |
| location | No | a 5-digit US postcode, a city ("Tampa, FL") or "lat,lng". Optional: without it every niche is listed with its totals. | |
| radius_miles | No | How far from the location counts as «here». Default 10. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the description earns credit for adding semantics rather than safety: coverage is either `complete` (every city passed cell by cell, no cell at Google's cap) or `partial` with `count` and `why`, and partial niches may hold unread businesses. That is real behavioral context about data trustworthiness that no annotation conveys.
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 first portion is well front-loaded, but the trailing wall of coverage text — dozens of trades with city lists, typos, and truncated '+10 more' counts — is unstructured, unparseable, and likely to go stale on every scan. It crowds out the operationally useful guidance at a large token cost.
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 three-optional-param read tool with no output schema, the description explains both result shapes (plain totals vs. radius-filtered with known_not_scanned_here), the conditions sub-object, and coverage labels. Only return ordering or pagination is unaddressed, which is minor here.
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 baseline is 3, but the description adds meaning: with `niche` it returns EVERY deal key with confirmed/refuted/unknown counts, and `niche` keys are explicitly the values to pass to list_cards `properties`. `location` and radius effects are restated in context of what comes back.
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 the specific resource (niches/trades the catalogue has read) and enumerates the fields each carries: key, other names, tags, and business/card counts. It also distinguishes itself from list_cards by telling the agent to feed a returned key, name, or tag into that tool's `niche` parameter.
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?
Explains the two modes clearly: without `location` every niche is listed with totals; with `location` only niches holding cards inside the radius appear, plus `known_not_scanned_here` as an explicit pre-search negative check. It lacks a stated when-not, but the mode split and the hand-off to list_cards give solid routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The status of an order_id from place_order or book_slot, asked of the platform again when it is not final (paid? confirmed? declined by the owner?). A Shopify cart link answers unknown — payment is on Shopify’s side and the shop does not report it here. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint and openWorldHint, so the bar is lower, and the description still adds real value: it enumerates candidate status outcomes (paid, confirmed, declined by owner), explains the `unknown` sentinel for Shopify carts and why, and notes the call is free. That is more than the annotations convey.
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 dense sentences, with the core purpose front-loaded and the caveat and cost appended. Every clause carries information; 'Free' is terse but genuinely useful for a polling tool, though it reads slightly clipped.
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 does the work of sketching return values (status words plus an `unknown` case), which is the main thing an agent needs to interpret a response. It stops short of promising exhaustive status enumeration, but is sufficient to call and read the result 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 0%, so the description must carry the meaning of `order_id` — and it does, defining it by provenance (the id returned by place_order or book_slot). The uuid format is left to the schema, which is reasonable since the schema declares 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?
States a specific verb-resource pair: it retrieves the status of an `order_id`. Crucially, it names the two sibling tools that produce such an id (place_order, book_slot), so an agent can immediately distinguish it from quote_order, get_product, and the other catalog 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?
Gives a clear trigger — re-poll the platform 'when it is not final' — and bounds the input to ids from place_order or book_slot. It also flags a specific non-applicable case (Shopify cart links yield `unknown`), which functions as a when-not. It does not mention rate limits or polling cadence, keeping it just 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.
For a business whose card shows an order action with method connected. Shopify: returns the shop’s
own checkout link with these items and quantities already in the cart (status: unknown, mode: cart)
— no customer data is needed or passed, the buyer gives their details and pays on Shopify, and nothing
exists on the shop until they do. Square: an order with a payment link (no customer data either).
WhatsApp: a message to the owner (customer phone or email). Returns order_id, status, checkout_url
— HAND THE CHECKOUT URL TO THE USER AS IT IS: that page takes the money, Versum holds no card and charges
nothing. Stock is checked live first on a platform that tracks it; «not in stock» is an unavailable
error and no order or link is given. Send an idempotency_key of your own and keep it for a retry: the
same key returns the same answer and the same link (repeated: true), never a second one. Lines name
offerings by their card id (and variant_id when the card lists several). status: unknown (a cart
link: payment is on the platform’s side) · created (the platform holds it) · pending_owner (WhatsApp) ·
confirmed · declined · failed. Get the user’s explicit yes before calling this.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | a note to the business, in the user’s words (not passed on a Shopify cart link) | |
| lines | Yes | ||
| customer | No | only where the platform needs it (WhatsApp); omit for Shopify and Square | |
| business_id | Yes | ||
| idempotency_key | No | your own key for this order; reuse it on a retry |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations present the bar is lower, yet the description adds substantial context: nothing exists on the shop until the buyer pays, Versum holds no card and charges nothing, no customer data is needed for Shopify/Square, a live stock check precedes order creation and an `unavailable` error means no link is issued, and the full `status` vocabulary is spelled out. The only tension is `idempotentHint: false` versus the claim that reusing the same `idempotency_key` "never a second one" — defensible since a call without the key duplicates the order, but worth noting.
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?
Nearly every sentence carries load — platform branches, return fields, error behavior, idempotency — with little padding. Structure is weaker than the content: it is a dense run-on with backticks, dashes and middots, and the critical confirmation instruction ("Get the user's explicit yes") is buried at the very end rather than 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?
With no output schema, the description fully carries the return contract: `order_id`, `status`, `checkout_url`, the meaning of each status value including `repeated: true` on idempotent retries, and the `unavailable` error case. An agent has everything it needs to call this correctly and hand the result to the user.
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 only 60%, but the description compensates well: lines reference offerings by card id and need `variant_id` only when the card lists several, `customer` is required only where the platform needs it (WhatsApp) and must be omitted for Shopify/Square, `note` is dropped on Shopify cart links, and `idempotency_key` is user-supplied and reused on retry. This is meaning the schema does not carry.
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+resource (place an order in the business's own system) and enumerates exact per-platform semantics (Shopify cart link, Square payment link, WhatsApp message to owner). It never names the sibling tools it is not, however, so an agent must infer the split with quote_order, check_availability and order_status from their names alone.
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 a clear precondition — the business's card must show an `order` action with method `connected` — and an explicit gating rule: "Get the user's explicit yes before calling this." It stops short of the alternative path (e.g. use quote_order first to preview, or check_availability to verify stock rather than relying on the live check) and names no sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free. For a business on WooCommerce or Shopify (its card says platform), with no owner connection:
puts the offering in a cart session of OUR OWN on the shop’s public cart, gives it the delivery address and
reads back what the shop itself computes — delivery.state confirmed | refuted | unknown for that address,
options (each delivery / pickup with its price, tax and the whole order’s total), tax, total,
currency, and delivery_date ONLY when the shop publishes one in its standard fields (otherwise
unknown — ask the shop). Nothing is ordered, the cart is emptied afterwards, and only the address is
sent (no name, e-mail or phone; nothing is stored). Shopify’s public cart has no tax: tax.state is unknown
and the total is before tax. A shop whose cart is closed answers not_available with the reason; so does
any other platform. When the shop needs more of the address than you gave, status: needs_address names
the missing fields. A required add-on the page asks for («a card with a message?») is answered «no»
unless you pass options; options_used says what was chosen. Hand order_url to the user to buy.
| Name | Required | Description | Default |
|---|---|---|---|
| items | No | several different items of the SAME shop in one cart (delivery and tax on the whole order); offering_id is then the first of them | |
| options | No | answers to the product page’s own add-on questions; the rest are answered «no» | |
| quantity | No | default 1 | |
| deliver_to | Yes | where it must be brought: "33139", "Miami Beach, FL 33139", or {postcode, state, city, address_1} | |
| variant_id | No | a variant id from the card when it lists several | |
| offering_id | Yes | the offering id from a card |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already present, the description adds substantial behavioral context: it creates a temporary cart session of its own, empties the cart afterwards, sends only the address, stores nothing, and reports specific failure states such as `not_available` and `needs_address`. It also discloses platform-specific tax limitations for Shopify and the add-on defaulting behavior.
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 content is mostly relevant and front-loads key constraints, but it is delivered as a dense paragraph with many clauses and parentheticals. Structuring the platform constraints, side effects, and return states separately would make it easier to scan.
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 carries the full burden of explaining returns, and it does: it documents `delivery.state`, `options`, `tax`, `total`, `currency`, `delivery_date`, `status: needs_address` with `missing`, and `options_used`. It also explains failure responses such as `not_available`, making it complete for an agent to call and interpret results.
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 still adds meaning about `options` answering the product page's add-on questions, defaulting unanswered add-ons to 'no', and `options_used` reporting what was chosen; it also clarifies that `deliver_to` sends only the address.
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 purpose: obtaining a delivered price quote from the shop's own cart without placing an order. It distinguishes itself from ordering by saying 'Nothing is ordered' and directing the user to `order_url` to buy, which separates it from `place_order`.
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 applicability conditions: free, for WooCommerce or Shopify businesses with no owner connection, and notes that closed carts or other platforms return `not_available`. It does not explicitly name sibling alternatives like `check_availability` or `place_order`, but its 'nothing ordered' and 'hand `order_url` to the user to buy' guidance provides practical routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delivery (sent · link_given · expired · failed) and the owner’s outcome (declined · other_time + proposal · available = free but NOT booked · confirmed = booked). confirmed: true only when the owner booked it.
| Name | Required | Description | Default |
|---|---|---|---|
| request_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context that annotations cannot: the exact meaning of each outcome, especially the subtle distinction that `available` means free but NOT booked and `confirmed: true` only when the owner actually booked. It does not say what state a fresh/unanswered request reports, but the status semantics are a real contribution.
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?
Very short and front-loaded, with the delivery states leading and the outcome states following. The notation-heavy style (`declined` · `other_time` + proposal) is dense but every token carries a status meaning; only slight cost is readability.
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 usefully explains the returned status vocabulary, which is the most important completeness gap for this tool. However, it omits the pending/no-response state, the source of request_id, and error behavior for an unknown request, so an agent cannot fully anticipate outcomes.
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 0% and the single required parameter is only typed (string, uuid format). The description never mentions request_id, where to obtain it (presumably from request_to_owner's response), or what happens if an unknown id is supplied. The one parameter that determines whether the call succeeds is left entirely to the schema type.
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 definition makes clear this is a status-lookup on a request-to-owner, enumerating both the delivery states (sent/link_given/expired/failed) and the owner's outcome states. That vocabulary implicitly distinguishes it from the sibling request_to_owner (which creates the request) and book_slot, though the description itself never states the retrieving verb explicitly.
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/when-not guidance and no named alternative. The only usage signal is the implicit workflow: check this after request_to_owner. An agent must infer that from the name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
For a business that takes requests through Versum (a verified owner with Telegram, e-mail or WhatsApp). Sends what,
when, how many, which branch and the person’s name and contact. Requires idempotency_key: retrying with the same key
returns the same request. Answers: sent (delivered to the owner), link_given (WhatsApp: give whatsapp_url to the
person — THEY send it; nothing is sent yet), or no_channel with the business’s other doors. Then poll request_status.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | YYYY-MM-DD, the business’s local date | |
| note | No | ||
| time | No | HH:MM, the business’s local time | |
| what | Yes | what the person wants (a service, an item, a table for 4 …) | |
| branch | No | which location, when the business has several | |
| customer | Yes | ||
| quantity | No | ||
| business_id | Yes | the business id from the card | |
| idempotency_key | Yes | your own key for this request; the same key never makes a second one |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by explaining idempotency semantics ('retrying with the same key returns the same request') and enumerating the three outcomes with required follow-up actions, including the non-obvious link_given case where nothing is sent and the agent must hand over whatsapp_url. This is exactly the behavioral context annotations cannot carry.
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?
Dense and front-loaded, with the precondition first and the outcome branches packed into one tight sentence. Slightly crowded for a single paragraph but no sentence 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?
For a 9-parameter mutation with a nested customer object and no output schema, the description covers the outcome shapes and the follow-up call, which is what an agent most needs. Minor gaps remain around what `note` is for and what happens on validation or channel failures.
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 67% schema coverage, the description compensates by mapping the core payload in plain language ('what, when, how many, which branch and the person's name and contact') and explaining the required idempotency_key. It leaves `note` and the `whatsapp_url` return unused, so not fully exhaustive.
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 ('Sends' a request to the verified owner) and the title explicitly distinguishes it from a booking ('not a booking until the owner confirms'). An agent can tell this apart from book_slot and place_order without opening a 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 a clear precondition ('For a business that takes requests through Versum... with Telegram, e-mail or WhatsApp') and a next step ('Then poll request_status'). It does not name book_slot or place_order as alternatives, so the boundary against sibling tools is only implied by the title.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free search of local US businesses by MEANING (current coverage: restaurants in Apollo Beach, Carrollwood, Gibsonton, Lutz (+10 more); florists in Austin, Aventura, Brickell, Gibsonton (+19 more); jewelrys in Tampa; furnitures in St. Petersburg, Tampa; nail salons in Apollo Beach, Gibsonton, Lutz, Riverview (+3 more); jewelry and watch repairs in St. Petersburg, Tampa, Temple Terrace; bike repairs in Apollo Beach, St. Petersburg, Tampa; mattresss in St. Petersburg, Tampa; clothing stores in Carrollwood, Hollywood, Tampa; party rentals in Lutz, Riverview, Ruskin, Tampa; hair salons in Gibsonton, Riverview, Ruskin, St. Petersburg (+3 more); garden center and nurserys in Ruskin, St. Petersburg, Tampa; pet groomings in Riverview, St. Petersburg, Tampa; car dealers in Tampa; boat rentals in St. Petersburg, Tampa; truck repairs in Tampa; tailors in St. Petersburg, Tampa; liquor stores in Lutz, Tampa; shooting ranges in St. Petersburg, Tampa; unknown trades in Tampa; barbers in Apollo Beach, New York, Riverview, St. Petersburg (+2 more); massages in St. Petersburg, Tampa, Temple Terrace; phone repairs in Apollo Beach, Tampa; landscapings in St. Petersburg, Tampa; plumbers in Brandon, Gibsonton, Lutz, Riverview (+1 more); medical equipment rentals in Gibsonton, Riverview, Tampa; coffee shops in Chicago, Tampa; carpet cleanings in Tampa; moverss in Tampa; pizzas in Tampa, Temple Terrace; bakerys in Tampa, Temple Terrace; medical clinics in Apollo Beach, Tampa; print shops in Tampa, Temple Terrace; accountants in Greater Northdale, Lutz, Tampa, Temple Terrace; HVACs in Apollo Beach, St. Petersburg, Tampa; dentists in Apollo Beach, Tampa; meal preps in St. Petersburg, Tampa; spas in St. Petersburg, Tampa, Temple Terrace; optometrists in Apollo Beach, Tampa; roofers in Tampa, Temple Terrace; elder care and home cares in Tampa; electricians in Apollo Beach, Odessa, Tampa; locksmiths in Greater Northdale, Riverview, Tampa; cleanings in Riverview, St. Petersburg, Tampa; veterinarians in Lutz, St. Petersburg, Tampa, Thonotosassa; oil changes in Gibsonton, Riverview, Ruskin, Tampa; wedding planners in St. Petersburg, Tampa; tree services in Odessa, St. Petersburg, Tampa; car rentals in Tampa; yogas in Apollo Beach, Ruskin, St. Petersburg, Tampa; hair-salons in St. Petersburg, Tampa, Temple Terrace; cafes in St. Petersburg, Tampa; chiropractors in Tampa; pressure washings in Apollo Beach, Tampa, Temple Terrace; barber-shops in Riverview, St. Petersburg, Tampa; shipping and packing stores in Tampa; kids play centers in Brandon, Tampa; travel agencys in St. Petersburg, Tampa; event venues in Lutz, Tampa; appliance repairs in Brandon, Clearwater, Gibsonton, Riverview (+2 more); handymans in Apollo Beach, St. Petersburg, Tampa; daycares in St. Petersburg, Tampa; physical therapys in St. Petersburg, Tampa; notarys in Gibsonton, Riverview, Sun City Center, Tampa; pool services in Apollo Beach, St. Petersburg, Tampa, Temple Terrace; septic and well services in Apollo Beach, Gibsonton, Lutz, Tampa; caterings in Riverview, Tampa, Temple Terrace; driving schools in Tampa, Town 'N' Country; photographers in Apollo Beach, St. Petersburg, Tampa; insurance agents in St. Petersburg, Tampa; body shops in Tampa; specialty grocery and farmers markets in St. Petersburg, Tampa; pet boardings in Apollo Beach, Tampa; music lessonss in St. Petersburg, Tampa; auto glasss in Tampa; painters in Kissimmee, St. Petersburg, Tampa; dance studios in Tampa; car washs in Riverview, Tampa, Temple Terrace; tattoo studios in Tampa; braids-locss in Tampa; real estate agents in Apollo Beach, St. Petersburg, Tampa, Westchase; funeral homes in Tampa; juice bars in Riverview, Tampa; cleaning services in Ruskin, Tampa; med spas in Tampa; butcher and seafood markets in Tampa; fishing charter and boat tourss in Ruskin, St. Petersburg, Tampa; tutorings in Gibsonton, St. Petersburg, Tampa, Westchase; fuel deliverys in Gibsonton, Riverview, Tampa; golf courses in St. Petersburg, Tampa; auto repairs in Tampa; lawyers in Tampa; storages in Tampa; truck tire services in Tampa; pet stores in Tampa; dog walking and pet sittings in Riverview, Tampa; towings in St. Petersburg, Tampa; junk removals in St. Petersburg, Tampa; bowling and billiardss in St. Petersburg, Tampa; garage doors in Tampa; taxi and transfer services in Tampa; parkings in Tampa; bike and jet ski rentals in Apollo Beach, Tampa; shoe repairs in Tampa; babysitting and nanny agencys in Tampa; EV charging stations in Tampa; bars in Tampa; gas stations in Gibsonton, Riverview, Sun City Center; window cleanings in Gibsonton, Riverview, St. Petersburg, Tampa; hotels in Tampa; urgent cares in Temple Terrace; kids sports and activitiess in St. Petersburg, Tampa; swim schools in Tampa; aquariums in Tampa; cinemas in Riverview, Ruskin, Tampa; dry cleaners in Tampa; grocerys in Tampa; thrift stores in Tampa; tennis and sports courtss in St. Petersburg; escape rooms in Tampa). Use it when you do not know
which niche the user’s words belong to; verify what comes back on the cards (get_card), and for a known
niche prefer list_cards, which lists every card in a fixed order instead of ranking a few. An empty
answer says why and carries gap_logged: true.
One sentence — what, where, when, budget — returns business cards with prices, availability and
order/booking links. Data comes from the businesses’ own websites; owner-verified cards are marked.
Call it whenever your user wants to buy, order, book, hire or get anything from a local business. Searching costs nothing, so search before you say you cannot help. Outside the coverage above the answer is empty and says so, which is itself useful — it is logged as a gap so the scanner learns where to go next. This tool neither buys nor reserves anything.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many BUSINESS CARDS to return. Default 10. | |
| query | Yes | What the user wants, IN THEIR OWN WORDS AND THEIR OWN LANGUAGE: "red roses", "steakhouse", "funeral flowers", "movers 2 bedroom", "ramo de rosas", or the same question in a language not written in the Latin alphabet. Matched by MEANING as well as by words, through one multilingual model — so do NOT translate for us and do NOT list synonyms yourself. A place, a date, a budget and a delivery word may be left in (they are parsed out), but the fewer extra words the better the match. | |
| detail | No | compact (default): the business, its 1–2 best offerings with prices and links, what can be done, and the date it was read — a few hundred bytes a card. full: everything, including images, the sentence each price was read from, variants, all four fulfilment modes with published areas, opening hours and per-field evidence. Ask for full only when the user has chosen a business and you need its delivery area or its hours. | |
| location | No | Where the user is, or where it must happen. A 5-DIGIT US POSTCODE IS BEST ("33139"): it is the only form a business’s own published delivery or service area can be matched against exactly, so a postcode gets you `how: "zips"` and a city name gets you a distance. A city ("Orlando, FL") or "lat,lng" also work. OPTIONAL IN NAME ONLY — without it nothing is measured and nothing is narrowed, and the answer comes back with `needs` carrying the question to put to your user. "near me" is not a location: ask which town. | |
| max_price | No | The most the user will pay for ONE offering, in USD, compared against the lowest number the business published — so "from $45" passes "under $50". An offering priced on request is NOT filtered out: it comes back `price_type: "quote_only"`, because "they quote it" is an answer. | |
| needed_by | No | When it has to happen: "today", "tomorrow", "tomorrow 9am", or an ISO date-time — WITH an offset (2026-10-31T14:00:00-04:00) if you know the user’s zone, because a business whose cut-off is on the RECIPIENT’s clock can only be judged against an offset you give. | |
| only_local | No | true = leave out marketplaces: a business whose shelf names places far from its own address (one local address, hundreds of listings in other cities and countries). Default false: a marketplace is kept, ranked lower, and its card says `marketplace: true` (the full card says why). | |
| properties | No | THE OPEN LAYER AS A FILTER: facts a business publishes beyond price and availability — a capacity, a deposit, a duration, whether something is included. Three states per key: a published value that fits = confirmed; a published value that does not = refuted (left out, a fact); nothing published = unknown (KEPT, ranked lower, named in the card’s `unknown`). Ask for the user’s real conditions here instead of putting them in `query`: «for 8 people» is {key:"capacity",min:8}, «no deposit» is {key:"deposit",max:0}. | |
| fulfillment | No | HOW it must reach the user, and the four are different questions: delivery = brought to the address; pickup = the user collects; on_site = the user goes there (a salon chair, a dining room); at_customer = the business travels (a mover, a plumber). Default any. A business that has not published an answer is KEPT; one that ruled it out is dropped. | |
| radius_miles | No | How far the business may be, in miles. Default 15. | |
| only_independent | No | true = leave out chains (a business whose website serves several of the places found). Default false: a chain is kept as a name, a telephone and a website — it was never read, so it has no offerings — and its card says `chain: true`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavior beyond the annotations: searching is free, the tool neither buys nor reserves anything, out-of-coverage searches return an empty answer with gap_logged: true, and data comes from business websites with owner-verified cards marked. These claims are consistent with readOnlyHint: true and openWorldHint: false.
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 opening sentence and usage guidance are front-loaded, but the middle is dominated by an enormous, repetitive coverage enumeration of dozens of trades and cities. That list is relevant context, yet it overwhelms the description and makes the core call guidance harder to scan.
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 an 11-parameter search tool with no output schema, the description covers the essential context: what it returns, that results include prices/availability/links, what happens outside coverage, that searching is free, that it does not transact, and how it relates to siblings. Little needed 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 the 11 parameters in detail. The description adds a useful query framing of 'what, where, when, budget' and explains coverage constraints, but it does not meaningfully explain most parameters beyond what the schema already 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: a free search of local US businesses by meaning, returning business cards. It also distinguishes the tool from siblings by saying to verify results with get_card and to prefer list_cards when the niche is already known.
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 guidance: use this when the user's trade/niche is unknown, search before saying you cannot help, and call it whenever the user wants to buy, order, book, hire, or get something local. It also names the alternative list_cards for known niches and get_card for verification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
request_statusrequest_to_ownerbook_slotcheck_availabilityfind_businessget_businessget_cardget_offeringget_productlist_cardslist_nichesorder_statusplace_orderquote_ordersearch_catalogFind local businesses with owner-verified hours, services, prices and contacts, for AI agents.
Verified local businesses, bookable by AI agents: services, prices, availability and appointments.
Owner-verified local business data for AI agents: profiles, hours, prices, with provenance.
Find local businesses: live prices, stock and open times, plus owner-confirmed bookings and orders
Add one secure layer between your agents and this server.
