search_businesses

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.

Parameters3

query	string	required	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.
type	string	optional	Optional. Return only records of this kind.
limit	number	optional	Optional. Maximum results, 1 to 50. Defaults to 20.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "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."
    },
    "type": {
      "type": "string",
      "enum": [
        "company",
        "merchant",
        "organization",
        "person",
        "other",
        "website"
      ],
      "description": "Optional. Return only records of this kind."
    },
    "limit": {
      "type": "number",
      "description": "Optional. Maximum results, 1 to 50. Defaults to 20."
    }
  },
  "required": [
    "query"
  ]
}

get_business

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.

Parameters2

slug	string	required	The `slug` field from a search_businesses result.
kind	string	optional	Optional. The `kind` field from the same search result. If omitted, "entity" is tried first, then "website".

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The `slug` field from a search_businesses result."
    },
    "kind": {
      "type": "string",
      "enum": [
        "entity",
        "website"
      ],
      "description": "Optional. The `kind` field from the same search result. If omitted, \"entity\" is tried first, then \"website\"."
    }
  },
  "required": [
    "slug"
  ]
}

check_merchant_verification

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.

Parameters1

slug

string

required

The `slug` field from a search_businesses result, or the merchant numeric id.

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The `slug` field from a search_businesses result, or the merchant numeric id."
    }
  },
  "required": [
    "slug"
  ]
}

contact_business

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.

Parameters6

slug	string	required	The `slug` field from a search_businesses result.
kind	string	optional	Optional. The `kind` field from the same search result.
agent_name	string	required	Who is writing, in words the business will read — e.g. "Claude, on behalf of a customer".
subject	string	required	Short subject line, like an email subject.
message	string	required	The message body. Maximum 4000 characters.
agent_contact	string	optional	Optional. An out-of-band address the business can reply to, e.g. the end user email if they agreed to share it.

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The `slug` field from a search_businesses result."
    },
    "kind": {
      "type": "string",
      "enum": [
        "entity",
        "website"
      ],
      "description": "Optional. The `kind` field from the same search result."
    },
    "agent_name": {
      "type": "string",
      "description": "Who is writing, in words the business will read — e.g. \"Claude, on behalf of a customer\"."
    },
    "subject": {
      "type": "string",
      "description": "Short subject line, like an email subject."
    },
    "message": {
      "type": "string",
      "description": "The message body. Maximum 4000 characters."
    },
    "agent_contact": {
      "type": "string",
      "description": "Optional. An out-of-band address the business can reply to, e.g. the end user email if they agreed to share it."
    }
  },
  "required": [
    "slug",
    "agent_name",
    "subject",
    "message"
  ]
}

check_replies

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.

Parameters2

conversation_id	number	required	The `conversation_id` returned by contact_business.
token	string	required	The secret `token` returned by contact_business.

Raw schema

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "number",
      "description": "The `conversation_id` returned by contact_business."
    },
    "token": {
      "type": "string",
      "description": "The secret `token` returned by contact_business."
    }
  },
  "required": [
    "conversation_id",
    "token"
  ]
}

send_followup

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.

Parameters3

conversation_id	number	required	The `conversation_id` returned by contact_business.
token	string	required	The secret `token` returned by contact_business.
message	string	required	The message body. Maximum 4000 characters.

Raw schema

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "number",
      "description": "The `conversation_id` returned by contact_business."
    },
    "token": {
      "type": "string",
      "description": "The secret `token` returned by contact_business."
    },
    "message": {
      "type": "string",
      "description": "The message body. Maximum 4000 characters."
    }
  },
  "required": [
    "conversation_id",
    "token",
    "message"
  ]
}

com.tunnelpowered/knowledge-base