US local businesses, services and source-cited prices, city by city. Free, no API key.
Scored across 5 tools
Each tool targets a distinct object: cities, businesses, prices across businesses, and price statistics. The main risk is overlap between find_prices (free-text price lookup) and price_summary (aggregate stats for a fixed service list in a city), plus search_businesses which also accepts service/product keywords. The descriptions do resolve this reasonably well, especially price_summary's 'For anything else use find_prices' escape hatch, but an agent must read carefully to pick correctly.
Four of five tools follow a clean verb_noun snake_case pattern (find_prices, get_business, list_cities, search_businesses). price_summary is a noun phrase, a minor deviation, though it reads naturally as a data getter. Nothing ambiguous or chaotic.
Five tools is well-scoped for a read-only local-business pricing service: two discovery tools, one detail tool, and two price-oriented tools. Every tool has a clear role and none feel like filler.
The lifecycle is covered end to end: find a covered city, search businesses, get full business detail, search prices, and get aggregate price stats. Minor gaps exist, such as no category listing to feed search_businesses and no geographic/radius or zip-based filtering, forcing keyword-only discovery. For a read-only dataset this is otherwise a complete surface.
Searches published prices for a product or service across a city's businesses, e.g. "haircut", "oil change", "bowling". Each price includes its source URL and the date it was read.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | City or town name, e.g. "Yerington" | |
| limit | No | ||
| query | Yes | ||
| state | Yes | Two-letter state code, e.g. "NV" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds value by disclosing that each returned price carries a source URL and the date it was read, which tells the agent results are provenance-bearing and time-stamped. That is meaningful behavioral context beyond the structured fields, though it omits coverage/fallback behavior when no published price exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, front-loaded with the action and scope, with examples kept tight. Nothing repeats the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search with no output schema, the description does explain what a result contains (price, source URL, read date), which is useful. But it leaves the 'limit' parameter's effect and any result-count/pagination behavior unexplained, and doesn't say what happens when a city has no published prices.
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 50%: city and state are described in the schema, while query and limit are not. The description partly compensates for 'query' by giving domain examples ('haircut', 'oil change', 'bowling'), but says nothing about 'limit', its maximum, or how results are capped.
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 ('searches published prices') scoped to a product/service across a city's businesses, with three concrete query examples that make the intent unmistakable. The resource noun ('prices') is distinct enough from the siblings (get_business, search_businesses, list_cities) that an agent can route correctly, though no sibling is named 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?
Usage is only implied: an agent infers it should call this when it needs price data for a specific locality. There is no explicit when-to-use/when-not guidance and no mention of the alternatives (e.g. search_businesses to discover businesses first, then this for prices).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full record for one business: address, phone, website, hours, services, prices with sources. Pass the id from search results, or city + state + slug.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| city | No | City or town name, e.g. "Yerington" | |
| slug | No | ||
| state | No | Two-letter state code, e.g. "NV" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the returned field set ('prices with sources' hints at provenance), but says nothing about not-found behavior, partial records, or whether lookups are exact-match. With annotations carrying the safety profile, this is adequate rather than rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero waste, with the returned content front-loaded and the invocation forms second. Nothing to trim.
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 responsibly enumerates the returned fields, and it covers both addressing modes. Missing only edge-case behavior (no match, missing fields, ambiguous slug), which keeps it from a 5.
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 50% and `id` and `slug` are undocumented in the schema; the description compensates by explaining that id comes from search results and that slug is paired with city + state, which is the key semantic an agent needs to pick the right parameter combination. It still doesn't explain what a slug looks like or the id format.
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 retrieval of a single business and enumerates what the record contains (address, phone, website, hours, services, prices with sources), which clearly separates it from a list/search tool. It does not name any sibling explicitly, but the 'id from search results' phrasing signals the relationship to search_businesses.
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 two concrete calling modes: reuse an id from search results, or supply city + state + slug. That implicitly tells the agent to call search first when it lacks an id. No explicit when-not-to-use or named alternative is given, 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.
Lists the US cities and towns CityBotMagic covers, with business counts. Call this first if unsure whether a city is covered.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Optional two-letter state code filter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that results include business counts and that this is a prerequisite/gating lookup, but says nothing about result volume, pagination, or ordering.
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 short sentences, zero filler, with the core purpose front-loaded and the workflow hint second. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-param read tool with full schema coverage and no output schema, the description covers purpose, payload content, and when to invoke. It could go slightly further by noting unfiltered calls return all cities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single 'state' parameter is fully documented there as a two-letter filter. The description adds no syntax or semantics beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Lists the US cities and towns CityBotMagic covers') and adds the payload detail ('with business counts'). This reads clearly as a coverage/catalog lookup, distinguishable from search_businesses, find_prices, and 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?
'Call this first if unsure whether a city is covered' gives an explicit ordering and trigger condition. It does not name alternative sibling tools or state when this tool is unnecessary (i.e. when coverage is already known).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What a common local service typically costs in a city: median, middle-half range, low and high, and every business's lowest published price with its source URL and read date. Services: oil-change, brake-service, wheel-alignment, tire-rotation, smog-check, car-detailing, car-wash, ac-tune-up, drain-cleaning, dog-grooming, haircut, manicure, pedicure, massage, teeth-whitening, tattoo-minimum, tattoo-hourly. Omit service to get all of them for the city. For anything else use find_prices.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | City or town name, e.g. "Yerington" | |
| state | Yes | Two-letter state code, e.g. "NV" | |
| service | No | A service slug or name, e.g. "oil-change", "haircut", "dog grooming". Omit for every service. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld annotations, the description discloses the actual return content: median, middle-half range, low/high, and every business's lowest published price with source URL and read date. This gives the agent enough behavioral context to know what result to expect and how fresh/sourced the pricing data is.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the output shape and then the service list, with no filler. It is appropriately sized, though the long enumerated service list makes it slightly less crisp than an ideal 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?
For a three-parameter read-only pricing tool with no output schema, the description covers the return values, the valid service scope, the omit behavior, and the sibling alternative. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameter documentation is already strong, but the description adds material value by enumerating the valid service slugs rather than only giving schema examples. It also clarifies omission behavior for the optional service parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact resource (typical local service cost in a city) and enumerates the returned metrics: median, middle-half range, low/high, and each business's lowest published price with source URL and read date. It also distinguishes itself from the sibling find_prices by explicitly directing other queries there.
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 useful usage guidance: omitting service returns all services for the city, and anything else should go to find_prices. The alternative is named, but the boundary between this tool and find_prices is expressed only as 'anything else,' which is slightly vague rather than a crisp when-to-use rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds local businesses in a city by keyword (name, category, service, product) and/or category. Returns contact details, hours availability and how many published prices each has.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | City or town name, e.g. "Yerington" | |
| limit | No | ||
| query | No | What the user needs, e.g. "oil change", "pizza", "plumber", "haircut" | |
| state | Yes | Two-letter state code, e.g. "NV" | |
| category | No | Optional category or group keyword, e.g. "restaurant", "health_care" | |
| has_prices | No | Only businesses with published prices |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the description sensibly focuses on behavior beyond safety: what the result set contains (contact details, hours availability, count of published prices). That return-shape disclosure is real added value since no output schema exists, though it says nothing about empty results or limit 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?
Two sentences, no filler, and the core operation is front-loaded ahead of the return-value detail. Every clause carries 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?
For a read-only, open-world-disabled search with no output schema, the description covers the search dimensions and the returned fields. Minor gaps remain: no mention of result limits/default behavior or what an empty result set looks like.
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 83%, so the baseline is 3. The parenthetical '(name, category, service, product)' does add meaning about which fields the query matches, which the schema's 'What the user needs' does not state, but city/state/limit/has_prices get no additional treatment.
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 verb and resource ('Finds local businesses') and scopes it to a city, keyword and/or category, which is enough to tell it apart from get_business (single entity) and find_prices (price lookup). It stops short of explicitly differentiating itself from those siblings by name.
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 only implied: the phrase 'by keyword ... and/or category' suggests the two search modes, but there is no statement of when to prefer this over find_prices or get_business, and no prerequisites or exclusions are given.
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.
price_summaryfind_pricesget_businesslist_citiessearch_businessesVerified US local service providers across 10 home-services trades. Owned data, no API key.
Local US home-service pricing, providers ranked by the Vouched Score, rebates, and glossary.
US business location data: search, sample, count, query rows or buy CSVs (Stripe or x402 USDC).
Verified local businesses, bookable by AI agents: services, prices, availability and appointments.
Add one secure layer between your agents and this server.
