Domains & Tools

Savanto's chat assistant is a multi-agent pipeline. Each visitor message is routed to one or more domains that handle a specific kind of question — products, articles/policies, orders, accounts, or anything else you wire in. You configure domains under Workspace → Chat → Domains.

There are two kinds of domains:

Kind	When to use	Where it lives
Built-in	Product or post questions answered from your indexed catalog and content.	Configured automatically when you connect a site. Tools are an opt-in add-on.
Custom	Anything outside the indexed corpus — orders, accounts, inventory APIs, internal CRMs.	You author the classifier prompt, agent prompt, and tool surface yourself.

Most workspaces start with built-in domains alone. Custom domains come into play once you need the AI to call your own systems.

Built-in Domains

Built-in domains (Product and Post) ship enabled by default. Out of the box they answer from the indexed corpus Savanto builds for your workspace — products synced from your storefront, articles/pages crawled from your site, taxonomies, and so on.

For most product- and content-discovery questions this is enough: the curator agent picks the most relevant items from the corpus and explains them to the user. But some questions can't be answered from indexed data — "is this in stock right now?", "what's the price for my membership tier?", "how many of these are at the Toronto warehouse?". That's what built-in tools are for.

Attaching tools to a built-in domain

Open Workspace → Chat → Domains and click Configure on either the Product Domain or Post Domain card. The modal gives you four knobs:

Knob	What it does
REST tool endpoints	One or two endpoint groups, each with one or more REST endpoints. Same shape as the custom-domain editor, capped tighter (max 2 groups).
Tool usage hints	Free-form prose the curator sees alongside the tool list. Use it to spell out when to call your tools — e.g. "Call the inventory endpoint whenever the user asks about stock."
Max tool turns	How many tool-call turns the curator may take per user message. Default `2`. Range `1`–`5`. Higher values let the curator chain calls (e.g. lookup → enrich) at the cost of latency.
Per-tool progress messages	Override the auto-derived "Calling `<tool>`..." chip the widget shows during a tool call. Map a tool name to a workspace-authored message.

The curator agent will only call your tools when the indexed corpus can't answer the question on its own. If a tool call fails or returns nothing useful, it falls back to the indexed answer rather than fabricating a value.

How the curator decides

When tools are attached, the curator's prompt picks up an extra section that boils down to:

Trust the indexed corpus first. If the catalog or knowledge base answers the question fully, don't burn a turn on a tool call.
Reach for tools when the question requires live state — inventory, real-time pricing, account-specific values, anything the indexed corpus can't carry.
Pass arguments derived from the user query. Never invent IDs or hallucinate filter values.
Acknowledge tool failures briefly. If a call comes back empty, say so honestly — don't fabricate.
Cite tool-derived facts, not the tool name. The user doesn't need to know which API was called.

You can layer your own guidance on top via the Tool usage hints field — the curator treats that text as workspace-specific addenda to the rules above.

Per-domain caps

Built-in tools share the same per-domain caps as custom-domain tools:

Number of endpoint groups per built-in domain (max 2)
Tool turns per message (max 5, default 2)
The same per-tenant chat rate limits that already govern tool calls today

If you need more, get in touch — we issue per-workspace overrides for channel-partner and high-volume deployments.

Custom Domains

Custom domains are for everything that isn't already covered by Product or Post — order lookups, account profile reads, inventory dashboards, internal CRMs, anything reachable over HTTP or MCP.

Each custom domain has:

Field	Purpose
Classifier prompt	One or two sentences telling the triage agent when to route a message to this domain.
Agent prompt	The full system prompt for the curator agent that handles this domain.
MCP servers	Optional Model Context Protocol servers — the curator picks up their tools automatically.
REST endpoints	Optional REST tools (same editor as built-in domains). Up to 3 endpoint groups per domain.
Progress message	The status chip the widget shows while this domain is running.

Use the Test tab in the domain editor to verify your classifier prompt routes the queries you expect before flipping the domain to enabled.

Built-in vs. custom: when to pick which

A useful heuristic:

Stick with built-in tools when the question is fundamentally a product or content question and you just need a single live-data side fetch (inventory, pricing). The built-in curator already understands your catalog and has the right voice — adding an inventory tool to the Product domain is usually a smaller change than spinning up a whole custom domain.
Reach for a custom domain when the topic itself isn't products or content (orders, accounts, scheduling, anything visitor-specific) — or when the answer needs a different prompt voice and a fully custom tool surface.

Pre-1.x workspaces that wired inventory or pricing lookups via custom domains can usually consolidate them onto the Product domain now. The configuration is simpler and the curator has more context.

Programmatic configuration

For staged rollouts, you can configure built-in tools directly via DynamoDB using the bundled script:

node scripts/configure-builtin-tools.mjs \
  --domain=product \
  --config=./scripts/builtin-tools/my-config.json

Add TARGET=prod TENANT_ID=... WORKSPACE_ID=... to target a production workspace (uses your AWS credentials). The script is idempotent and busts the workspace-settings cache so the next chat request picks up the new tool surface — no cloud restart required.

The JSON file mirrors the dashboard form:

{
  "tools": [
    {
      "name": "inventory",
      "baseUrl": "https://api.example.com",
      "responseFormat": "json",
      "endpoints": [
        {
          "toolName": "check_inventory",
          "description": "Check live stock for a product SKU",
          "method": "GET",
          "path": "/inventory/{sku}",
          "parameters": []
        }
      ]
    }
  ],
  "toolProgressMessages": { "check_inventory": "Checking live stock..." },
  "maxTurns": 2,
  "usageHints": "Call check_inventory whenever the user asks about stock or availability."
}

Best practices

Start without tools. Make sure the built-in curator answers the bulk of questions from the indexed corpus before adding a tool surface.
Be explicit in usageHints. The curator's default policy is conservative — it skips tools when in doubt. If you want a tool called for a specific kind of question, say so plainly.
Keep maxTurns low. Each turn is an additional model round-trip. Two is usually enough; raise it only when you genuinely need chained calls.
Map progress messages. The default "Calling <tool>..." chip is fine for engineering, but a workspace-authored "Checking live inventory..." reads much better to a customer.
Cap response sizes upstream. Tools that return very large payloads will be truncated by the platform's safety guard. Use dropPaths on the endpoint to prune before the response reaches the curator.

Next Steps

AI Chat — How the chat assistant works end-to-end.
Workspaces — Connecting and managing sites.
Live Agent — Handing off to a human when the AI can't help.