Search verified local businesses, check what their verification proves, and message them.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.6/5 across 9 of 9 tools scored.
Most tools have clearly distinct purposes, but ask_business and ask_business_freeform both serve the core function of asking a question about a listing, which could cause misselection. The detailed descriptions mitigate the overlap, but the similar intent remains a minor ambiguity.
All tool names follow a consistent verb_noun snake_case pattern (ask_, check_, contact_, get_, search_, send_), with only ask_business_freeform adding a modifier that still fits the convention. Naming is predictable and readable.
Nine tools is well-scoped for a knowledge base server, covering discovery (search, get), questioning (ask), asynchronous communication (contact, followup, replies, escalation), and verification. Each tool earns its place without unnecessary bloat.
The tool set provides full coverage of the domain: finding businesses, reading profiles, asking structured and freeform questions, escalating unresolved queries, opening and continuing conversations, and checking verification. Poll-based tools handle dead ends explicitly, so there are no obvious gaps.
ask_businessAInspectAsk one specific question about a listing and get an answer from the registry, with no human involved. Try this before contact_business: it is instant, free, and does not put a message in someone's inbox. Returns either an answer or an escalation. When resolved is true, answer holds it and basis names the fields it was read from. When escalate is true we do not hold the fact — this is NOT a negative answer, and in particular an unlisted place is "we do not know", never "they do not deliver there". Only the business can declare its own list complete. Unsupported questions come back with refused true and a supported list rather than a guess: nothing here is ever inferred, approximated or improvised. Authentication: none. This tool works with no credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | The `kind` field from the same search result. | |
| slug | Yes | The `slug` field from a search_businesses result. | |
| intent | Yes | Which question to ask. "is_open_now" needs nothing else; "delivers_to" needs a `params` place; "lead_time" asks the shortest notice they accept an order on. | |
| params | No | Arguments for the question. For "delivers_to": { "place": "Botanica" }. Ignored by the others. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden and does so excellently. It explains return states (`resolved`, `escalate`, `refused`), clarifies that escalation is not a negative answer, notes that unlisted means unknown, and states that nothing is inferred or approximated. Authentication is also explicitly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with the core purpose first, then usage guidance, then semantic details. It is longer than typical due to important caveats, but every sentence adds value. Minor redundancy exists: 'Authentication: none' and 'This tool works with no credentials' say the same thing.
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?
Given the tool's complexity (4 params, nested object, no output schema), the description covers all essential aspects: what it does, return semantics, error handling via `refused`, and authentication. It also provides enough context to choose between this and contact_business. The absence of an output schema is compensated by detailed textual descriptions of response states.
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. The description adds value by explaining the intent options and the role of `params` for `delivers_to`, and by noting that `params` is ignored by other intents. It also clarifies the `supported` list for unsupported questions, going 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 uses a specific verb ('Ask') and resource ('listing') and clearly distinguishes the tool from contact_business by noting it is instant, free, and does not send an inbox message. It also states it handles 'one specific question,' contrasting with the freeform sibling.
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 tells when to use this tool before contact_business and describes advantages. However, it does not directly contrast with ask_business_freeform, though 'one specific question' implies a structured-question use case. The guidance for when to use vs. alternatives is strong but not fully exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ask_business_freeformAInspectSame answers as ask_business, but you send the person's own words instead of choosing an intent, and the reply comes back in the language they used. Supported languages: en, ro, ru, de; anything else is answered in English. Prefer ask_business when you already know which of the three questions you are asking — it is instant and costs nothing, whereas this one runs a model to read the question and is rate-limited accordingly. A model is used ONLY to decide which question was asked and in which language. It never sees the business's stored data and never writes the answer. Returns an outcome and a reply in the asker's language. Branch on outcome, not on the prose: "answered" carries reply and a structured answer; "needs_detail" means we need one more thing from the asker and reply requests it; "not_understood" means it was not one of our three questions, with supported listing them; "escalated" means a real question we do not hold the fact for — we forward that one to the business ourselves, and escalation carries the ref that reads their answer later with check_escalation. handoff still holds what was gathered, for contact_business. An escalation is never a negative answer. Authentication: none. This tool works with no credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | The `kind` field from the same search result. | |
| slug | Yes | The `slug` field from a search_businesses result. | |
| question | Yes | What the person actually asked, in their own words and their own language. Do not translate or rephrase it — the language of this text decides the language of the reply. | |
| idempotency_key | No | Optional, and only matters when a question reaches a person. The same question about the same business within 24 hours attaches to the open one and does not notify them twice, which is right when you are RETRYING a failed call and wrong when it is a genuinely new problem worded the same way. Send the same key when retrying, a fresh one when it is a new ask. Omit it and the retry behaviour applies, which is the safe default for the business. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full disclosure burden. It reveals the model usage scope (only to decide question and language), privacy guarantees (never sees stored data, never writes answer), rate limiting, language support with English fallback, and detailed outcome behaviors including escalation semantics. This is far beyond typical descriptions and fully transparent.
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 a compact but information-dense paragraph, organized logically: comparison to sibling, language/rate-limit notes, privacy/model usage, outcome enumeration, and auth. Every sentence carries substantive guidance and no filler. Despite its length, it earns its place given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain return values, and it does so comprehensively: `outcome` variants (`answered`, `needs_detail`, `not_understood`, `escalated`) with their respective payloads and how to branch. It also covers `handoff` for contact_business and references check_escalation. Combined with language, auth, and rate-limit context, this is fully complete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, and the schema itself already explains each parameter thoroughly (including the nuanced idempotency_key retry behavior and the language-deciding role of `question`). The tool description mostly restates or summarizes these, adding little new parameter-specific meaning beyond what's in the schema. Baseline 3 is appropriate.
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 identifies this tool as a freeform variant of ask_business, explicitly contrasting it with the intent-based sibling. It specifies the verb (ask), the resource (business freeform query), and the key difference: sending the person's own words versus choosing an intent. This distinguishes it effectively from its primary sibling.
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?
The description gives explicit guidance: 'Prefer ask_business when you already know which of the three questions you are asking — it is instant and costs nothing, whereas this one runs a model to read the question and is rate-limited accordingly.' It also explains when to branch on specific `outcome` values and how to handle retries with `idempotency_key`. This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cancel_orderAInspectCancel an order you placed with commit_order. Returns settled. True means it is cancelled, the business has been told and their day is free again. False comes with a reason: "inside-cancel-window" (later notice than they said they need), "no-cancel-window-set" (they never said), "order-passed", "not-open" (already cancelled or withdrawn) or "not-the-issuing-agent". Every reason but the last two puts the request in front of the business and returns an escalation to poll with check_escalation — a refusal here is a question being asked, not a dead end. Also returns refund, which is the business's OWN published terms at the notice given. tunnel settles no money and holds none: nothing has been paid or refunded, and only the business can act on it. Authentication: bearer token required, and it must be the same agent that placed the order. Anyone else holding the reference gets the request routed to the business instead.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | The `ref` returned by commit_order. It is the only handle on this order. | |
| note | No | Optional. Why, in the buyer's own words. Recorded, shown to the business and carried into the question if a person has to decide. Never parsed, and it cannot change the answer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the behavioral contract: return values (settled), possible reasons with explanations, escalation behavior, refund semantics, legacy settlement, and authentication requirements. It covers the full lifecycle of a cancellation attempt.
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 dense but well-structured, each sentence adding necessary detail about outcomes, reasons, and actions. It is longer than the minimal viable description, but the complexity of the cancellation flow justifies the length without redundancy.
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?
Given the tool's complexity and the absence of an output schema, the description fully explains return values, error conditions, and next steps (e.g., polling check_escalation). It also covers edge cases like reauthentication and delegation, making it complete for agent use.
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 schema already describes both parameters (ref and note) with 100% coverage, but the description adds essential nuance: ref is the only handle on the order, and note is never parsed and cannot change the outcome. This goes beyond the schema to clarify parameter intent.
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 the tool cancels an order placed with commit_order, specifying the action and resource. It distinguishes from sibling tools like request_order_change and reschedule_order by focusing solely on cancellation and detailing the outcome.
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 context: use this for canceling orders you placed with commit_order, and references check_escalation for polling follow-ups. However, it does not explicitly mention alternatives like request_order_change or state when not to use this tool, leaving some room for interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_availabilityAInspectFind out when a business is actually free. Worked out per call against their opening hours, their notice period, their blackout dates and what is already booked — there is no stored list of free times to be out of date. Returns known true with days, each holding slots that carry a start, an end and free. firstFree is the earliest one across the range. Pass time to ask about one exact moment instead of browsing. known false means this business has not set up a calendar and reason names the missing piece. That is "we cannot tell you", never "they are busy" — ask a person instead. A free slot is not a hold. Nothing is reserved until commit_order, and between the two calls someone else can take it. Authentication: none. This tool works with no credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Optional. How many days to walk, 1 to 14. Defaults to 7. | |
| from | No | Optional. First day to look at, yyyy-mm-dd in the business's own local calendar. Defaults to their today. | |
| kind | No | Optional. The `kind` field from the same search result. Defaults to "entity". | |
| slug | Yes | The `slug` field from a search_businesses result. | |
| time | No | Optional. One exact start time as HH:MM, 24-hour, on the first day of the range. The answer comes back under `asked`, and "not-a-slot-start" means their day divides differently — the free starts are listed beside it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral transparency burden. It discloses real-time calculation (no stale list), the meaning of `known` false ('we cannot tell you, never they are busy'), the 'not-a-slot-start' special case, the non-holding nature of a free slot, and authentication requirements ('Authentication: none'). This is exemplary.
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 appropriately sized for the tool's complexity; every sentence earns its place. It is front-loaded with the main purpose, then covers computation freshness, return shape, special cases, reservation caveat, and auth, all without repeating schema field descriptions. The structure flows logically from what → how → when → caveats.
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?
Given no output schema and no annotations, the description provides a thorough mental model of the tool. It names the response envelope (`known`, `days`, `slots`, `firstFree`, `asked`, `reason`), explains the false/error case, and relates the tool to `commit_order`, making it complete enough for an agent to know both the call and the interpretation of 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 coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema for the `time` parameter, explaining its purpose ('ask about one exact moment') and its special response ('not-a-slot-start' with free starts listed beside it). It also frames the `days`/`from` browsing behavior into a coherent model of returned `slots`, which the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Find out when a business is actually free') and clearly distinguishes itself from siblings by emphasizing per-call computation against live data (opening hours, notice period, blackout dates, bookings) rather than a stored list. It also clarifies the known-false semantics, making it clear this is an availability lookup, not a reservation or commitment tool.
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?
The description gives explicit guidance on when to use the `time` parameter ('exact moment instead of browsing') and warns that 'Nothing is reserved until commit_order' and 'between the two calls someone else can take it,' steering reservation tasks to a sibling tool. It also advises to ask a person when `known` is false. It stops short of naming alternative tools directly, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_commitmentAInspectRead a commitment you were given by commit_order, including whether the business has since withdrawn it. Returns state: "issued" means it stands, "repudiated" means the business said they cannot honour it, with their stated reason. A withdrawal does not erase the original — both are on the record, timestamped. Check this before acting on a commitment made some time ago. Authentication: none. This tool works with no credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | The `ref` returned by commit_order. It is the only way to read this commitment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to rely on, the description discloses key behavioral traits: the meaning of 'issued' and 'repudiated', that withdrawal does not erase the original, and that both are timestamped. It also explicitly states 'Authentication: none' and 'This tool works with no credentials', which is valuable context beyond the schema.
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 four sentences, each adding relevant information: purpose, state values, persistence behavior, usage timing, and auth requirements. It is front-loaded with the main verb and resource, and contains no 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 simple read tool with one parameter and no output schema, the description fully covers what the agent needs: how to invoke (ref), what to expect (state and meaning), and special behaviors (withdrawal persistence, no auth). It is complete for its complexity.
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% for the single parameter 'ref', and its description already explains that it is the only way to read the commitment. The tool description reinforces this but adds no new parameter-level meaning, so the baseline of 3 is appropriate.
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 the tool's function: 'Read a commitment you were given by commit_order'. It specifies the resource (commitment) and differentiates from its sibling commit_order by focusing on reading rather than creating. The state semantics are also explained, making it unambiguous.
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?
The description gives explicit guidance: 'Check this before acting on a commitment made some time ago.' This conveys when the tool should be used. It does not mention when not to use it or name alternatives, but the context is clear enough for a unique read-only tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_escalationAInspectRead the answer to a question that had to go to a human. Use the escalation.ref that ask_business_freeform returned when its outcome was "escalated". Returns a state and, once there is one, the business's own answer in their words. Branch on state: "open" means we have not reached them yet, "delivered" means the question is in front of them and unanswered, "answered" carries answer, "undeliverable" means this business has given us no way to reach them and waiting will not help, "expired" means nobody answered and we have stopped waiting. This is a poll, not a subscription, and there is no obligation on anyone to answer. Come back later rather than in a loop; most answers take hours, not seconds. Authentication: none. This tool works with no credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | The `escalation.ref` from an earlier ask_business_freeform result. It is the only way to read this answer, so keep it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes full responsibility for behavior. It states the tool is a read ('Read'), a poll not a subscription, explains the state semantics, and notes authentication is not required. This gives the agent a complete safety and behavior profile.
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 purpose and flows logically from usage to output to polling behavior to authentication. Every sentence contributes essential information, particularly the state enumeration, so it is appropriately sized for a tool with no output schema.
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?
Since there is no output schema, the description compensates by fully explaining the return structure: the `state` and `answer`, plus all five possible state values and their meanings. It also covers the polling model and the lack of authentication, making the tool self-contained. Given the simple one-parameter schema, this is complete.
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 schema already documents the `ref` parameter at 100% coverage, including its origin and importance. The description merely repeats the schema's message without adding syntax, validation, or additional meaning, so it meets the baseline of 3 but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource: 'Read the answer to a question that had to go to a human.' It further ties the tool to ask_business_freeform and explains the output states, distinguishing it from siblings like check_replies. The purpose is unmistakable.
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 explicitly states the trigger condition: 'Use the `escalation.ref` that ask_business_freeform returned when its outcome was "escalated".' It also provides cadence guidance ('Come back later rather than in a loop'). However, it does not explicitly name alternatives or when-not scenarios, so it stops short of the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_merchant_verificationAInspectCheck live what a merchant has actually been verified to, and by whom. Call this before acting on a claim that matters — a profile is a cached summary, this is the current answer. Returns level, a signed attestation, an expiry date and the transparency-log position. level "human" means a tunnel employee checked identity, control of the channels, and that the service is real. level "automated" means machines proved the merchant controls the channels its record cites and NOTHING about who they are or whether they deliver — the limitations array says so inside the signed payload. null means neither. Neither level is an endorsement of quality. Treat an answer older than five minutes as stale for anything irreversible. Authentication: none. This tool works with no credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The `slug` field from a search_businesses result, or the merchant numeric id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses that authentication is none, the tool works without credentials, and clarifies that neither level is an endorsement of quality. It describes the return fields and the constraints of each level.
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 well front-loaded with the main purpose, but the explanation of levels is somewhat lengthy. It could be more concise while retaining all necessary 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?
Given no output schema, the description adequately explains what is returned and the semantics. It does not cover edge cases like errors or rate limits, but for a single-param tool it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already provides a description for the single parameter 'slug'. The tool description does not add additional meaning beyond what is in 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 the tool checks what a merchant has been verified to and by whom, distinguishes it from a cached profile, and explains the meaning of different levels. It is very specific and actionable.
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?
The description advises calling this before acting on a claim that matters, and notes that the profile is a cached summary. It also provides staleness guidance (5 minutes). It does not explicitly mention alternatives but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_repliesAInspectRead a conversation you opened with contact_business, including anything the business has replied since. Returns the whole message thread and its status. Poll it; there is no push. Authentication: the conversation_id and token from contact_business are the credential for this call. No bearer token is needed.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | The secret `token` returned by contact_business. | |
| conversation_id | Yes | The `conversation_id` returned by contact_business. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses read-only nature, polling requirement, authentication mechanism, and return value. All behavioral traits are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding value: purpose, return value, usage hint. No wasted words. Front-loaded with the action.
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?
Given no output schema, description adequately covers return type (whole thread and status). Also explains authentication, which is essential for using the tool. Complete for a two-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%, but description adds critical context: parameters are credentials from contact_business. This enhances understanding beyond the schema's basic 'returned by contact_business'.
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?
Clearly states verb 'Read' and resource 'conversation you opened with contact_business'. Distinguishes from sibling contact_business by focusing on reading replies rather than initiating. The purpose is explicit and unambiguous.
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?
Provides clear usage context: polling required ('Poll it; there is no push') and authentication credentials from contact_business. Does not explicitly state when not to use, but implicitly suggests using after contact_business and before send_followup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
commit_orderAInspectPlace a binding order with a business, inside limits they set in advance. This is the only tool here that commits anyone to anything. Either name the figure yourself, or send items from get_rate_card and we price them from the merchant's own card. Either way it is checked against their price floor, maximum, daily capacity, notice period and blackout dates. Send time to take one slot rather than a whole day — check_availability lists them. No model reads any part of this call: the fields you send are the fields we check, so a commitment cannot be talked into existence by anything written in prose. Returns committed. When true you get a ref, the exact terms agreed and basis naming which of their settings allowed it. When false, reason names the single limit that refused: "not-authorised", "below-price-floor", "above-maximum" (a person decides that one), "capacity-full", "blackout-date", "inside-lead-time", "currency-mismatch", "date-in-past", "unknown-items", "quote-mismatch" (their prices changed), "slot-taken", "not-a-slot-start". A refusal is final for those terms — change them or use contact_business; do not retry the same call. The business may later withdraw. Read state from check_commitment before relying on it. Authentication: bearer token required. Register once at POST /api/v1/agents/register, exchange the credentials at POST /api/v1/agents/token.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | The day the work or delivery is for, as yyyy-mm-dd, in the business's own local calendar. | |
| kind | Yes | The `kind` field from the same search result. | |
| slug | Yes | The `slug` field from a search_businesses result. | |
| time | No | Optional. A slot start on that day, HH:MM in 24-hour time and in their timezone. It must be one of the starts check_availability lists; times between them are refused rather than rounded to the nearest one. | |
| items | No | Optional. Lines from their rate card, as request_quote takes them. When present, the price is theirs rather than yours and is computed fresh at this moment — a card that changed since you quoted refuses with "quote-mismatch" instead of billing the new figure. | |
| amount | No | What the buyer is offering to pay, as a number. Required unless you send `items`. This is your figure, not ours — we only check it against the limits the business set. Sent alongside `items`, it must equal what their card comes to, or the call is refused. | |
| currency | No | ISO code, e.g. MDL or EUR. Required unless you send `items`. It must match the currency their limits are in. | |
| quantity | No | Optional. How many, as a whole number. Defaults to 1. Leave it out when you send `items` — the quantities are on the lines. | |
| description | No | Optional. What the order is for, in plain words. Recorded and shown to the business; it is never parsed and never changes what we check. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses bindingness, safety checks (price floor, maximum, capacity, blackouts), integrity guarantees (no model reads the call), refusal finality, possible later withdrawal, and authentication requirements. This is exceptionally transparent.
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 long but densely packed with essential information for a high-stakes binding action. It is front-loaded with purpose and uses structured lists (refusal reasons) for readability. Every sentence adds value, though it is more verbose than the simplest tools.
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?
Given 9 parameters, no annotations, and no output schema, the description fully covers the return contract (committed, ref, terms, basis, reason), the auth flow, and edge cases like quote-mismatch. It leaves no critical behavioral gap.
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?
Although schema coverage is 100%, the description adds crucial semantics: the mutual exclusivity and equality requirement between amount and items, the currency matching constraint, time slot validation against check_availability, and the non-parsing of the description field. These are not apparent from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource: 'Place a binding order with a business'. It also distinguishes from all siblings by noting 'the only tool here that commits anyone to anything', making its unique role explicit.
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 explains when to use it (to commit), and how to choose between naming a figure or sending items from get_rate_card. It also gives exclusions: 'do not retry the same call' and suggests alternatives like contact_business or check_commitment for follow-up.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
contact_businessAInspectOpen a conversation with the person behind a listing. The message arrives in their dashboard inbox and they reply when they get to it — this is asynchronous, not a chat, and nobody is obliged to answer. Returns a conversation_id and a secret token. Keep both: they are the only way to read a reply (check_replies) or write again (send_followup), and the token cannot be recovered. Authentication: bearer token required. Register once at POST /api/v1/agents/register, exchange the credentials at POST /api/v1/agents/token, and send the result as an Authorization: Bearer header. Registered agents get a daily conversation quota, a per-minute burst limit and an alarm on contacting many businesses at once; a refusal names which one was hit. Reading the knowledge base needs none of this.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Optional. The `kind` field from the same search result. | |
| slug | Yes | The `slug` field from a search_businesses result. | |
| message | Yes | The message body. Maximum 4000 characters. | |
| subject | Yes | Short subject line, like an email subject. | |
| agent_name | Yes | Who is writing, in words the business will read — e.g. "Claude, on behalf of a customer". | |
| agent_contact | No | Optional. An out-of-band address the business can reply to, e.g. the end user email if they agreed to share it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility. It discloses that the tool is asynchronous, non-obligatory, returns a secret unrecoverable token, requires bearer authentication, has daily and burst quotas, and an alarm for contacting many businesses. This is comprehensive behavioral information beyond what any structured annotation would provide.
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 primary action, followed by return values, token importance, and authentication details. It is structured logically and every sentence adds value. Could be trimmed slightly, but generally concise for the amount of information conveyed.
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?
The description covers the tool's purpose, return values, critical token behavior, authentication, rate limits, and related tools. It lacks explicit error handling beyond refusal naming the limit, but given the absence of output schema and annotations, it provides sufficient context for an AI agent to use the tool effectively.
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 input schema has 100% description coverage for all 6 parameters, so the schema already documents each parameter's meaning. The tool description does not add new parameter-level semantics beyond the schema; it only provides context about the slug coming from search_businesses and the importance of the token. Baseline 3 is appropriate.
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 the action ('Open a conversation with the person behind a listing'), specifies the asynchronous nature, and distinguishes from sibling tools by explaining that check_replies and send_followup are for reading replies and writing again. It also references search_businesses implicitly through the slug field.
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?
The description provides guidelines by explaining the asynchronous model, emphasizing that the token is critical and must be saved, and detailing authentication requirements and rate limits. It contrasts with 'reading the knowledge base' to indicate when authentication is not needed, though it does not explicitly state when to use or not use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_businessAInspectRead the full profile of one business. Returns identity, contact details, address, social profiles, offerings, FAQ, verification and any machine-readable endpoints we publish for it. Absent information is named in missing rather than dropped silently, so an empty field means "we do not hold this", not "they do not have one". An unknown slug returns candidate slugs instead of a bare failure. Authentication: none. This tool works with no credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Optional. The `kind` field from the same search result. If omitted, "entity" is tried first, then "website". | |
| slug | Yes | The `slug` field from a search_businesses result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully accounts for behavioral transparency. It discloses that absent information is named in a 'missing' field (not dropped silently), unknown slugs return candidate slugs, and no authentication is needed. This covers important edge cases and safety considerations.
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 concise and well-structured, front-loading the core purpose and then adding relevant details about missing fields, error handling, and authentication. Every sentence serves a purpose without redundancy.
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?
Given no output schema, the description is highly complete: it lists the categories of returned data, explains the 'missing' field convention, describes behavior for invalid slugs, and confirms no credentials are needed. This enables an agent to confidently invoke the 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%, but the description adds value beyond the schema by explaining the default fallback logic for the 'kind' parameter (entity then website) and specifying that 'slug' comes from a search_businesses result. This provides essential context beyond parameter names and enum values.
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 the tool reads the full business profile, listing specific fields like identity, contact, address, social profiles, offerings, FAQ, and verification. It distinguishes from siblings like search_businesses (searching) and contact_business (contacting) by focusing on reading a complete record.
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?
The description notes the tool requires no credentials and explains behavior for unknown slugs, but does not explicitly state when to use this tool over alternatives like search_businesses or contact_business. However, the context is clear enough for an agent to infer appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_rate_cardAInspectRead the prices a business has authorised us to quote on their behalf. Returns published and, when true, a rateCard holding a currency, an optional minimum charge and items — each with a code, a label, a unit and an amount. Those code values are what request_quote and commit_order take: we price exactly what you name and never work out which line a description meant, because a near-miss there is a wrong price someone has to honour. published false comes with reason: "no-rate-card" means they have not written one, "not-authorised" means they have not allowed us to name prices at all. Neither means the work is unavailable — only that the figure has to come from a person, via ask_business_freeform or contact_business. Authentication: none. This tool works with no credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Optional. The `kind` field from the same search result. Defaults to "entity". | |
| slug | Yes | The `slug` field from a search_businesses result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: it is a read operation, pricing is exact-match ('never work out which line a description meant'), the meaning of published/reason values, and that no authentication is needed. This fully informs the agent about side effects and data semantics.
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 well-structured and information-dense; every sentence adds value: purpose, return format, exact-match caveat, fallback tools, and authentication. No filler or redundancy.
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?
Given the simple 2-parameter schema and no output schema, the description fully covers return values, failure reasons, alternative tools, and authentication, making it complete for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters at 100% coverage. The description mentions the returned codes are used by other tools but does not add new meaning to the slug or kind parameters beyond what the schema states, 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?
The description clearly states the tool reads authorised prices for a business, with a specific verb ('Read') and resource ('prices'). It also outlines the return structure and distinguishes itself from pricing/commit operations by noting the codes feed request_quote and commit_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?
Explicitly provides fallback guidance: when published is false, use ask_business_freeform or contact_business. It also implies the primary use case of obtaining exact codes for quote/commit, thereby clarifying when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
request_order_changeAInspectRaise anything else about an order that already exists: a change to what was ordered, a refund request, or a problem with what was delivered. This tool never settles anything, and that is deliberate. Changing an order re-prices it and a refund moves money tunnel does not hold, so both are decisions only the business makes. What this does is put the request in front of them with the whole order attached — reference, terms, lines, date and what has already happened to it — on the channel they actually read. Returns settled false always, the order as it stands, and an escalation whose ref you poll with check_escalation for the business's own answer in their words. For a refund it also returns refund: their published terms at this notice, if they have published any. Nothing has been paid, refunded or changed by this call. Authentication: bearer token required.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | The `ref` returned by commit_order. | |
| note | Yes | What the buyer actually said, in their own words. This is the part the business needs, so send it verbatim. Carried unchanged and never interpreted. | |
| change | Yes | What kind of request this is: "modify" to change what was ordered, "refund" to ask about money back, "other" for anything else including something being wrong. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden. It discloses critical behavioral traits: returns settled=false always, attaches the full order, re-prices on changes, moves money on refunds, requires bearer token, and explicitly states that no money or changes are executed by this call. This is exceptionally transparent.
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 dense and front-loaded with purpose, then moves into behavior and return values. It is a single paragraph, but every sentence contributes valuable context. Some minor redundancy exists (e.g., "Nothing has been paid..." restates earlier points), preventing a 5.
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?
The tool has no output schema and rich behavioral implications. The description compensates by explaining exactly what is returned (settled, order, escalation, refund terms), how to follow up (check_escalation), authentication requirements, and side-effect guarantees. This is complete for an agent to invoke and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces some parameter meanings (e.g., change types, note verbatim) but does not add substantial new semantic information beyond what the schema already provides. It adds context about the order attachment, but this is behavioral, not parameter-specific.
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 the tool's purpose with a specific verb and resource: "Raise anything else about an order that already exists." It enumerates distinct request types (change, refund, problem) and differentiates itself from siblings like commit_order and cancel_order by emphasizing it never settles anything.
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?
The description provides explicit guidance on when to use this tool: for existing orders needing changes, refunds, or issue reports. It clearly states what the tool does not do (never settles, no payment/refund/change) and directs the agent to poll check_escalation for the business's answer, effectively naming the follow-up tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
request_quoteAInspectPrice a specific set of line items against a business's rate card. Call get_rate_card first and name code values from it; we do the arithmetic. Returns quoted. When true you get total, lines showing what each one came to, and validUntil. A quote is a statement, NOT a hold — nothing is reserved and no price is locked. commit_order prices the same items again from the card at the moment it binds, so if the merchant changed a figure in between you are told rather than charged. When quoted is false, reason is "unknown-items" (not on their card), "quantity-out-of-range" (change the number and call again), "no-rate-card", "not-authorised" or "below-price-floor". All but the second put the question in front of a person and return an escalation whose ref you can poll with check_escalation. Authentication: none. This tool works with no credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Optional. The `kind` field from the same search result. Defaults to "entity". | |
| note | No | Optional. What the job is, in the buyer's own words. Never parsed and never changes the figure; it is what a human reads if the quote has to go to one. | |
| slug | Yes | The `slug` field from a search_businesses result. | |
| items | Yes | The lines to price. Each is an object with a `code` from get_rate_card and an optional quantity, which defaults to 1. Up to 100 lines. | |
| language | No | Optional. The buyer's language, recorded with the request. Defaults to English. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It discloses that a quote is not a hold, nothing is reserved, no price is locked, and commit_order re-prices from the card, with the agent told if the merchant changed a figure. It details all return fields and the meaning of each failure reason, plus escalation refs and authentication state. This is exceptionally transparent.
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?
Although dense, every sentence earns its place. It starts with the core action, then prerequisites, return values, caveats, error handling, escalation path, and authentication. The structure is logical and front-loaded, with no filler or repetition.
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 tool with 5 parameters, no output schema, and no annotations, the description is remarkably complete. It covers how to invoke, what to expect, all failure modes with actionable outcomes, escalation polling, and security context. There are no significant gaps.
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. The description adds meaningful context beyond the schema: items must use codes from get_rate_card, up to 100 lines, note is never parsed and never changes the figure, and language is recorded. These extra notes enrich parameter understanding without repeating schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Price a specific set of line items against a business's rate card.' It clearly distinguishes the tool from siblings by naming get_rate_card as a prerequisite and commit_order as the later binding step, so the purpose is unambiguous and differentiated.
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 instructs to call get_rate_card first and use its code values. Also clarifies when to use alternatives: commit_order re-prices at bind time, and escalations are polled with check_escalation. It even tells the agent to change quantity and call again for 'quantity-out-of-range'. This is thorough usage guidance with exclusions and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
reschedule_orderAInspectMove an order you placed to a different date, or a booking to a different slot. The price, the items and the quantity are unchanged — this moves WHEN, nothing else. To change what was ordered, use request_order_change. A booking made for a time must be moved to a time, and a whole-day order to a whole day; the new slot is checked exactly as commit_order checked the first one. Call check_availability first. Returns settled, and when true from and to, plus remainingReschedules — an order may be moved a limited number of times before a person is asked instead. False comes with a reason: "slot-taken", "not-a-slot-start", "closed-that-day", "blackout-date", "capacity-full", "inside-lead-time", "date-in-past", "time-required", "time-not-supported", "inside-cancel-window", "too-many-reschedules" or "not-open". Some are yours to fix and carry freeSlots; the rest return an escalation for check_escalation. Authentication: bearer token required, and it must be the same agent that placed the order.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | The `ref` returned by commit_order. | |
| date | Yes | The new day, as yyyy-mm-dd in the business's own local calendar. | |
| note | No | Optional. Why, in the buyer's own words. Shown to the business, never parsed. | |
| time | No | The new slot start, HH:MM in 24-hour time and in their timezone. Required if the order was made for a time; leave it out if it was made for a whole day. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It discloses the limited reschedules, exact reason codes, escalation behavior, and authentication requirements (same agent, bearer token). This goes well beyond a simple 'move' statement.
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 long but front-loaded with the core purpose and includes necessary details like error codes and auth. It is somewhat dense but each sentence contributes value; a slight trim of the exhaustive reason list would be possible.
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?
Given the complexity (no output schema, multiple failure modes), the description fully covers behavior, prerequisites, return values, error handling, and escalation. It leaves little ambiguity for an agent to correctly invoke and interpret the 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 description coverage is 100%, so the baseline is 3. The description restates the time-required constraint but does not add meaningful new semantics beyond what the schema already documents.
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 action: move an order/booking to a different date/slot, and explicitly distinguishes from request_order_change for altering content. It clearly identifies the resource and the scope (WHEN, not WHAT).
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?
Provides explicit guidance: use for rescheduling only, use request_order_change for item changes, and call check_availability first. Also clarifies constraints for time-based vs whole-day orders, offering practical usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_businessesAInspectFind businesses, merchants and websites in the tunnel knowledge base by name or topic. Start here: every other tool needs a slug, and this is where a slug comes from. Returns an array of summaries, each with slug, kind, name, description and a verification object. Read verification.level rather than assuming: "human" means a tunnel employee checked the business, "automated" means machines proved only that the business controls its own channels, and null means neither. Zero matches is a normal answer, not an error — it comes back with completeness "empty". Authentication: none. This tool works with no credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Optional. Return only records of this kind. | |
| limit | No | Optional. Maximum results, 1 to 50. Defaults to 20. | |
| query | Yes | Name, topic or place. Words are matched independently against the name, location, description, offerings and FAQ, and most of them have to appear somewhere in a record, so "cakes in Chisinau" works. Accents are ignored, so the unaccented spelling is fine. This matches words, not meanings: a business calling itself a "cofetăria" will not be found by searching "bakery". If nothing comes back, try the words the business would use about itself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: authentication is none, it works without credentials, returns an array with specific fields, explains the verification object and its levels, and describes the empty result response. No contradictions.
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 a single paragraph of 6 sentences, front-loaded with purpose and key advice. Every sentence adds unique information (purpose, entry-point, return format, verification, error handling, authentication). No wasted words.
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?
Given 3 parameters, no output schema, and no annotations, the description covers all critical aspects: purpose, usage context, return structure with verification, behavior on empty results, authentication, and parameter tips. It is fully complete for agent decision-making.
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 baseline is 3. The description adds significant value beyond the schema: explains query matching logic (words independently, accents ignored, examples), default limit, and optional type. This enhances usability.
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 explicitly states the tool's action ('find'), resource ('businesses, merchants and websites'), and scope ('by name or topic'). It also differentiates this tool from siblings by noting that every other tool needs a slug from this one.
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?
The description explicitly positions this tool as the entry point ('Start here: every other tool needs a slug, and this is where a slug comes from'). It also explains that zero matches is a normal answer, not an error. While it doesn't explicitly list when not to use it, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_followupAInspectAdd another message to a conversation already opened with contact_business. Returns the updated message thread. There is a cap on messages per conversation, so send one considered follow-up rather than several fragments. Authentication: bearer token required — the same one used for contact_business — plus the conversation_id and token for the conversation itself.
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | The secret `token` returned by contact_business. | |
| message | Yes | The message body. Maximum 4000 characters. | |
| conversation_id | Yes | The `conversation_id` returned by contact_business. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It mentions the message cap, return of the updated thread, and authentication requirements. It doesn't detail rate limits or error handling, but the disclosed cap is a key behavioral trait for a follow-up tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences cover purpose, usage guideline, and authentication/details. No redundant information; every sentence adds value. The structure is front-loaded with the main action.
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?
Given 3 required parameters, no output schema, and no annotations, the description provides necessary context: purpose, prerequisite (contact_business), cap, and authentication. It could briefly note that message is the content, but that's in schema. Overall adequate.
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% with descriptions for each parameter. The description adds value by explaining that token and conversation_id come from a prior contact_business call, providing context beyond the schema. This clarifies the parameter relationships.
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 explicitly states the tool adds a message to an existing conversation opened with contact_business, distinguishing it from sibling tools like contact_business (which opens the conversation) and check_replies. The verb 'add' and resource 'message to conversation' are clear.
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?
The description warns about a message cap per conversation, guiding the agent to send one considered follow-up rather than fragments. It also notes the required authentication and the need for conversation_id and token from contact_business, implying that contact_business should be called first. However, it doesn't explicitly list alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!