Errors & limits
The known failure modes, stated up front so a connecting agent handles them by design instead of flailing. If you hit behaviour not listed here, treat the tool reference (generated from the live schema) as the source of truth.
Errors you will meet, and what they actually mean
| Symptom | Actual cause | What to do |
|---|---|---|
404 from get_system_details / get_policy_details / get_training_details | The document is a master template (isMasterTemplate: true) — its content lives in the master workspace only | Expected behaviour, not a missing document. Check isMasterTemplate on the tree/search result before fetching details. |
400 from list_documents_by_owner | The owner full name didn’t match exactly (e.g. “Kristian Basilio” vs “Kristian Philippe Basilio”) | Use the exact full name from a tree node, or the user UUID (ownerId) instead. |
502 on edit_system with a large body | Content above roughly 126KB | Split into multiple documents. Note edit_* replaces the whole content field, so “writing in sections” means resending an ever-larger body — it reaches the ceiling sooner, not later. |
| Write/move/publish/delete fails on a document that clearly exists | It’s a master template — they’re immutable | Create your own document instead; see organising guide. |
| Content you wrote looks different after a human edited the document | The editor filtered it — you authored outside the supported set | Not data loss at the API layer; re-author within the authoring contract. |
Document renders as visible tag soup (literal <h2> characters on screen) | You sent HTML-escaped content (<h2> instead of <h2>); the API stores it verbatim and returns success | Send raw HTML. Read the document back after writing to confirm rendering. |
403 “Company not found” fetching a share link externally | Known issue — the share endpoint can’t resolve the workspace from the bare URL (verified 28 Jul 2026) | Tracked with the product team; test a share link before promising it to an outside party. See Sharing & links. |
Validation limits
| Field / parameter | Limit |
|---|---|
title (documents, folders) | 255 characters, plain text |
publishTitle (version label) | 255 characters |
state | Integer 0–4 only — see Document lifecycle |
content per edit | Keep under ~126KB (see above) |
Search limit | ≤ 100 per page |
list_documents_by_owner limit | ≤ 500 per page; fetchAll: true caps at 5,000 documents |
Member/audit tools limit | ≤ 500 per page (fetchAll defaults true for complete audits) |
Behaviours that surprise agents (by design, not bugs)
- Create-with-content auto-publishes. Assigned members see the document immediately; pass
publish: falsefor a hidden draft. You do not need to ask the user to confirm publishing on create. - Every link opens in a new tab. The editor forces
target="_blank"on all links — don’t try to control link behaviour. - Visibility follows the token, not the person. Reads and writes are scoped to the identity on the workspace’s most recently generated AI Gateway token — not necessarily whoever is connected (known issue, fix in progress). “Document not found” can simply mean that identity can’t see it.
- No seat provisioning, no deletes, no workspace-wide analytics via the MCP — see Known limits and the changelog for what’s recently landed (document-level member assignment and per-document activity logs are now available).
Being a good citizen
There are no published rate limits, but the practical rules are: orient before acting (tree/search before create/edit), page with fetchAll rather than hammering per-item calls, and batch related edits rather than re-editing the same document dozens of times — each edit is a real revision in the document’s history.