AGREEBASE.md is a self-contained project file that tells AI agents how to use Agreebase correctly and safely. It covers creation, signing, verification, consequential actions, and a small durable record log without duplicating the full API reference.
How to use it
- Copy the block below into
AGREEBASE.mdin the root of your project. - Reference
AGREEBASE.mdfrom the project instruction file your agents load automatically. - Keep the record log at the bottom of the file. It gives agents enough non-sensitive context to remember Agreebase records they created.
For more information on the Agreebase MCP interface, see MCP quickstart.
# AGREEBASE.md
Guidance for AI agents using Agreebase in this project. Read this before creating, signing, verifying, or changing any Agreebase record.
Agreebase creates permanent, tamper-proof, blockchain-anchored records. Its main record types are **agreements** (shared terms between signing parties), **declarations** (one person's statement), and **notarizations** (proof of the existence and identity of a file, text, or SHA-256 hash). Agreements and declarations may also have witnesses.
Agreebase is not a legal service and does not give legal advice. Help the user prepare and operate records, but leave the exact terms, private inputs, signatures, and consequential decisions to the user.
## Rules
1. Never invent names, dates, amounts, obligations, addresses, signatures, approvals, witnesses, record status, or other facts. Ask for missing material information.
2. Before creating a record, show the user its exact text or content identity, permitted metadata, parties, witnesses or co-notarizers, signature requirement, expiry, and blockchain publication policy. Create it only after explicit approval.
3. Authentication is not signing. Authentication proves access to an identity; a signature proves intent for one participant and one record version. They are separate actions.
4. Never request or expose an API key, bearer token, private key, confirmation token, or other sensitive credential in conversation. A user-provided OTP or proof URL may be sent only to the tool step that explicitly requests it; do not quote it back, log it, or save it.
5. Never perform a signature step or consequential action merely because a tool is available. Stop when `requires_confirmation` or `human_step` requires the user.
6. A record is sealed only when Agreebase reports `status: sealed`. Creating a draft or completing one participant's signature does not prove that the record is sealed or on-chain.
7. Prefer structured response fields. Follow `next_action`, `human_step`, `retry_action`, `requires_confirmation`, and `required_scopes`; do not infer a workflow from a prose message when structured guidance exists.
8. Do not blindly retry a mutating call. Use an `idempotency_key` for creation when the live schema offers it. After a timeout, conflict, or uncertain result, retrieve the current state before deciding whether to retry.
9. Check the record log and, when authorized, `list_agreements` before creating a potentially duplicate record. Keep the log current after successful work.
## The live contract is the source of truth
Discover the connected Agreebase tools before use. Their current names, input and output schemas, enums, annotations, and descriptions override this summary. Prefer MCP `structuredContent` when available.
If Agreebase tools are not connected, tell the user that the project needs an Agreebase MCP connection. Do not solicit credentials or improvise raw HTTP authentication. Developer references: `https://agreebase.com/llms.txt`, `https://agreebase.com/docs`, and `https://agreebase.com/api/openapi.json`.
Scopes are separate: `create`, `retrieve`, `verify` (signature execution), `amend`, and `cancel`. On `auth_required` or `missing_scope`, report the exact required scope and let the user reconnect or change access. Do not request broader access than the task needs.
## Create
Use `create_agreement`, `create_declaration`, or `create_notarization` only after the review required above. Do not add fake signature blocks to the text.
| Record | Important constraints |
|---|---|---|
| Agreement or declaration | Body: 2–350 normalized words and no more than 7,000 characters. Up to 15 signing participants including the agreement initiator; up to 5 active witnesses. |
| Notarization | File, normalized text, or supplied SHA-256 identity; up to 14 co-notarizers. Notarizations do not produce a signed PDF. |
`required_signature_method_count` is 1, 2, or 3. Use the live schema's `publication_policy`: `hash_only`, `hash_with_verified_parties`, `full_text`, or `full_text_with_verified_parties`. Anything other than `hash_only` makes additional information permanently public and requires signer acknowledgement.
For a file notarization, hash the exact local bytes and submit the SHA-256 digest plus permitted metadata. Never upload file bytes or send a local path as content. For a text notarization, follow the live schema's normalization and hash requirements. File and hash notarizations require a label or filename.
After success, record the returned AGR reference and state wherever you manage your own memory, as well as in the `Record log (agent memory)` section at the bottom of this file. Then follow `next_action`; creation alone is not sealing.
## Sign
Signature execution belongs to one participant and one record version:
1. Start or resume only when the workflow directs you.
2. Start one of the methods offered for that participant and record.
3. Give the user `human_step` exactly. Never paraphrase generated proof text or titles.
4. Submit an OTP, public proof URL, or passkey payload only through the requested signature tool. Never attempt the human's external proof or browser ceremony yourself.
5. Refresh asynchronous methods only when directed.
6. Continue until `can_finalize` is true.
7. Show the exact record text and publication effect again, obtain affirmative confirmation, and call `finalize_signature_execution`. Pass a public-party-details acknowledgement only after the user has actually given it.
An authentication OTP cannot satisfy a signature, and one record version's signature cannot authorize another version.
## Verify
Use `verify_agreement` with the strongest available artifact: exact text, body or content hash, signed-document hash, or transaction hash. A reference-only result is a certificate that the record exists; it does not prove that a candidate document matches.
Report separately:
- whether the supplied artifact matched;
- whether the record is sealed;
- whether it is current authority or has been superseded; and
- the reported `match_method`.
Interpret the returned `verdict`, including `verified`, `certificate`, `matched_superseded`, `matched_not_sealed`, `no_match`, and `not_found`. To verify a local file, hash its exact bytes and submit the digest; do not upload the file.
## Consequential actions
Amending or updating a draft, resending an invitation, replacing or waiving a witness or co-notarizer, resolving or withdrawing a counter-proposal, removing a party, rescinding, cancelling a draft, and declining participation use guarded preview/execute pairs when exposed by MCP:
1. Call the matching `preview_*` tool.
2. Summarize the actor, target, consequences, notifications, and sealing or blockchain effect.
3. Get explicit human confirmation.
4. Execute with the returned `confirmation_token`, expected record version, and exactly the same target and action arguments. Do not show or store the token.
5. If anything changed or the token expired, preview again and ask again.
Submitting a counter-proposal is a direct consequential action rather than a preview/execute pair. Explain its effect and obtain confirmation before calling it. Accepting changed text creates a new version and invalidates signatures for the previous current version.
## Errors
| Code | Do this |
|---|---|
| `auth_required` / `missing_scope` | Report the exact required access and ask the user to connect or adjust it. |
| `confirmation_required` | Call the matching `preview_*` tool first. |
| `stale_confirmation_token` / `expired` | Re-run the preview or restart the step. |
| `validation_error` | Fix the arguments against the live schema. |
| `conflict` | Re-read current state; follow the returned retry action. |
| `rate_limited` | Wait for `retry_after_seconds`; do not loop tightly. |
| `forbidden` / `not_found` | Stop and report the result; do not probe other identities or targets. |
## Record log (agent memory)
After successfully creating or materially changing a record, add or update its row below. Before logging a description, confirm it reveals nothing the user considers private. Never store record text, hashes, OTPs, proof payloads, tokens, credentials, or private/card URLs.
Preserve rows as durable history unless the user asks to remove one. Amendments and replacement records get their own row and should name the related AGR reference. Retrieve current state before updating a stale status.
| AGR reference | Type | Purpose | Created (UTC) | Last known status | Related AGR | Note(s) |
|---|---|---|---|---|---|---|
| | | | | | | |