You've set up your AI agent. You've given it instructions. It handles a few basic tasks — and then it hits a wall. It gives wrong answers, makes up policies, and generally behaves like someone who skimmed the Wikipedia summary instead of reading the book.

The problem isn't the agent. It's the knowledge base.

Most people dump a few documents into a folder, point their agent at it, and hope for the best. That works about as well as handing a new hire a stack of printed PDFs and saying "figure it out." The agent needs structure, clarity, and context — not a data dump. Here's how to build a knowledge base that actually makes your agent smarter.

Write Like Your Agent Has No Common Sense

Here's the most important thing to understand: an AI agent has read a lot of text, but it has no lived experience. It doesn't know that "ship within 24 hours" means business days unless you say so. It doesn't know that "call the customer back" means within the same business day unless you specify.

When you write for an agent, assume zero implicit understanding. Every edge case, every ambiguity, every "everyone knows that" assumption — spell it out. This doesn't mean writing a novel. It means writing precise, unambiguous instructions.

Bad: "We offer refunds within 30 days."
Good: "We offer full refunds within 30 calendar days of purchase. Refunds are processed back to the original payment method within 5-7 business days. After 30 days, refunds are at manager discretion — escalate to the support lead. Refunds require the customer's order number and email address. Partial refunds are available for subscription customers who used the service for 14+ days."

The good version removes every assumption. The agent can act on it without guessing.

Structure for Retrieval, Not Reading

Your agent doesn't read your knowledge base like a person does — it searches it. The difference matters. A human might enjoy a narrative flow. An agent needs chunks it can retrieve and return verbatim.

The best structure is modular, hierarchical, and self-contained:

  • Top-level categories — "Pricing", "Shipping", "Returns", "Product Specs", "Internal Processes"
  • Atomic entries — each entry covers exactly one concept or policy
  • Concise titles — "Return Policy — Physical Goods" not "Information Regarding Our Policies for Returns of Physical Products"
  • Standalone content — each entry should be understandable without reading other entries

Here's what a good entry looks like:

## Shipping Policy — Domestic (US)
- Carrier: USPS Priority or UPS Ground
- Cost: Free for orders over $50, otherwise $7.99 flat rate
- Transit time: 3-5 business days (not calendar days)
- Tracking: Sent via email when label is created
- PO Boxes: USPS only — UPS cannot deliver to PO Boxes
- Holiday cutoffs: Orders placed after Dec 20 may not arrive by Dec 24

This is retrieval-ready. The agent can find the exact line it needs without wading through paragraphs of explanation.

Include Decision Trees for Ambiguous Situations

The hardest thing for an agent to handle is the gray area — situations where the answer depends on a chain of conditions. The best format for this is a decision tree written as nested bullet points or if/then statements.

## Refund Decision Tree
IF customer requests refund:
  1. Check purchase date against current date
  2. IF within 30 days → process full refund (no questions)
  3. IF 31-60 days → partial refund only (50% of purchase price)
     - Exception: IF order was damaged → escalate to manager
  4. IF over 60 days → do NOT refund
     - Offer store credit at manager's discretion
     - IF customer is a VIP tier subscriber → escalate to manager

Decision trees eliminate guesswork. The agent follows the branches and reaches the correct outcome every time. You can audit the logic in advance, and when it goes wrong, you can pinpoint exactly which branch needs fixing.

Keep a Single Source of Truth

One of the most common failure modes I see: a business has its refund policy in a PDF, on the website footer, in a Slack message from last month, and in a Notion page that three different people have edited. The agent, trying to be helpful, picks the wrong version.

The fix is brutal and simple: one source of truth. Choose a single document or folder that your agent reads at the start of every session. Everything else is out of bounds. When the policy changes, update the one source. That's it.

This applies to internal processes too. If your agent handles scheduling, the scheduling SOP lives in the single source. If it handles email triage, the triage rules live there. No fragmentation, no ambiguity, no stale copies floating around.

Audit by Asking Your Agent Questions

You can't trust that your knowledge base is good — you have to test it. The testing process is simple: ask your agent the questions your customers or team members actually ask, and see what it answers.

Run through scenarios like these:

  • "A customer ordered a product 45 days ago. It arrived damaged. What do I do?"
  • "Someone is asking about our return policy on the live chat. What do I say?"
  • "A team member wants to know who handles enterprise escalations. Where do I route this?"

For each question, check: did the agent find the right entry? Did it interpret the policy correctly? Did it miss an exception? Correct what you find, and then re-test the same questions. Within a few rounds, your knowledge base will tighten up significantly.

This is also how you discover gaps. If the agent can't answer a question, you don't have that information in your knowledge base. Add it.

The Maintenance Cadence

Knowledge bases decay. Products change, policies shift, new situations arise. A knowledge base that was perfect in January is mediocre by June and harmful by December.

Set a recurring maintenance schedule:

  • Weekly (5 minutes): Review the last week's agent interactions. Did the agent fail on anything it should have handled? Update the relevant entry.
  • Monthly (30 minutes): Scan for outdated information. Did a price change? A shipping partner? A policy update? Fix it.
  • Quarterly (1 hour): Do a full scenario audit. Run through 10-15 realistic questions and see if the agent handles them correctly. Refactor entries that are causing confusion.

This isn't busywork. It's the difference between an agent that stays useful and an agent that quietly goes stale.

A Worked Example: The Product Spec Entry

Let me show you what a good, complete entry looks like — this is for a fictional SaaS product called "Timely":

## Product: Timely (Time Tracking SaaS)

### Tiers and Pricing
- Free: Up to 5 projects, 3 users, basic reporting — $0
- Pro: Unlimited projects, 15 users, advanced reporting, integrations — $29/user/month
- Enterprise: Unlimited everything, SSO, dedicated support, custom integrations — Contact sales

### Key Features by Tier
- Free: Manual time entry, basic dashboard, CSV export
- Pro: Timer, calendar sync, team dashboards, QuickBooks/Xero integration, API access
- Enterprise: All Pro features + custom roles, audit logs, SLA, on-prem option

### Billing
- Pro is billed monthly or annually (annual = 2 months free)
- Enterprise is annual only, invoiced quarterly
- Trials: 14-day free trial on Pro, no credit card required
- Cancellation: Cancel anytime. If cancelled mid-cycle, access continues through the end of the billing period

### Support SLA
- Free: Email only, 48-hour response target
- Pro: Email + live chat, 4-hour response target (business hours)
- Enterprise: Dedicated account manager, 1-hour response target, 24/7

This entry is structured, self-contained, and retrieval-friendly. An agent asked "What does the Pro tier cost?" finds "Pro: ... $29/user/month" in seconds. Asked "Can a Free user get API access?" it finds "Free: ... basic reporting" and correctly concludes no. Every piece of information is explicit and unambiguous.

The Bottom Line

Your agent is only as good as the information you give it. A well-structured knowledge base is the single highest-leverage investment you can make in agent performance. Write in unambiguous terms, structure for retrieval, build decision trees for gray areas, maintain a single source of truth, and audit regularly. Do this, and your agent will go from "it's okay, I guess" to "I don't know how I managed without it."

This post is part of a series on building practical, high-value AI agents. If you missed the earlier ones, start with Setting Up Your Personal AI Agent and How to Build an AI Agent That Actually Understands Your Business.