Skip to main content
Glama
Sign In

SuVerse

by io.suverse.www
OverviewDiscussionsAdmin

Every business of one trade near a place, in one fixed order — the shelf

list_cards
Read-only

Every business of ONE trade (niche: a key from list_niches, exactly) near location, default radius 15 miles, 20 a page. The order is fixed and is not a ranking: independent businesses, then chains, then marketplaces; inside each, by distance (a trade that comes to the customer: published service area first). query does NOT filter or reorder businesses: it chooses which ITEM each card shows. To find businesses that have an item, use search_catalog. Each card: id, name, distance, phone, a few items, next (one action), and for what you pass — needed_by, max_price, deliver_to — a state: hours give open_then / closed_then / unknown (never a free slot); an item price within the budget is item_price_within_budget (the total is not known until priced). needed_by: «today», «tomorrow 19:00», «after 15:00», an interval «tomorrow 08:00 to 17:00», a deadline «by 2026-11-20», a range «this week» — read the same way in every tool. A niche that is not a key returns no cards and the variants to choose from. Each card carries transparency {grade A–D, have, of, items ✓/✗}: how much the business publishes about itself, NOT quality. You may sort or filter by it; this order does not use it. Trades on the shelf: restaurant (2520) · medical clinic (1227) · auto repair (1111) · insurance agent (1107) · hair salon (1095) · dentist (1076) · lawyer (1037) · oil change (978) · clothing store (903) · massage (890) · accountant (881) · nail salon (782) · hvac (776) · print shop (768) · real estate agent (762) · beauty salon (757) · barber (734) · chiropractor (710) · notary (673) · gas station (663) · appliance repair (589) · grocery (562) · car dealer (560) · storage (548) · optometrist (542) · bakery (537) · bar (530) · landscaping (516) · pharmacy (505) · elder care and home care (461) · daycare (448) · body shop (446) · photographer (440) · pet grooming (433) · pizza (426) · catering (411) · cleaning (409) · event venue (402) · florist (402) · tire shop (393) · auto parts store (389) · hotel (379) · pressure washing (378) · plumber (372) · jewelry (362) · furniture (361) · electrician (355) · pool service (355) · windows and doors (330) · tree service (327) · coffee shop (325) · party rental (319) · towing (316) · roofer (313) · veterinarian (306) · tattoo studio (296) · truck tire service (294) · pest control (293) · car wash (274) · junk removal (272) · movers (271) · liquor store (268) · tutoring (262) · ev charging station (260) · urgent care (256) · window cleaning (248) · truck repair (237) · carpet cleaning (224) · travel agency (214) · painter (191) · physical therapy (190) · ice cream shop (189) · car rental (188) · parking (176) · bike repair (175) · dance studio (169) · fishing charter and boat tours (168) · fuel delivery (167) · jewelry and watch repair (164) · music lessons (160) · dry cleaner (159) · locksmith (154) · handyman (152) · med spa (152) · auto glass (151) · gym (147) · general contractor (146) · shipping and packing store (146) · wedding planner (139) · septic and well service (131) · garage door (124) · dog walking and pet sitting (108) · garden center and nursery (103) · pet boarding (103) · phone repair (101) · mattress (88) · thrift store (87) · yoga (83) · hardware store (75) · boat rental (73) · tailor (68) · bike and jet ski rental (65) · funeral home (60) · medical equipment rental (55) · golf course (53) · driving school (52) · pet store (49) · butcher and seafood market (43) · swim school (30) · meal prep (21) · cinema (20) · shooting range (20) · juice bar (19) · computer repair (18) · kids play center (18) · escape room (17) · tennis and sports courts (17) · bowling and billiards (12) · brewery (9) · kids sports and activities (9) · specialty grocery and farmers market (9) · babysitting and nanny agency (8) · motorcycle repair (8) · taxi and transfer service (8) · local business (6) · other online service (6) · martial arts (5) · shoe repair (4) · online store (3) · food truck (2) · lash and brow studio (2) · museum (2) · services (2) · sporting goods store (2) · aquarium (1) · butcher (1) · furniture store (1) · logistics software (1) · motel (1) · shoe store (1) · store (1) · transportation service (1) · travel booking site (1); known but not scanned anywhere: candle shop, confectionery, garden center, gift shop, medical apparel, party shop, toy store. Follow the server instructions «HOW TO USE THE SUVERSE CATALOG»: results are candidates, not proof; keep reading, quoting, requesting and ordering separate; nothing is sent to an owner, booked, ordered or paid without the user’s permission.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "niche": "<niche>"
    },
    "name": "list_cards"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNothe `next_page` token of the previous answer
tagsNoFILTER 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»).
limitNocards per page. Default 10.
nicheYesa niche key from list_niches, exactly (another word returns the variants to choose from, never a substitute)
queryNochooses which ITEM each card shows («red roses», «balayage»); it does not filter or reorder businesses — for that, search_catalog
detailNotask (default): the short card under the task; shelf: the older ≤ 1 KB shelf card
intentNowhat 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)
locationNoa 5-digit US postcode (best), a city ("Tampa, FL") or "lat,lng". Required for local trades; ignored for online niches (software, apps, online shops — see list_niches → online_niches).
max_priceNothe 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_byNowhen: «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_toNowhere 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
propertiesNofacts to read off each card without filtering: property_states {key: "confirmed <value>" | "refuted" | "unknown"}
radius_milesNoDefault 15 (the same in every tool).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Goes well past the readOnly/openWorld/destructive annotations: it discloses the fixed ordering rule (independent → chains → marketplaces, then distance, with service-area-first for mobile trades), pagination via next_page, what each card contains, the fallback behavior for an invalid niche, and the explicit caveat that nothing is sent, booked or paid without user permission.

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

Conciseness2/5

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

The core semantics are front-loaded, but roughly half the text is a ~150-entry enumeration of trades with counts prefixed to marketing-style descriptions, which the description itself renders redundant by requiring niche keys from list_niches. That bulk crowds out scanning and invites the agent to pass raw trade names that will fail the exact-key requirement.

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

Completeness5/5

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

For a 13-parameter, read-only listing tool with no output schema, the description covers everything needed to call it correctly: required niche, location requirements and online-niche exception, page token, radius, card contents and ordering, plus the server-instruction caveat about candidates and user permission. Nothing material is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, and the description genuinely adds meaning: the accepted natural-language shapes for needed_by ('tomorrow 08:00 to 17:00', 'by 2026-11-20', 'this week'), the in_budget/budget_unknown/over_budget grouping behind max_price, and the item-selection role of query. It is docked one point because it states '20 a page' while the schema declares limit default 10 — a conflicting default the caller must reconcile.

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

Purpose5/5

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

Opens with a precise verb+resource+scope: 'Every business of ONE trade (niche: a key from list_niches, exactly) near location, default radius 15 miles.' It explicitly separates itself from search_catalog ('To find businesses that have an item, use search_catalog'), so an agent can route 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.

Usage Guidelines5/5

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

Gives the selecting conditions for the nearest alternative (search_catalog for finding businesses that carry an item), the prerequisite for the required parameter (niche must be a key from list_niches), and the non-obvious rule that query chooses the shown item rather than filtering or reordering. It also tells the agent it may sort/filter by transparency, which the default order does not use.

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

All SuVerse toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources