Knowledge Base

Find 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.

Read 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.

Check 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.

Ask 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.

Same 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.

Read 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.

Read 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.

Read 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.

Price 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.

Find 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.

Place 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.

Cancel 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.

Move 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.

Raise 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.

Open 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.

Read 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.

Add 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.