Writing pages agents can use

You don't need to learn a new format to write for agents. Good pages for an agent are mostly just good pages: clear, specific, organized by topic. But there are a few things about how Herald reads your pages that change what "good" means in practice, and they're worth knowing before you write a lot.

How your page gets read

When you publish a page, it's split into sections at its headings. Every #, ## and ### heading starts a new section; anything deeper (#### and below) stays inside the section above it. Each section remembers where it came from, so a ### Group bookings under ## Pricing on a page called "Plans" is stored as:

Plans › Pricing › Group bookings

When an agent asks for context, search runs over these sections, not over whole pages. The agent usually gets the handful of sections that best match its task, plus your rules and anything a pack says it always needs.

Three things follow from that, and almost everything else on this page is a consequence of them:

1. A heading is what gets found. The heading path is part of what search matches on, so a specific heading pulls its section into the right tasks and a vague one doesn't.
2. A section has to make sense alone. It may arrive without the sections around it. If it only makes sense after reading the paragraph above, the agent won't have that paragraph.
3. Size matters. A short, focused section that matches a task beats a long one that partly matches. Sections over roughly 700 tokens (about 500 words) are split at paragraph breaks, and the pieces lose some of their context when that happens.

One topic per heading

This is the single most useful habit. If a page covers four competitors, give each competitor its own ## heading. If it covers three personas, same again. Then a task about one competitor gets that competitor, not a page about all four.

Compare these two ways of writing the same thing.

## Competitors

We mostly come up against Bookwell and Slotly. Bookwell is cheaper for
small teams but has no group bookings, and their API is read-only. Slotly
has group bookings but charges per seat, which gets expensive past twenty
staff. When a prospect mentions either, focus on...

## Bookwell

Cheaper than us for teams under five. Where they win: price, a simpler setup.

Where we win: group bookings (they have none) and a full read-write API
(theirs is read-only).

When a prospect brings them up: ask how many staff will take bookings...

## Slotly

Has group bookings, like us. Charges per seat, so past about twenty staff
we're cheaper...

The second version is longer, and it's better in every way that matters. An agent writing a comparison page against Slotly gets exactly the Slotly section. The first version gets returned whole or not at all, and the agent has to work out which half applies.

Good headings are specific and say what's underneath: "Refunds after a downgrade", "Discounts reps can offer", "How booking rules work". Headings like "Overview", "Misc", "Notes" or "Other" are close to useless for search, because they could be about anything.

Write sections that stand alone

Read any one of your sections and imagine it's the only thing the agent was given. Does it still make sense?

The usual problems are references to things outside the section:

• "As mentioned above..." (the agent didn't see above)
• "This plan..." (which plan?)
• "See the table below" (it might not have the table)
• Pronouns that point at the previous section's subject

The fix is usually a few words. "The Team plan includes..." instead of "It includes...". Repeating a name costs almost nothing and saves the agent from guessing.

You don't need to repeat everything. The section's heading path travels with it, so the agent always knows the page and heading it came from. "Plans › Team › What's included" already tells it which plan, as long as the heading says so.

Say the actual thing

By default, agents are told to use only facts, quotes and numbers that appear in the context they get back, and to say so when something's missing instead of making it up. That's a good rule, but it means anything you leave vague stays vague.

• Put the number in. "Most customers see results within a few weeks" gives an agent nothing to cite. "Median time to first booking is 9 days (from our 2026 onboarding data)" does.
• Name things. "A large hospital group" can't be quoted in a case study. "Harbor Health, 14 clinics" can, if you're allowed to.
• Write down the reasons, not just the conclusions. "We don't offer monthly billing on the Enterprise plan because procurement teams want one annual PO" lets an agent answer the follow-up question.
• Include the edge cases you keep explaining. The one-off question that comes up every week is exactly the thing that should be written down.

If you find yourself writing "TBD", either leave the heading out until you know, or write what's true now ("Pricing for the API add-on hasn't been set yet; don't quote one").

Examples beat adjectives

This matters most on voice and style pages. "Confident, warm, never salesy" reads as a clear brief to a person and as almost nothing to a model, because every brand says that. What works is showing it.

## Sounds like us

- "Your clinic's bookings, in one place. Set it up before lunch."
- "We'll credit the difference to your next invoice. Nothing to do on your end."

## Doesn't sound like us

- "Unlock the power of seamless scheduling!"
- "We apologize for any inconvenience this may have caused."

Three or four pairs like that will do more than a page of description.

Keep rules short and few

A rule page goes out with every request, whole, even when it pushes past the token budget. That's what makes rules reliable, and it's also why you should be strict about what goes in one.

A good rule is something that would be a real problem if an agent got it wrong once: a claim you legally can't make, a discount that needs sign-off, a word your CEO hates, a roadmap date nobody's allowed to promise. Write each one as a short line. Put the long explanations on a normal reference page and link to it.

If your rule pages add up to more than a page or two, some of what's in them probably belongs in a pack instead. Rules, pinned pages and packs has more on choosing between them.

Use usage notes for "how to use this"

Every page has an optional usage note: one line that travels with the page's content every time it's sent, shown right under the page title. It's the place for instructions about the page rather than facts in it.

Good usage notes:

• "Quote prices only from this page. If a price isn't here, say it needs confirming."
• "Internal positioning. Never name a competitor in published content."
• "Only cite customers and stats from this page. If it's not here, it's not citable."
• "For engineers. Customer-facing writing should describe the behavior, not the endpoints."

Keep it to one line. If it needs a paragraph, it's probably a rule.

Link pages together

Write [[Page Title]] to point at another page, the way you would in a wiki. In the editor it turns into a chip you can click (it's struck through if no page has that title). Agents see the brackets and can call read_page with the title inside to follow the link.

Links are useful when a section depends on something defined elsewhere: "Discounts follow the approval rules in [[Pricing and packaging]]." If you rename a page, links to it across the workspace are updated for you, as long as the old and new titles aren't shared with another page.

Name things the way people say them

Search matches on meaning and on exact words, so it helps when your pages use the same terms your team uses when they ask for things. If everyone says "the hospital deal" and your page only says "Harbor Health", say both once.

For names that come up a lot (competitors, products, personas, regions), add them to your tag vocabulary with their aliases. Then "AvaTax", "Ava" and "Avalara" all point at the same thing.

Give folders real names

The folder a page sits in is part of what search sees, alongside the page's type and tags. "Support / Billing / Refund policy" is easier to find for a billing question than "Docs / Misc / Refund policy". You don't need a deep tree. A few well-named folders is plenty.

Set an expiry date on anything temporary

A launch promotion, a conference offer, a pricing change that only applies this quarter: set the page's Expires date. After that date it stops being sent by get_context and stops showing up in search. It stays in the workspace, so you can update the date or reuse the page next time.

Check how it came out

After you publish, open How agents see this page at the bottom of the page. It lists every section with its heading path, its size in tokens and the tags it picked up. A quick look will tell you:

• whether a section is far bigger than the rest (split it with a heading),
• whether a heading path reads well out of context,
• whether a section has picked up a tag it shouldn't have, or missed one it should.

A quick checklist

Before you publish a page you care about:

• Each distinct topic has its own heading, and the headings are specific.
• Any section makes sense on its own.
• Numbers, names and dates are written out, not implied.
• Anything that must never be skipped is on a rule page, in one short line.
• The page has a usage note if it needs to be used in a particular way.
• Temporary content has an expiry date.

Then connect an agent, give it a real task, and read what comes back. That loop (write, ask, read, fix the page) is how workspaces get good.