A Support Agent for Theme Buyers: Docs + MCP + Chat

A support agent for theme buyers works when three layers are built deliberately and in the right order: documentation structured as retrievable, atomic facts rather than long-form prose; a tool layer (increasingly standardized as MCP — the Model Context Protocol) that lets an assistant call real, scoped functions instead of guessing; and a chat surface that knows when to answer directly, when to call a tool, and when to hand off to a human. Skip any one layer and the agent either hallucinates confidently or becomes a glorified search box. This case study walks through building that stack for a digital-goods storefront — the kind that sells design assets and themes — using what actually works today, not what a marketing page promises.

This is a forward-looking, architecture-first piece. Polo Themes today sells Figma UI kits and Shopify OS 2.0 themes, not a packaged support-agent product — but the underlying problem (customers asking "does this work with X," "how do I install this," "what's the difference between these two bundles") is universal to any theme or template business, and it's exactly the kind of problem headless, API-first, AI-native commerce is built to solve well. The rest of this post is a practitioner's guide to building that system, grounded in how retrieval, tool-calling, and support triage actually behave in production.

The Problem With "Just Add a Chatbot"

Most AI customer-support projects start backwards. A team picks a model, points it at a help-center export, wraps it in a chat widget, and ships. It demos well because the first few questions are softball ones the docs already answer clearly. It falls apart on the questions that actually generate support tickets: "I bought the bundle last month, does this update include the new sections," "my Shopify theme won't let me add a fourth image block, is that a bug or a plan limit," "which Figma kit works with the Auto Layout version I'm on." Those questions aren't answered by prose — they require state (what did this customer buy, when) and structure (what changed between versions, what's a known limitation vs. a bug). A model with no tools and no structured source can only pattern-match against whatever text it was given, and it will pattern-match its way into a wrong answer stated with total confidence.

The fix isn't a better model. It's giving the model the same three things a good human support agent has: a well-organized knowledge base it can search precisely, tools it can call to check real account and order state, and clear rules about when to say "I don't know, let me get a person."

Layer One: Docs Structured for Retrieval, Not for Reading

The single highest-leverage decision in this whole stack is how the documentation is written and chunked — and it's the one teams skip because it looks like busywork compared to picking a model or a vector database. Long-form docs written for a human to read top-to-bottom are bad retrieval sources. A 2,000-word "Getting Started With Your Shopify Theme" page might contain the one sentence that answers a customer's question, buried between six paragraphs of unrelated setup steps. When that page gets embedded and chunked mechanically — say, every 500 tokens — the answer often lands split across two chunks, or surrounded by enough irrelevant context that the retrieval step ranks a worse chunk higher.

The alternative is writing (or re-deriving) docs as atomic, self-contained facts: one question, one scoped answer, tagged with the product, version, and category it applies to. "Does the Optics theme support a fourth product image without an app?" gets its own entry with a direct yes/no and the one-sentence why. This is closer to how a well-run FAQ or knowledge-base article is structured than how a tutorial is written, and it maps naturally onto how support tickets actually arrive — as single, specific questions, not requests to read a manual.

Metadata is not optional

Every chunk needs machine-readable metadata attached: which product it describes, which version it was true as of, whether it's a policy (refunds, licensing) or a technical fact (compatibility, setup steps), and a last-verified date. Without this, retrieval treats a fact about last year's theme version identically to a fact about the current one, and the agent will confidently answer with stale information. This is the same discipline good technical writers already practice — versioned docs, changelogs, deprecation notices — just made explicit enough for a retrieval system to filter on it instead of a human skimming for context clues.

Write the boundary cases, not just the happy path

The questions that actually reach a support inbox are disproportionately edge cases: partial refunds, license transfers, "I bought under my old email," version compatibility across an upgrade. A doc set optimized for a support agent should over-invest in exactly these boundary questions relative to how a marketing-facing help center would prioritize them, because that's where an ungrounded model is most likely to fabricate a plausible-sounding but wrong answer.

Layer Two: Tools via MCP, Not a Prompt That Begs for Honesty

Retrieval alone answers "what does the documentation say." It cannot answer "what did this specific customer buy" or "is this order eligible for a refund," because those require live lookups against real systems — order history, license status, entitlement records. This is where the Model Context Protocol (MCP) matters: it's an open, increasingly standard way to expose a set of callable tools (and readable resources) to an LLM client in a uniform shape, instead of every vendor inventing its own bespoke function-calling schema. For a support agent, the practical effect is that "look up this order" or "check this license's activation count" becomes a well-typed tool call the model can invoke and get a structured result back from — not a paragraph of instructions hoping the model behaves.

The design discipline that matters here is scoping tools narrowly. A tool called "look up order by ID" that returns exactly order status, items, and refund eligibility is safe and predictable. A tool that hands the model broad database or admin access "so it can figure out what it needs" is how support bots leak other customers' data or take actions nobody authorized. Every tool exposed to the assistant should be built the way you'd build a public API endpoint: least privilege, explicit inputs, a response shape the model can't misinterpret, and no destructive action available without a confirmation step or a human in the loop.

• Read-only by default: order lookup, license status, doc search should be tools the agent can call freely; anything that changes state (issuing a refund, resending a license key) should require an explicit confirmation step, ideally with a human able to review before it executes.
• Typed, narrow responses: a tool should return "order #4821: Optics bundle, purchased 2026-03-14, refund window closed" — not a raw database row the model has to interpret and could misread.
• Rate-limited and logged: every tool call from the agent should be logged with the conversation ID, so a support lead can audit exactly what the assistant looked up and why it answered the way it did.
• Fails closed: if a tool call errors or times out, the agent's fallback should be "I couldn't check that — let me connect you with a person," never a guess dressed up as a lookup result.

Layer Three: The Chat Surface — Routing, Not Just Replying

The chat widget itself is the least technically interesting layer and the one most teams over-invest in polishing before the underlying stack is sound. What actually matters at this layer is routing logic: deciding, per message, whether the right move is answering from retrieved docs, calling a tool, asking a clarifying question, or escalating to a human — and doing that classification cheaply and reliably before the expensive generation step runs.

A well-built support agent is honest about its own confidence. If retrieval returns weak matches and no tool clearly applies, the right answer is "I'm not certain — here's what I found, and here's how to reach a person," not a fluent paragraph built from thin evidence. This matters more for a theme and template business than it might for, say, a shipping-status bot, because the questions people ask about design assets — licensing, compatibility, customization limits — have real financial and legal weight if answered wrong. An agent that's occasionally slower to hand off but never confidently wrong builds more trust over a year of support interactions than one that answers everything instantly and is wrong ten percent of the time.

Escalation is a feature, not a failure

Teams sometimes measure a support agent's success by how rarely it hands off to a human, which is the wrong metric. The right metric is whether the *handoffs that do happen* arrive at a human with useful context already attached — the customer's question, what the agent found and didn't find, and what it already tried — so the human isn't starting cold. An agent that escalates promptly with a clean summary is doing its job well even if its deflection rate is modest; one that never escalates and just talks its way through uncertainty is optimizing for the wrong thing entirely.

Where This Intersects Headless and Next.js Storefronts

This architecture is a natural fit for headless, API-first commerce specifically because the three layers — docs, tools, chat — are all just services behind APIs, which is exactly the shape a Next.js or similar headless storefront is already built around. A monolithic theme editor bolts a chat widget on as a third-party script; a headless setup can treat the support agent as another consumer of the same commerce API the storefront itself uses for orders and entitlements, with the MCP tool layer wrapping those same endpoints instead of duplicating access logic. That composability is a large part of why headless and AI-native tooling are converging right now: an agent that needs to check "is this order refund-eligible" benefits enormously from a commerce backend that already exposes that as a clean, typed call rather than something buried in server-rendered page logic.

None of this requires abandoning a well-built Shopify or Figma-based workflow today — a store on our Shopify theme catalog can layer a support agent on top of order and app data the same way, just with a bit more integration glue than a purpose-built headless API provides natively. But it's worth understanding this stack now if a headless migration or an AI-native storefront rebuild is anywhere on the roadmap, because the docs-structuring work in particular pays off regardless of which commerce backend eventually sits behind it.

A Practical Build Order

If a team is building this from scratch, the sequence that avoids the most rework looks roughly like this: rewrite or re-derive the highest-traffic support answers as atomic, tagged doc entries first, before touching any model or framework. Then wire a small number of tightly scoped, read-only tools — order lookup and license status are almost always the highest-value first two — and test the agent against real historical support transcripts, not synthetic questions. Only after those two layers are solid does the chat surface and its routing logic become the interesting problem, because by then the agent has something honest to say most of the time, and the remaining work is deciding gracefully when it doesn't.

• Weeks 1-2: audit real support tickets from the last quarter; rewrite the top 80% of recurring questions as atomic, versioned, tagged doc entries.
• Weeks 3-4: build and test two or three narrow, read-only MCP tools (order lookup, license/entitlement check) against a staging copy of real data.
• Weeks 5-6: wire routing logic and confidence thresholds; run the agent against last quarter's real transcripts before ever showing it a live customer, and measure how often it would have answered correctly, escalated appropriately, or gotten it wrong.
• Ongoing: log every tool call and every escalation; review a sample weekly and feed corrections back into the doc set, since stale or wrong doc entries are the most common cause of agent drift over time.

Frequently Asked Questions

Do I need MCP specifically, or can I just use function calling?

Standard model-provider function calling works fine for a single-vendor, single-model setup. MCP's advantage is standardizing the tool interface so the same tool server works across different clients and models without rewriting the integration each time — valuable if you expect to change model providers, add multiple client surfaces (chat widget, internal support console, an IDE-based agent), or want tools built once and reused broadly.

What's the single biggest mistake teams make building a support agent like this?

Starting with the model and the chat widget instead of the docs. Retrieval quality is capped by how well the source material is structured; no amount of prompt engineering fixes an agent that's searching over unstructured, unversioned prose.

Should small teams build this themselves or buy a support-AI product?

For a small catalog and modest support volume, a well-maintained FAQ plus a lightweight retrieval layer over your own docs often gets most of the value with a fraction of the engineering cost. The tool-calling and MCP layer earns its complexity once support questions genuinely require live account or order state, not just documentation lookups.

How does this relate to Polo Themes' own products today?

Polo Themes currently sells Figma UI kits and Shopify themes, not a packaged support-agent product. This piece is a practitioner's architecture guide written from expertise in the space we're building toward — headless, API-first, AI-native commerce tooling — and it applies whether you're running a Shopify store today or planning a Next.js storefront tomorrow.