Skip to main content
Glama

Bookvia

Search local businesses

search_businesses
Read-onlyIdempotent

Find verified local service businesses by job description and location (postal code, district, neighbourhood or town in Germany). Recognises the trade from everyday words and asks back with options when unclear. Returns matching services with price ranges. Only businesses that confirmed their own data are in results. A separate list, unverified, can hold businesses from public data that are not on Bookvia: always marked verified: false, never part of results. If the customer says the job is urgent, pass urgent: true: businesses that state they react within one hour right now come first. The order follows how well a business fits and never depends on payment.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_businesses"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of results, default 10
queryNoFree text in German describing the job, e.g. "Steckdose in der Küche setzen" or "Heizungswartung"
offsetNoSkip this many results. Use next_offset from the previous answer to get the next page
urgentNotrue only if the customer said the job is urgent, e.g. the heating is off or water is leaking. Ask the customer; never conclude it from the kind of job. Businesses that state they react within one hour at this moment are then listed first, see reacts_within_1h
categoryNoTrade or industry to filter by
districtNoBerlin district or neighbourhood, e.g. "Neukölln", "Kreuzberg", "Prenzlauer Berg"
locationNoWhere the job is, as the customer said it: German postal code, district, neighbourhood or town, e.g. "12047", "Kreuzberg", "Berlin-Neukölln". Preferred over district and postal_code.
remote_okNotrue if the customer is fine with a provider who works online or by phone instead of coming by. Ask the customer when the job needs nobody on site (tax, legal or business advice, coaching, translation, tutoring, web design, IT for offices). Businesses anywhere in Germany that work remotely are then included, local ones first
postal_codeNoGerman 5-digit postal code of the job location

Output Schema

NameRequiredDescriptionDefault
totalYesAll matching businesses, not only the ones on this page
noticeYes
resultsYes
unverifiedNoSeparate list, never part of results or total: businesses from public data that are NOT on Bookvia and have not confirmed anything. Only filled when trade and place of the search are clear. Read unverified_notice before you mention one
next_offsetNoPass as offset to get the next page. null: there are no more results
interpretationYesWhat Bookvia understood: trade and location. Selected automatically at 80 % confidence or more.
remote_availableNoMore matching businesses that work remotely and were left out because remote_ok was not set
unverified_noticeNoWhat you must tell the customer about the entries in unverified. Only set when unverified is not empty
interpreted_districtYesDistrict the location filter was mapped to
unverified_attributionNoSource of the entries in unverified. Show this line whenever you show one of them. Only set when unverified is not empty

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedInput schema / properties / urgent
      Added value: +{
      +  "description": "true only if the customer said the job is urgent, e.g. the heating is off or water is leaking. Ask the customer; never conclude it from the kind of job. Businesses that state they react within one hour at this moment are then listed first, see reacts_within_1h",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / results / items / properties / reacts_within_1h
      Added value: +{
      +  "description": "Only with urgent: true. true: by its own statement the business reacts within one hour at this moment, during or outside its opening hours. Tell the customer, never promise",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / unverified
      Added value: +{
      +  "description": "Separate list, never part of results or total: businesses from public data that are NOT on Bookvia and have not confirmed anything. Only filled when trade and place of the search are clear. Read unverified_notice before you mention one",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "can_forward": {
      +        "description": "true: Bookvia can pass a request of the customer on to this business. false: it cannot, the customer has to get in touch themselves by phone or website",
      +        "type": "boolean"
      +      },
      +      "category": {
      +        "additionalProperties": false,
      +        "description": "Trade, as Bookvia mapped it from the public source",
      +        "properties": {
      +          "id": {
      +            "type": "string"
      +          },
      +          "label": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "id",
      +          "label"
      +        ],
      +        "type": "object"
      +      },
      +      "city": {
      +        "type": "string"
      +      },
      +      "district": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "id": {
      +        "description": "Listing ID, starts with lst_. Not a business ID: there is no Bookvia profile, no services and no prices behind it",
      +        "type": "string"
      +      },
      +      "name": {
      +        "type": "string"
      +      },
      +      "phone": {
      +        "description": "Public phone number from the source, not confirmed by the business",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "postal_code": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "source": {
      +        "description": "Where the data comes from. Known values: openstreetmap. More may be added later",
      +        "type": "string"
      +      },
      +      "verified": {
      +        "const": false,
      +        "description": "Always false: this business is not on Bookvia and has not confirmed any of this data",
      +        "type": "boolean"
      +      },
      +      "website_url": {
      +        "description": "Public website from the source, not confirmed by the business",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      }
      +    },
      +    "required": [
      +      "id",
      +      "name",
      +      "verified",
      +      "category",
      +      "city",
      +      "district",
      +      "postal_code",
      +      "phone",
      +      "website_url",
      +      "can_forward",
      +      "source"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / unverified_attribution
      Added value: +{
      +  "description": "Source of the entries in unverified. Show this line whenever you show one of them. Only set when unverified is not empty",
      +  "type": "string"
      +}
    • addedOutput schema / properties / unverified_notice
      Added value: +{
      +  "description": "What you must tell the customer about the entries in unverified. Only set when unverified is not empty",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: only businesses that confirmed their own data appear, unverified public-data entries are always verified:false and never in results, and ranking is explained as fit-based and explicitly never payment-driven. It also discloses that the tool may respond with clarifying options rather than results, which is a non-obvious interaction behavior.

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

Conciseness4/5

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

Purpose and verified-only scope are front-loaded before the parameter notes, and each later sentence addresses a distinct concern (urgent, ordering, unverified list). It is somewhat long and the urgent sentence duplicates the schema's urgent description almost verbatim, costing a little efficiency.

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 nine-parameter, open-ended search with an output schema and full annotation coverage, the description supplies the missing conceptual layer: what 'verified' means, how unverified data is separated, how remote and urgent intents change results, and how ordering works. Nothing an agent needs to call or interpret this tool is absent.

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

Parameters3/5

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

With 100% schema description coverage the baseline is 3, and the description mostly echoes what the schema already says about urgent, remote_ok and location precedence. The ranking/payment statement is about result ordering, not parameter meaning, so it does not lift this dimension above baseline.

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?

States a specific verb and resource ('Find verified local service businesses') plus the two filter dimensions (job description, location in Germany) and what comes back (matching services with price ranges). The verified-only scope is spelled out, which is a genuine distinguishing property rather than a restatement of the name.

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

Usage Guidelines4/5

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

Gives concrete decision rules for the two tricky parameters: pass urgent:true only when the customer said so, and set remote_ok when the job needs nobody on site, with an enumerated list of such job types. It also says the tool asks back with options when the trade is unclear. It stops short of naming the sibling get_business_profile as the follow-up step, so routing between the two is left implicit.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources