Skip to content
This page is also available as markdown at /docs/set-up/set-custom-instructions.md. For the complete documentation index, see llms.txt.
Get started

Set custom instructions for the agent

Custom instructions are rules that the Falconer agent follows. Use them to keep agent writing consistent, for example “Write in US English” or “Never include API keys or passwords”.

You can set rules at four levels: the organization, a Space, a folder and a document. A document gets the rules of every level above it, so you write a rule once and it applies to all the documents below it.

LevelWhere to find itWho can change itWhat the rule covers
OrganizationSettings → Organization settings → Agent settingsOrganization ownersEverything the agent does in your organization: how it searches, what it answers and every document it writes
SpaceOpen the Space, click the more button (⋮), then Details → AgentOrganization owners who can edit the SpaceWrites to every document in the Space
FolderOpen the folder, click the more button (⋮), then Details → AgentAnyone who can edit the folderWrites to every document in the folder and its subfolders
DocumentOpen the document, click the more button (⋮), then Details → AgentAnyone who can edit the documentWrites to the document and to documents nested under it

Each level has one Custom instructions field of up to 2,000 characters. Write one rule per line. Members who cannot edit a level see its rules as read-only text.

  1. Go to Settings → Organization settings → Agent settings.
  2. Enter your rules under Custom instructions.
  3. Click Save.

To remove the rules, clear the field and click Save.

Custom instructions in the organization Agent settings

The Agent settings page also lists every Space, folder and document in your organization that has its own custom instructions, each with a link to open it and a preview of its rule text. Use this list to review all overrides across the organization from one place, instead of checking each Space, folder and document individually.

  1. Open the Space or folder.
  2. Click the more button (⋮) and select Details.
  3. Enter your rules in Custom instructions under Agent.

The rules save when you click outside the field.

Custom instructions for a folder in the Details panel
  1. Open the document.
  2. Click the more button (⋮) on the top right corner and select Details.
  3. Scroll to Agent and enter your rules in Custom instructions.

The rules save when you click outside the field.

Custom instructions for a document in the Details sidebar

When the agent writes to a document, it follows every rule that applies to that document, in this order:

  1. The organization rules
  2. The rules of each Space and folder above the document, from the top down
  3. The document’s own rules, and the rules of any document it is nested under

For example, a runbook in the Runbooks folder gets the organization rules, the Runbooks folder rules and its own rules.

  • Rules add up. A folder rule does not replace the organization rule. The agent follows both.
  • Organization rules always apply. A Space, folder or document rule cannot relax them.
  • The most specific rule wins a real conflict. A document rule wins over its folder, and a folder rule wins over the folder or Space it sits in.
  • A rule about one kind of write covers only that kind. For example, a rule for new documents does not ask the agent to change an existing document.
  • Private sections get the organization rules only. Folder and document rules apply to documents in your company navigation, not to documents that are only in a private section.

If a write cannot satisfy every rule, the agent does not write. It stops and tells you which rule blocked it.

Where the agent worksWhat it uses
Falcon in the app, in Slack and in MattermostThe organization rules for every request. The rules of a document when it creates or edits that document.
Auto-update drafts from pull requestsThe rules of each document. A proposed edit that breaks a rule is dropped.
Knowledge HealthThe rules of each document. If a fix would break a rule, Falcon leaves the finding pending and names the rule.
MCP, the public API and the CLIThe rules of each document, returned with every read and checked on every write. See Use custom instructions from MCP, the API and the CLI.

The Ask the docs assistant on a public docs site does not use custom instructions.

Custom instructions guide the agent. Review agent changes the same way you review any other change.

Use custom instructions from MCP, the API and the CLI

Section titled “Use custom instructions from MCP, the API and the CLI”

External agents, such as Claude Code or Cursor connected through MCP, get the same rules as Falcon.

  • Reads return the rules. read (MCP) and GET /docs/{id} (API) return a customInstructions object before the document content. It has a rulesHash, the precedence text and the list of rules, each with its level (org, space, folder or document), its name and its instructions.
  • Folders return the rules for new documents. get_folder (MCP) and GET /folders/{folderId} (API) list the rules a new document in that folder gets.
  • Writes send the hash. Pass the rulesHash as customInstructionsHash on every create and edit. In the CLI, use --custom-instructions-hash.
  • A write without the current hash is refused. The API returns 412 with the code custom_instructions_required and the current rules, and writes nothing. The agent checks its write against the rules and retries with the new rulesHash.
  • Documents with the same rules share one hash. Pass customInstructionsHash on a read to skip rules you already have. If the rules have not changed, the response says unchanged: true instead of repeating them.

To read or change rules, use read_settings and edit_settings (MCP) or GET and PATCH /settings/{scope} (API). The org, space, folder and document scopes each have a customInstructions key. A read returns the level’s own rule as value and every rule that applies, organization first, as effectiveValue. A change to the organization rules must be sent again with confirmed: true before it is saved.

The agent did not follow a folder or document rule

  • Make sure the document is in your company navigation. Documents that are only in a private section get the organization rules only.
  • Check the rules of every level above the document. The Details panel shows only the rule set on that level, not the rules it inherits. read_settings shows all of them as effectiveValue.
  • Check the custom instructions list under Settings → Organization settings → Agent settings, which shows every Space, folder and document with its own rules, so you can review overrides without visiting each one.

I cannot change the Space rules

Only organization owners can change a Space’s custom instructions.

**An MCP or API write fails with ****custom_instructions_required**

The rules changed since the agent last read them, or the write did not include customInstructionsHash. Read the document again, check the write against the rules and retry with the new rulesHash.

Slack Q&A channels have their own per-channel instructions, set in the Slack integration settings. They are separate from custom instructions.