Rule format

A rule is a Markdown file that says what an output must meet. You give it a name, a description, and tags. Every upload is a new version, and a rule only reaches your agents once you set it to active.

What you provide

The same fields apply whether your agent creates the rule with create_rule or you upload it in Agent Rules in the portal.

Field	What it is
`name`	Required. Unique in your catalog, ignoring case. If it is taken you are told to pick another or to upload a new version of the existing rule.
`description`	A short sentence on what the rule is for. It appears in lists, so agents can choose the right rule without reading each one.
`tags`	For finding and grouping, such as email or brand. Tags also decide which rules you select when you build a rule set.
`content`	Required. The rule itself, as UTF-8 Markdown, within the size limit.

The upload check is limited to four things: the content is not empty, it is valid UTF-8 Markdown, it is within the size limit, and the name is free. A refusal names the field that failed. Beyond that, write the rule the way you would brief a careful reviewer: what to look for, what counts as a failure, and what counts as a pass.

An example

This is an example of the kind of rule a support team might write. It is not a required template.

Example rule content

markdown

# Promises

A reply to a customer must not promise a date or an outcome that the
support team does not control.

It fails if it:
- states a refund or delivery date as a guarantee
- says a problem will never happen again
- commits to compensation

It passes if it describes the usual timing and says who sets the final
timing.

Versions

You do not edit a rule in place. To change it, upload the whole new content. It is saved as a new version with its own version ID.
A version never changes after it is saved. Earlier versions stay readable, and results still point at the version they ran against.
A new version does not reach your agents until you set the rule to active. Agents keep getting the active version in the meantime.
If someone else saved a version after the one you started from, your upload is still saved and the result warns you and names the other version.
Rule sets that pin an older version are listed when you save a new one, so you can move them.
An earlier version cannot be made current again in this release.

Statuses

Status	What it means	Who can run it
draft	Uploaded, not ready to try. Every new rule starts here.	Nobody. A critique against a draft is refused: set it to test first.
test	Being checked by hand.	Your company, by calling it directly with its ID. It is not in the standard list.
active	Published and in use.	Your agents. It appears in the standard list.
disabled	Still viewable, but turned off.	Nobody. Set it back to active to turn it on again.
archived	Hidden as if deleted. History is kept.	Nobody. An archived rule cannot be restored in this release.

Move a rule between statuses with update_rule or in the portal. Nothing is ever hard-deleted, and a status change does not create a version.

Test a rule before you set it active

Set the rule to test.
Run validate against the rule ID on an output that should pass, then on one that should fail. Each run is a critique and uses a credit.
If the results are wrong, upload a revised version and check again.
When the rule behaves as you intend, set it to active.

Test runs are marked as tests, so reports leave them out unless you ask for them.

Finding and reusing rules

list_rules returns active rules from three places and nothing else: your own catalog, your approved list, and the public catalog. It filters by search term, tag, and source, and pages its results. A company can add its own tags to a public rule, visible only to it, so it can filter and group public rules without copying them.

See also rule sets, critique results, and the MCP tools.