Knowledge Guide: How to Structure What Your Agent Knows

Your Agent is only as good as the knowledge you give it, and how you organize that knowledge matters as much as what's in it. This guide explains how your Agent looks things up, why the same article copied across ten hotels works against you, and how to structure knowledge so your Agent answers correctly for every property. Follow it and you'll get more accurate answers and fewer "I don't know" moments.

Why Knowledge Quality Decides Everything

Think of your Agent as a seasoned concierge: years of experience, polished, completely at ease with guests. The one catch is that they have no memory of your hotel. They've never worked here, so they know nothing specific about your property: your rooms, your policies, your amenities. What they do have is a book, and the remarkable ability to look anything up in it instantly. For every guest question, they flip to the most relevant pages and answer from what's there. Give them a clear, complete, well-organized book and they shine. Give them a thin or messy one and they struggle, no matter how skilled they are.

That's how your Agent works: for each guest question it looks things up in the knowledge you've given it, then answers from what it finds. (In AI circles this look-it-up-then-answer approach is called retrieval-augmented generation, or RAG. You don't need the term, just the idea. There's a short reading list at the end if you're curious.) Your Agent doesn't browse the web or rely on outside facts, so if something isn't in its knowledge, or it's buried in noise, the answer suffers.

Good knowledge in, good answers out. For how Places and Resources fit together, see Understanding Your Agent's Knowledge: Places and Resources.

How Your Agent Looks Things Up

This is the part most people get wrong, and it changes how you should organize everything.

When a guest asks a question, your Agent doesn't open the folder for the guest's hotel and read through it. It searches all the knowledge in every Place assigned to it, by topic. Ask about parking and it pulls up the passages that best match "parking", wherever they live. It reads roughly 10 of them, ranked by how well they match the question, and answers from those.

A few things follow from this:

• It searches by topic first, property second. Your Agent does its best to prefer the property the guest is talking about, and it's told to ignore results from other properties. But every matching passage from every Place competes for the same roughly 10 spots.
• It reads passages, not whole documents. Long content is split into passages of about a page each. Each passage keeps its Resource name and the heading it sits under, so the Agent knows where it came from. It doesn't automatically see the rest of the document.
• It always gets its top matches. Even when nothing fits well, the best-matching passages still come through. Noise isn't harmless. It takes the place of something better.
• It works on meaning and on words. "Can I bring my dog?" finds your pet policy even if the policy never says "dog." Using the words guests actually use still helps it land on the right passage.

Back to the concierge. They don't read your book cover to cover for every question. They flip to the 10 pages that look most relevant and answer from those. Your job is to make sure the right pages exist, and that nothing crowds them out.

One Topic, One Resource

Here's the most common way knowledge goes wrong in hotel groups.

Say you run TrustYou Hotels & Resorts with properties in Berlin, Amsterdam, Munich, and five other cities. Your website has a parking page for each hotel, so you add each page as a Resource in each hotel's Place. Seven of those pages say the same thing: on-site garage, 25 euros a night, book at reception. The Munich page says there's no parking at all. The Amsterdam page points to a partner garage two streets away.

To you, that's eight neatly separated articles. To your Agent, it's eight passages that all match "parking" about equally well. When a guest asks about parking in Munich, the roughly 10 spots fill up with seven copies of "on-site garage, 25 euros" and, hopefully, the one Munich passage. The exception is outnumbered seven to one. Often the Agent still picks it out. Sometimes it doesn't, and the guest in Munich hears about a garage that doesn't exist.

The seven copies also add nothing. Your Agent doesn't need to read the same fact seven times.

The fix is to organize by topic, not by property. Write one Parking Resource:

1. Start with the general rule that applies everywhere.
2. List only what's different, property by property, in a short table or list.
3. Name the property in every line that's property-specific.

Before: eight Resources. After: one, roughly like this:

# Parking

Most TrustYou Hotels & Resorts have an on-site garage. Parking costs 25 euros per night.
Guests reserve a spot at reception on arrival.

## Exceptions by hotel

| Hotel | Parking |
|---|---|
| TrustYou Hotels & Resorts Munich | No parking at the hotel. Public garage "Stachus" is a five-minute walk, about 30 euros per night. |
| TrustYou Hotels & Resorts Amsterdam | No on-site garage. Partner garage Q-Park Centrum, two streets away, 35 euros per night with a hotel voucher. |

Now a parking question pulls up one general passage and one exceptions passage, both clear, with room to spare. Your Agent sees the rule and the exception side by side, and it knows exactly which hotel each exception belongs to.

Do this for every topic where most properties are alike: breakfast, check-in and check-out, pets, cancellation, Wi-Fi, gym, late checkout. Keep separate per-property Resources only for content that's genuinely unique to one place, like a restaurant menu or directions from the local train station.

Make Every Passage Stand on Its Own

Because your Agent reads passages, not documents, each passage has to make sense on its own. A few habits make that happen:

• Put the topic in the Resource name and in your headings. Each passage carries its Resource name and heading with it. "Parking > Exceptions by hotel" tells your Agent what it's looking at. "Info 3 > Section 2" doesn't.
• Repeat the property name in property-specific sentences. Don't rely on a heading three paragraphs up. "There's no parking at the hotel" could be about any property once it's cut out of context. "TrustYou Hotels & Resorts Munich has no parking at the hotel" can't be misread.
• Keep tables short. A table with a few columns and one row per property works well. A 40-row table with eight columns can get cut in the middle, and half a table is hard to read. Split long tables by topic, or switch to a bulleted list with the property name at the start of each line.
• One idea per paragraph. Short paragraphs under clear headings land in clean passages. A wall of text gets chopped at arbitrary points.

Organize Places for a Hotel Group

Places are the containers for your Resources, and a good layout makes the topic-first approach easy.

For a group with several properties, we recommend:

• One shared Place for brand-wide knowledge. Leave the address empty. Put your topic Resources here: parking, breakfast, policies, loyalty program, each with its exceptions table. Assign this Place to every Agent.
• One Place per property for what's unique there. The address, directions, the restaurant, local tips, the pool hours. Only content that has no equivalent at your other properties.

Two more things help your Agent find the right property:

• Name Places clearly and consistently. Your Agent matches what the guest says ("your hotel in Munich") against your Place names and addresses. "TrustYou Hotels & Resorts Munich" works. "TYHR-MUC-02" doesn't.
• Don't over-split. More Places don't mean more precision. Your Agent still searches all of them by topic. A few well-named Places with focused Resources beat dozens of thin ones.

For a single hotel, this is simpler: one Place, topic-focused Resources, and you're done.

Write for the Question, Not the Brochure

Guests ask questions. Write knowledge that answers them.

• Use the words guests use. Your Agent understands meaning, but matching words still helps it find the right passage. Say "parking," "garage," and "car park," not "vehicle accommodation." Say "check-in," not "arrival procedures."
• Lead with the fact. "Check-in starts at 3:00 PM" beats a paragraph about your warm welcome that mentions the time at the end.
• Want a specific answer to a specific question? Write it as a question and answer. An FAQ-style entry ("Can I check in early? Yes, from 1:00 PM for 20 euros, subject to availability.") gives your Agent the exact wording you want. This belongs in knowledge, not in Custom Instructions.
• Trim the noise. Marketing copy, navigation menus, and footers take up passage space without adding facts. For Website Resources, use Content Selectors to keep only the real content. See Adding a Website Resource.

Say What You Don't Offer

Here's the trick most people miss. It's not enough to document what you do offer. Tell your Agent what you don't.

The natural instinct is to document only what you have: your rooms, your restaurant, your amenities. So if your hotel has no pool, you simply don't mention a pool anywhere. That feels logical, but it leaves a hole. When a guest asks "Do you have a pool?", your Agent has nothing to find, and a blank is not an answer. Worse, in a hotel group, the best-matching passages about pools will come from the properties that do have one.

The fix is to write the negation down as knowledge. Your concierge can't flip to a page that doesn't exist. If you don't have a pool, the fact "this hotel does not have a swimming pool" needs to live on a knowledge page, just like your check-in time does. The Munich row in the parking table above is exactly this: it states what isn't there.

State the boundaries plainly and your Agent answers with confidence:

• "TrustYou Hotels & Resorts Berlin does not have a swimming pool."
• "Pets are not allowed at any of our hotels, with the exception of service animals."
• "We do not offer airport shuttle service."
• "Late checkout is not available on weekends."

A simple way to do this: keep a short Markdown Resource called something like "What we don't offer" and list the common no's in plain sentences, naming the property where it matters. It takes five minutes and removes a whole category of weak answers. Add a line whenever a guest asks about something you don't have, so the gap never reappears.

Keep One Version of Every Fact

If two sources disagree (an old policy says checkout is noon, a new one says 11:00 AM), your Agent can surface either one. Conflicting knowledge is one of the most common reasons an Agent gives inconsistent answers. Pick the correct version, keep it in one place, and remove the rest.

Outdated facts are worse than missing ones, because a confident wrong answer erodes trust. Review your knowledge regularly and remove anything that no longer applies. Website and Reviews Resources refresh on their own. Document and Markdown Resources change only when you update them, so they need a closer eye. For anything seasonal, put the dates in the text ("The rooftop bar is open May 1 to September 30") so your Agent can tell a guest when it applies.

What to Leave Out

More knowledge isn't always better. Some content adds noise or risk:

• Guest-specific or personal data. Your knowledge is shared across every Conversation, with every guest. Keep individual booking details and personal information out of it. (Personalized answers come from connected guest-data sources, not from shared knowledge.)
• Secrets and credentials. Passwords, API keys, internal-only links, and anything you wouldn't want repeated in a chat.
• Outdated or expired content. Last season's offers, old menus, retired policies. Remove them so they can't resurface.
• Duplicates. The same fact in eight places competes with itself and pushes out the exceptions. Keep one.
• Filler and marketing fluff. Long promotional copy with little factual content dilutes the useful parts and takes up passage space.

Facts Versus Behavior

A useful rule of thumb:

• Facts go in knowledge (Resources). This includes negative facts like "we have no parking on site."
• Behavior rules go in Custom Instructions. A light touch like "lead with our spa when a guest mentions relaxing" shapes how your Agent acts, not what it knows.

Custom Instructions run on every single message, so keep them short. Anything you want your Agent to say belongs in knowledge, where it's looked up only when relevant. See How the Agent Works.

Keep It Fresh

Knowledge isn't set-and-forget. Build a light habit:

1. Review your Insights and flagged messages for questions your Agent answered poorly or not at all.
2. Add or correct knowledge to close those gaps. If the problem was a cross-property mix-up, check whether the topic still lives in several copies.
3. Remove anything that's expired or no longer true.
4. Re-check after big changes (a renovation, a new policy, a seasonal menu).

A Quick Checklist

• Does each topic live in one Resource, with property differences in a short table?
• Is the property named in every property-specific sentence and table row?
• Do your Resource names and headings say what the content is about?
• Have you stated what you don't offer, not just what you do?
• Is there exactly one version of each fact?
• Is personal, secret, or outdated content kept out?
• Are behavior rules in Custom Instructions, not buried in knowledge?

Further Reading

Everything above lines up with what researchers have found makes the look-it-up-then-answer approach (RAG) work well. You don't need any of this to run a great Agent. The concierge and their book is all the model you need. But if you're curious, these are accessible starting points:

• Lewis et al. (2020), Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks (arXiv:2005.11401). The original idea: an AI answers better when it first looks up relevant documents instead of relying on memory.
• Gao et al. (2024), Retrieval-Augmented Generation for Large Language Models: A Survey (arXiv:2312.10997). A broad overview, including how much answer quality depends on the quality of the source content.
• Liu et al. (2024), Lost in the Middle: How Language Models Use Long Contexts (arXiv:2307.03172). Models pay the most attention to the beginning and end of what they're given, which is why concise, focused knowledge beats dumping in everything.
• Barnett et al. (2024), Seven Failure Points When Engineering a Retrieval-Augmented Generation System (arXiv:2401.05856). Common ways these systems go wrong, several of them rooted in missing, duplicated, or messy source content.
• Anthropic (2024), Introducing Contextual Retrieval (anthropic.com). Why each passage should carry enough context to stand on its own, the idea behind the "repeat the property name" advice above.

What's Next

• Understanding Your Agent's Knowledge: Places and Resources -- how Places and Resources fit together
• Creating and Managing Places -- set up the shared and per-property Places described above
• Adding Document and Markdown Resources -- write your topic Resources directly
• Adding a Website Resource -- pull in web pages and trim them to the real content