Set up Herald with your agent

This page is written for your agent, not for you. To use it, paste the link into a chat with Claude, ChatGPT, Claude Code or any agent that can read web pages, and say "set this up for me":

https://getherald.ai/docs/agent-setup

It works with what you already have and asks before changing anything. If you'd rather do it by hand, the Quickstart covers the same ground.

Introduction

This is Herald's setup guide for agents. The user shared it because they want to use Herald as the shared context for their agents: what their company does, who they work with, how they work and the rules they follow, in one workspace that every agent reads before it writes.

The steps below walk you through setup. First, how to talk to the user while you do it.

If the user asks you to review, summarize or compare this page rather than set it up, treat it as a document and don't run setup.

Rules for talking to the user

Follow these closely. They keep setup short and easy to follow.

• Show one step at a time, and end each step with one clear next step.
• Use everyday language. Assume the user isn't technical and is new to Herald.
• Start each step with why: what the user gets from it. Then explain how. Assume they could stop at any point.
• Keep each message to two to four sentences and at most two choices. Leave out lists, technical details and alternatives unless they ask.
• If your platform can show buttons or clickable choices, use them for decisions.
• Do as much checking as you need behind the scenes, but only share why the step matters, what you recommend, and the one decision you need.
• Keep going until setup is finished. After each step, lead the user to the next one.

Why Herald

What you know about the user's company disappears when the chat ends, and it stays inside one app. A new chat or a new agent starts from nothing. People paste the same background in again, and different agents give different answers.

A Herald workspace is a set of pages the user's team writes and publishes: a company overview, a brand voice, pricing, competitors, policies, whatever their work depends on. Any connected agent can ask for the context it needs for a task and get back the rules and the most relevant sections, within a token budget. The team decides what goes in and who can see it.

How it works once it's set up:

1. You call get_context with the task before you start.
2. You do the work using what came back, and say when something is missing.
3. When the user asks, you write what you learned back as a draft.
4. The team reviews and publishes it, and every agent starts the next task knowing more.

One-time setup

Do these steps in order.

1. Connect to the workspace

First check whether you already have Herald's tools (get_context, search, get_structure and others). If you do, skip to confirming the connection.

If you don't, set it up yourself if your platform lets you; otherwise tell the user exactly where to click. Use the sign-in URL, https://getherald.ai/api/mcp, so the connection acts as the user and sees exactly what they can see. Show only the directions for the platform you're running on:

• In Claude (web or desktop), go to Settings → Connectors → Add custom connector. Paste the sign-in URL, save, then click Connect and sign in with their Herald account.
• In ChatGPT, go to Settings → Apps & Connectors and create a connector with the sign-in URL, using OAuth for authentication. Some plans need developer mode turned on first.
• In Claude Code, run the command below, then run /mcp and choose the server to sign in.

claude mcp add --transport http context https://getherald.ai/api/mcp

For anything else, see Connecting your tools. If the user doesn't have an account yet, send them to https://getherald.ai/sign-in; creating one takes a company name and a workspace name. Wait for them to say they're back.

To confirm it worked, call list_workspaces and tell the user which workspace you're connected to (their default is marked). If they're in more than one, say so in one line and ask which one this setup is for; pass that name as workspace on every call from now on. Then call get_structure so you know what's already there. If list_workspaces isn't available, you're on an API key, which is tied to one workspace; use get_structure alone.

If something goes wrong, check Troubleshooting before asking the user.

Choose how much to set up

Right after you confirm the connection, show the user one choice. Use your platform's clickable choices if it has them, with the recommended option first and each option's full description. Only if it has none, show a numbered list and say they can reply 1 or 2.

Ask: "You're connected to [workspace]. How much do you want to set up?"

Option	Description
Set up my agents and fill in the workspace (Recommended)	I'll make sure your agents check Herald before they work, then help you write your first pages so they have something to read.
Just set up my agents	I'll make sure your agents check Herald before they work. Nothing gets added to the workspace.

If the workspace already has published pages for the basics, recommend the second option.

If they choose the first option, do steps 2 to 5. Their choice approves creating draft pages and private notes in step 3. Don't ask for that again; tell them what you made, with titles. Still ask before you publish anything or edit a page that already exists.

If they choose the second option, do step 2, then step 5. In the wrap-up, tell them they can share this page again any time to fill in the workspace.

2. Add standing instructions

Do this first. Connecting gives an agent the tools, but it doesn't make it use them every time: a request like "tidy this up" doesn't obviously look like it needs the company's context. A few lines in the user's own instructions fix that. If the user stops after one step, this is the one to finish. It takes one copy and paste.

Tell the user where to paste it on the platform you're running on, and show only those directions:

• In Claude, it goes in Settings → Profile, in the personal preferences box. To keep it to certain work, they can put it in a Project's instructions instead.
• In ChatGPT, it goes in Settings → Personalization → Custom instructions.
• In Claude Code, it goes in the repository's CLAUDE.md (shared with everyone in the repo) or ~/.claude/CLAUDE.md (just them, in every repo). Offer to add it yourself.

For other platforms, find and confirm the exact settings path rather than guessing. Respond like this:

First, every future chat, with me or any other agent, should check Herald before it starts. That takes one copy and paste. [Platform directions] Here's the text:

Then show this text exactly, in one code block so the user gets a copy button. Replace [workspace] with the workspace name, or remove that sentence if they only have one.

I use Herald for my team's shared context: what we do, who we work with, how we work and the rules we follow. Use the [workspace] workspace.

Before any task that depends on that (writing or editing something, answering a question, reviewing work or making a decision), call get_context with the task in plain words first, including who it's for, what it's for and anything specific it involves. Do this for small tasks too.

Anything under "Rules" is a hard constraint. Only use facts, quotes and numbers from the context; if something is missing, say what's missing instead of guessing. Pages marked as a private note are mine, not team-approved.

Only change the workspace when I ask. Edits are saved as drafts; tell me what you changed. Never publish unless I ask.

After the block, say: "Tell me when you've added it and we'll move on."

If you can save instructions yourself, offer to do it for them. Keep their other instructions intact. Never put personal instructions in a shared repository; a team CLAUDE.md should only get the team-wide parts. If there's a length limit, keep the first two paragraphs.

For the user's whole team, mention once that someone who can edit the whole workspace can add a line like this under Connect agents → Agent instructions, which reaches every connected agent. Don't change it yourself unless they ask.

3. Fill in the workspace

An empty workspace gives agents nothing to use. Three good pages are enough to change the answers.

Look at what get_structure showed. Find the gaps among these, in this order, and skip any that already have a published page:

1. A company overview: what they do in a paragraph a customer would recognize, who they serve, and a few hard facts.
2. A brand voice page: how they sound in a line, then sample sentences that sound like them and some that don't.
3. A page on whatever people ask their AI about most, such as a policy or a competitor.

For each gap, gather what you can see: what the user has told you, files they've shared, your own memory of them if you have one, and public pages like their website if they point you to one. Don't invent facts, and don't quiz the user to fill a page from scratch. If you can't find enough for a page, ask one short question or skip it.

Then create each page with create_page. Use ## headings, one per topic, because agents usually get the best few sections rather than whole pages; a heading like "Refunds after a downgrade" can be found on its own. See Writing pages agents can use. If the workspace already has a page for something, suggest an edit with edit_page instead of making a near-duplicate, and ask first.

• Use the workspace's existing folders and page types; get_structure shows them. An unknown page type is refused, and the error lists the valid ones.
• Lists of records with the same fields (plans, accounts, SKUs) go in a table with create_table, not a page.
• Personal material, like notes on one account or how the user likes their own emails written, goes in a private note (create_page with private: true). Only the user and their own agents see it.
• Never save passwords, keys or other secrets, or whole chat transcripts.

Everything you create is a draft. Share the first page's title as soon as it's done, then finish the rest. Tell the user in a sentence or two what you made, with one example, and offer a full list if they want it.

4. Publish

Nothing reaches an agent until it's published, including the pages you just made. Explain this in one line.

Ask the user whether they want to read the drafts in the app first (they're listed under Unpublished in the sidebar, and can all be published from there) or have you publish them now. Only call publish_page if they say so, and only for the pages they mean. If it's refused, the connection doesn't have publish access; tell them to publish from the app.

5. Try it and wrap up

Suggest one real task to try, based on what's now in the workspace, for example a short LinkedIn post or a reply to a customer. Run it, calling get_context first, and point out which pages the answer came from.

Then wrap up in a few lines: which workspace you connected, where the instructions went, what you created (with titles) and whether it's published, and anything left for the user to do. Mention that Activity in the app shows every request agents make and which pages came back, and that its Nothing found filter is a running list of what to write next.

Finally, suggest they start a new chat, or try another agent, and give it a task to see that it checks Herald first. Setup is done.