MCP connector reference
Audience: Traceable users (document authors, project contributors, reviewers,
and the org admins who grant access). No coding knowledge is assumed.
Applies to: the Traceable MCP server traceable v6.0.0, 43 tools.
Last updated: 2026-11-02
1. What this is
The Traceable MCP connector lets an AI assistant (Claude on claude.ai, Claude Desktop, or Claude Code) work inside your Traceable account the same way you do: it can browse your projects, read documents, write and edit content, build ID grids, create trace links, and pull material out of your Reference Library.
Two things are worth understanding before you connect:
- The assistant acts as you. It signs in with your account through a consent screen, and it can reach exactly what you can reach, no more. If you are not a member of a project, neither is the assistant. If your role is read-only, the assistant is read-only too.
- It only touches drafts, and every change is attributable. Publishing, review, and e-signature stay human actions in the app. Every edit the assistant makes is written to the audit log against your name, and (unless an admin turns the setting off) each edited row waits for you in the document's Agent panel for you to read and accept.
Think of it as a very fast co-author who can draft, restructure, and cross-link, while you keep the pen for anything that makes a document official.
2. Before you start
You need three things:
| Requirement | How to get it |
|---|---|
| A Traceable account | Sign in at https://app.traceabledocs.com |
| Your organisation allows external agents | On by default. An org admin can turn it off for everyone (see below). |
| MCP access enabled on your user | Off by default. An org admin turns on Enable MCP access for you. |
| An MCP client | claude.ai, Claude Code, or another client that takes a server URL (section 3) |
Two switches, and both must be on
Access is governed at two levels, and a refusal at either one stops the connection:
- The organisation must permit external agents at all. This is on by default, so nothing changed for organisations that already had the connector working.
- You must be granted access individually. This is off by default.
If you belong to more than one organisation, every one of them must permit external agents. The connection is granted to you, not to one organisation, so a connected assistant reaches everything you can reach across all of them. An organisation that switches external agents off is saying that no outside agent touches its data, and that is only true if the switch also covers members who happen to belong to a second, more permissive organisation. The cost is real: one organisation can cut you off from the others.
Turning it on (org admins)
Per person. Go to Org settings → Members, open the member, and in the AI / integrations access box switch Enable MCP access on.
For the whole organisation. Go to Org settings → AI agents and switch Allow external AI agents to connect (MCP) on.
Either switch is an immediate cut-off when turned off: the member's connector stops working straight away, even mid-session, without waiting for anything to expire.
Both control whether a person may connect. Neither changes what they can see: project and organisation membership decides that, exactly as in the web app.
3. Connecting
The server address is:
https://app.traceabledocs.com/api/mcp/mcp
On claude.ai (web, desktop, mobile)
- Open Settings → Connectors.
- Choose Add custom connector.
- Paste the address above and save.
- Claude sends you to Traceable's sign-in and then to a consent screen headed "Authorize … wants to connect to your Traceable account".
- Check the permissions listed, then approve.
In Claude Code
claude mcp add --transport http traceable https://app.traceabledocs.com/api/mcp/mcp
Then start Claude Code and follow the browser sign-in and consent prompt the first time a Traceable tool is used.
In other clients
The connector is an ordinary remote MCP server: streamable HTTP, with OAuth sign-in handled by the client. Any client that accepts a custom server URL can use it, and the sign-in and consent steps are the same ones described above.
ChatGPT and Cursor have been connected and used end to end (verified 3 October 2026), and Google Antigravity on 20 October 2026. VS Code is expected to work because it speaks the same protocol, but we have not yet run it end to end. If you connect one of those successfully, or hit a problem with any client, tell us through the in-app Support menu (section 12) so this list stays accurate.
| Client | Where to put the URL | Status |
|---|---|---|
| ChatGPT | Developer mode, as a custom connector | Verified |
| Cursor | MCP settings, as an HTTP server, or one click: Add Traceable to Cursor | Verified |
| VS Code | MCP settings, as an HTTP server | Not yet verified |
| Google Antigravity | Agent panel ⋯ > MCP Servers > Manage MCP Servers > View raw config, add "traceable": { "serverUrl": "https://app.traceabledocs.com/api/mcp/mcp" } under mcpServers, save and Refresh. It registers itself and signs in through your browser, so it needs no client ID or secret. Its changes are attributed to "MCP CLI Proxy", the name its connection bridge registers with. |
Verified |
| Gemini CLI | gemini extensions install https://github.com/Traceable-Org/traceable-gemini-extension. Google no longer serves Gemini CLI to personal accounts, so this is for Workspace (Gemini Code Assist Standard or Enterprise) and paid API-key users; everyone else uses Antigravity. |
Not yet verified |
Assistants that need a client ID and secret (Microsoft 365 Copilot)
Claude, ChatGPT and most other clients register themselves when they first connect, so there is nothing to set up. Some do not: Microsoft 365 Copilot (a declarative agent with an MCP plugin, built in Microsoft 365 Agents Toolkit), Microsoft's agent connectors and Copilot Studio all ask for a client ID and secret first. For those, an org admin registers an application in Traceable. It is included on the Team plan and above.
- In the assistant, start setting up OAuth and note the redirect URI (sometimes called the callback URL) it shows you.
- In Traceable, go to Org settings → AI agents → Registered applications. Give the application a name, paste the redirect URI, and choose Register.
- Copy the client ID and secret straight away. The secret is shown once and never again, because Traceable keeps only a scrambled copy of it. If it is lost, choose Replace secret and update the assistant.
- Back in the assistant, choose OAuth with a client ID and secret (often called static or manual registration) and enter:
| Field | Value |
|---|---|
| Client ID | from step 3 |
| Client secret | from step 3 |
| Authorization URL | https://app.traceabledocs.com/oauth/authorize |
| Token URL | https://app.traceabledocs.com/oauth/token |
| Refresh URL | https://app.traceabledocs.com/oauth/token |
| Scope | documents:read documents:write |
| PKCE | On (S256). Traceable requires it. |
Each member then signs in and approves the consent screen as themselves, exactly as on claude.ai, and still needs MCP access granted (section 2). Only members of the organisation that registered the application can connect through it. Disable stops it at once for everyone; Enable turns it back on.
Clients that only speak stdio or SSE. Some older clients cannot talk to an
HTTP server directly. Put mcp-remote in front:
npx mcp-remote https://app.traceabledocs.com/api/mcp/mcp
There is no SSE endpoint to connect to instead: the connector serves the streamable HTTP transport only.
What you are agreeing to on the consent screen
| Permission shown | What it allows |
|---|---|
| Read your projects and documents | Browsing projects, document maps, link maps, templates, document content, and the Reference Library |
| Create and edit document content | Creating and editing draft documents, rows, ID grids, trace links, and references |
Approving grants both by default. Access is time-limited behind the scenes: the short-lived key the assistant holds lasts up to an hour and is renewed silently for up to 30 days of continued use, after which you sign in again.
Who is asking
Below the permissions, an About this application box shows what Traceable actually knows about the client:
| Field | What it means |
|---|---|
| Website | The address the application gave for itself, shown as plain text |
| Sends you back to | The address you will be returned to after approving |
"Sends you back to" is the one field worth reading closely. It is the only line on the screen that Traceable verified rather than took the application's word for: it has to match, exactly, what the application registered in advance, so it is the one thing a bad actor cannot change after the fact. If it is not a host you expect, do not approve.
For an application your org admin registered (section 3, Assistants that need a client ID and secret), the box says "Registered by <organisation> administrators" instead. Otherwise you will see the line "This application registered itself. Traceable has not verified it." That is literally true, and it is why no logo is shown. Any application may register itself and call itself anything, including "Traceable Official". Rendering its logo would make a claim it made about itself look like one we checked, on the exact screen where you are deciding whether to trust it. So you get hostnames as text, and links to the application's own privacy policy and terms if it supplied them, and nothing dressed up as an endorsement.
If you are told you do not have access
Signing in with an account that has not been granted MCP access does not leave you stuck. You get a page that names your organisation and explains which of the two switches in section 2 is closed:
- Your account is not permitted yet. This is the common case, and the page offers an Ask an administrator for access button that emails your organisation's admins. They decide. You can connect once one of them grants it.
- Your organisation has turned external agents off. An admin has to change that under Org settings → AI agents. There is no button here, because no email to an admin would let them clear it for you alone.
In every case nothing has been shared with the application at the point you are refused.
4. What the assistant can see
Access mirrors your own, through the same checks as the web app:
- Projects: only projects you are a member of, and only active ones.
- Organisations: only organisations you belong to.
- Documents: every document in those projects, subject to your project role.
- Role limits: an auditor sees published documents only, so an assistant acting for an auditor cannot read a draft. Reviewers can read drafts but cannot write. Contributors and admins can read and write.
- Reference Library: organisation-scoped items, plus items in projects you belong to.
Same rule for writing: if your role cannot edit a document in the app, the assistant cannot edit it either, and the tool returns an access error.
5. What the assistant can do
You do not type tool names. You ask in plain language and the assistant picks the tools. The groups below tell you what is in reach, so you know what to ask for.
Workspace
- List your organisations and projects, with your role in each.
- Produce a document map of a project: groups, documents, document numbers, ID prefixes, types, statuses, versions, item counts, and heading outlines.
- Produce a link map: which documents trace to which, with link counts, including one-to-many relationships and links out to external documents.
- List the templates available to you (system templates plus your organisation's).
- Read a project's board: the Design Phases board of a product or process project, or the quality system diagram of a Quality project, with every cell and the documents and placeholders in it.
- Read a document as an outline (cheap) or in full, or just a slice of it.
"Map the infusion pump project and tell me which documents have no incoming trace links."
Documents and content
- Create a document in a project, optionally from a template, with a name, document number, TraceID prefix, type, and group, and put it in a cell of the project's board.
- Move a document to another cell of the board, or take it off the board.
- Plan a document not yet written as a placeholder card in a cell, change or move it, remove it, and later write the document it planned, which then takes the placeholder's card. These board tools are a controlled release (Agents can plan and place documents on the board): an organisation under controlled releases turns it on in Org settings > Releases.
- Replace a whole segment (header, body, footer, or the title page equivalents).
- Insert one or more blocks at a chosen point: after a given TraceID, after a given row, or at the start or end of the body.
- Replace a single block, identified by its TraceID or its row position.
- Delete a block. Deletes are soft, so a mistake is recoverable in the app, and deleting a table or grid header removes its children with it.
- Update document metadata: name, number, type, group, and heading auto-numbering.
Content the assistant can author includes headings and paragraphs, traceable
rows, tables, multi-column bands, ID grids, table of contents, revision tables,
signature tables and signature rows, publish logs, document lists, traceability
matrices, Test Plans, diagrams, page and section breaks (including paper size
and orientation), and property tokens such as {{docTitle}}.
The assistant can also name figures and tables, cite references and point at other parts of the document:
- Captions. Numbering is automatic, so the assistant sets only the name after
"Figure N" or "Table N":
caption="..."(andhideCaption=true) in an image's{...}options, in a[[table caption="..."]]line before a table, or on an ID grid's[[id-header]]. Reads show the captions too, so rewriting a section the assistant has read keeps them. - Crops.
crop=x,y,w,hin an image's{...}options shows only that region, given as percentages of the whole picture, exactly as a crop made in the editor: the stored file is not changed, and a reviewer can undo the crop to see what was left out. The assistant can look at the image first with traceable_image_view. - Citations.
[label](cite:REF-00000I)cites one of the document's references and shows as the same live "[n]" chip the editor inserts. The reference must be added first. - Cross-references.
[label](ref:UN-7)points at a heading, a table ("Table 2") or a live ID row of the same document, as the editor's cross-reference chip.
A citation or cross-reference that does not match anything in the document is written as plain text, and the assistant is told so. HTML typed into content is kept as text, never as markup.
A document holds at most one Test Plan, one Test Report and one Test Summary, and each is the document's own. The assistant places them and names what each draws from, by document number:
[[test-plan protocols="D0074,D0080"]]: the Test Plan draws one entry from each protocol ID row of those documents.[[test-report from="D0081"]]: the Test Report tests the protocols that the Test Plan in D0081 includes. With no plan,[[test-report protocols="D0074"]]tests every protocol in the documents named.[[test-summary from="D0082"]]: the Test Summary closes out each test the Test Report in D0082 records.
In a document that holds its own Test Plan, a bare [[test-report]] tests that
plan, and likewise a bare [[test-summary]] closes out the document's own Test
Report. The same rules apply as in the editor: the documents named are added to
the document's references, and a Test Report is locked to the published version
of each source. A source can still be a draft, but the report then warns that
it should be published before results are recorded. A bare directive keeps the
row's existing source, and a read returns protocols= and from=, so writing a
read segment back keeps every source. A second row of the same kind in a
document is refused.
Add columns= to choose what a row shows: a stage (plan, test,
baseline), individual columns, or both, for example
[[test-report from="D0081" columns="links,test"]]. Protocol is always shown.
The assistant can also record the test itself. It reads a record's entries, then fills in the columns that record holds: the decision and rationale in a Test Plan; the results, notes, samples, location, equipment and Pass/Fail in a Test Report, per test step where the protocol has steps; the assessment, baseline notes and resolution in a Test Summary. It can attach evidence, either from the document's references or by uploading a file: an image shows inline in the Evidence column, and any other file is filed in the project's Reference Library and attached as a chip. One thing stays with a person: the tester's electronic signature, which the assistant cannot apply. Every change the assistant makes to a test record goes to review like any other agent change.
"Create an OQ report from our report template, with a Test Report in its Executed Results section testing the OQ Test Plan in D0081."
"Draft a 12-requirement Functional Requirements document from the user needs in PRJ-002, using our FRS template, prefix FR."
Traceability
An ID grid is the mechanism traceability is made of: its rows carry the TraceIDs and its link columns carry the links. So the grid tools and the link tools belong together, and the assistant reaches for them as one set.
Grids matter because they are the part of a document most easily damaged by a wholesale rewrite. These edit in place and keep every row's identity and trace links intact:
- Add a column (id, text, link, calculation, dropdown, test result, or checkbox).
- Rename a column header.
- Change a column's type, including dropdown options and calculation sources.
- Set a single cell's value.
Summary columns are the one exception: they are built in the app only. Link cells are also not set directly, you ask for a trace link instead and the chip is placed for you.
"Add a 'Verification method' dropdown column to the grid in DRS with options Test, Inspection, Analysis, Demonstration."
And the links themselves:
- Create a trace link between two TraceIDs in a project. It is idempotent, so asking twice does not create a duplicate. When the source is an ID row, the link chip is also placed in a link column so it is visible on the page. If the row has no link column, the link is still created and the assistant tells you why nothing is showing.
- Delete a trace link, named by the two TraceIDs it runs between. The direction matters: asking to delete FR-1 to UN-2 will not delete a link that runs UN-2 to FR-1, it tells you the link runs the other way.
- Rename a TraceID in place without breaking anything: links into and out of the row survive, the grid's id cell stays in sync, and cached labels elsewhere in the project are refreshed.
- Rename a document's whole TraceID prefix, re-deriving every row's visible id while preserving links. You do not need to rebuild a document to re-prefix it.
"Renumber the ID grid in PRJ-004 so the ids run DR-1 to DR-40 with no gaps."
Library
- List the items you can access, with REF code, kind, file type, scope, and whether the text has been indexed.
- Keyword search across indexed item text, returning a snippet per hit.
- Read an item's extracted plain text.
- Index an item so its text becomes searchable and cheap to read.
- Attach a library item, or another document, as a reference on a document, creating the Reference Table row if one is not there yet.
- Upload a file (a standard, a manual, a report, up to 3 MB) to the project's Reference Library and add it to the document's references in the same step. Its text is indexed straight away where the file type has text to extract. In an organisation under controlled releases this works once an organisation admin turns on Agents can upload reference files in Org settings > Releases.
Search is plain keyword matching over text extracted on Traceable's own servers. There is no embedding service and no third-party call, so nothing leaves the system to make search work.
"Search the library for 'IEC 62304 software safety classification' and cite the best match on PRJ-003."
Skills
- List your organisation's skills: the Skill rows written in Traceable documents, with each one's name, when to use it, tags and document type, and the document and version it comes from.
- Read a skill as a
SKILL.mdfile, the open Agent Skills format, so the assistant can follow it.
The assistant is served each skill as it stands in its document's latest published version. A change to a skill reaches the assistant once its document is reviewed and published again. A draft skill is served only when the assistant asks for one, marked as a draft, and never to an auditor. To change a skill, the assistant edits its Skill row in the document, like any other row. In an organisation under controlled releases this works once an organisation admin turns on Agents read skills in Org settings > Releases.
Each published skill is also offered as a prompt, which assistants such as
Claude show as a slash command (for example /write-a-risk-assessment). Picking
one puts that exact published version of the skill into the conversation, so you
choose the method rather than leaving it to the assistant. The list is yours: the
published skills in the projects you belong to, refreshed each time the assistant
connects. Draft skills are never offered as prompts. Two skills with the same
name each carry their document number. Assistants that do not show prompts still
reach every skill through the tools above.
"Load our skills, then draft the risk assessment for PRJ-003 the way our published skill says."
Messages
- List your document Discussions and your direct and group conversations, with how many messages you have not read in each.
- Read a Discussion or a conversation: every message and reply, who wrote it, the tasks assigned from it, and who can be mentioned there.
- Post a message or a reply as you. It is marked via the assistant's name, so everyone in the thread can see an assistant wrote it, and people are told about it as for any message you post.
The assistant reaches the same threads you can in the Chat panel, including your direct and group messages, and can post only where you could. Its reading leaves the messages unread for you, so your Inbox still shows what you have not seen yourself. It cannot edit, remove or react to a message, or assign one as a task. An organisation admin can turn this off for the whole organisation under Org settings > AI agents > Discussions and messages. In an organisation under controlled releases it works once an organisation admin turns on Agents read and post in threads in Org settings > Releases.
"Summarise what has been said in the Discussion on PRJ-003-SRS since Monday, and reply to Ann's question about the release date."
6. What the assistant cannot do
Deliberate limits, not gaps to work around:
| Not available | Why, and what to do instead |
|---|---|
| Publishing a document | Publishing creates the controlled version. It stays a human action in the app. |
| Reviews, approvals, e-signature | Same reason. Sign in the app. |
| Editing a published document silently | A write to a published document opens a new draft first (see section 7). The published version is untouched in history. |
| Creating projects, organisations, or users | Account and project administration is app-only. |
| Deleting a live document | Only an archived document can be deleted, and that deletion is permanent. Archive it in the app first. |
| Uploading attachments into document content, or images from another website | The assistant can upload an image (PNG, JPEG, GIF, WebP or AVIF, up to 3 MB) and place it in a text row, a table cell or a text cell of an ID row, see traceable_image_upload. It cannot place an image from another website: upload it instead. Test Plan evidence can be any file, up to 3 MB, and so can a file uploaded to the Reference Library, see traceable_library_upload. |
| Signing a Test Report entry as the tester | The tester's signature is an electronic signature (21 CFR Part 11). The assistant records results; the tester signs in the app. |
| Cross-references to figures | Figures are not cross-reference targets in the editor either. Headings, tables and ID rows are. |
| Hand-authoring a Reference Table | Ask for a reference to be added and the table row is provisioned automatically. |
| Reading PDFs, PowerPoint, or images in the library | Text extraction covers Word, spreadsheets, CSV, text and markup formats, and web pages. Other types report back as unsupported rather than guessing. |
| Merged cells in a band converted to a table | Reading is lossy and a wholesale rewrite flattens the merges. Edit those bands in the app. |
7. What happens to your documents when the assistant edits them
Drafts, always. If a document is published, the first write reopens it as a new draft (for example v1.0 becomes v1.1) and the published version stays intact in history. If it is already a draft, a burst of edits opens one new draft increment, so an assistant's editing pass gets its own line on the Versions timeline, just like one of your own editing sessions.
Rows wait for your acceptance. Each project has a Require AI change review setting (Org settings → Projects, admin only), on by default. On the Regulated plan an org admin can also require it in every project (Org settings → AI agents), and then no project can switch it off. While it is on, every row an assistant writes is flagged and appears on the Agent changes tab of the document's Review panel under Pending, with the row preview and its TraceID. Contributors and admins get an Acknowledge button, and acknowledged changes move to the Acknowledged list. The tab is empty when there is nothing waiting.
Deletes are recoverable. Block deletions are soft, matching what deleting a row in the editor does. Links pointing at a deleted row are marked broken rather than vanishing, so nothing disappears quietly.
Two editors at once are caught, not merged. Every read gives the assistant the document's current revision, and it passes that revision back when it writes. If anyone has changed the document in between (you in the app, a colleague, or another assistant session), the write is refused and nothing is changed. The assistant re-reads the document, tells you what changed, and only then carries on. Every tool that changes a document, including links, grid columns, TraceID renames and prefix renames, takes part in this check and hands back the current revision. The revision follows the document's content, so renaming the document, adding a reference or recording a Test Plan result leaves it unchanged: none of those can overwrite anyone's rows. Without this, a second session could quietly overwrite rows the first one had just written.
Everything is logged. Each change writes an append-only audit log entry attributed to you as the acting user, so agent-assisted authoring keeps the same provenance trail as manual authoring.
8. Getting good results
Name things precisely. Document numbers (PRJ-003), TraceIDs (FR-012), and REF codes (REF-00001A) remove all guesswork. If two projects share a name across different organisations, name the organisation too.
Ask for a map before a rewrite. "Map the project, then propose what to change" costs little and prevents the assistant from working with a stale picture.
Prefer targeted edits to wholesale rewrites. Replacing a whole segment soft-deletes the rows in it and marks links to them broken. Asking to "update FR-012" or "add a column to that grid" preserves row identity and links. If you want a rewrite, say so explicitly, and expect to re-link.
Work in batches you can review. A dozen rows you read and accept beats two hundred you skim.
Expect long jobs to pause. Your AI client limits how many tool calls the assistant can make in one reply, and Traceable cannot see or change that limit. On a long job the assistant works in steps and, before it stops, says what is done and what is next. Reply "continue" and it picks up from there, re-reading the document first. Run one assistant session per document at a time: two sessions working the same document will keep refusing each other's writes.
Some prompts that work well:
- "Read PRJ-002 and list every user need that has no downstream requirement."
- "Create a Design Requirements document from the FRS, one DR per FR, prefix DR, and trace each DR back to its FR."
- "In PRJ-004, set the Verification column to 'Test' for every row whose text mentions measurement."
- "Check the link map for orphaned documents and summarise the gaps."
- "Add REF-00012B as a reference on PRJ-003 and cite it in the introduction."
A note on row numbers. Inserting a row renumbers the rows after it. The assistant handles this by re-reading or by anchoring to TraceIDs, but if you see it editing what looks like the wrong row, ask it to re-read the document first.
9. Managing and revoking access
Your own connections
Go to Account → Security → Connected apps. Each app you have authorised is listed and can be revoked. Revoking stops that app obtaining new access; access it already holds stops working within the hour.
As an org admin
- Org settings → Members → (member) → Active connections: revoke a specific connection for that member.
- Enable MCP access off: the immediate, total cut-off for that user, across every client they have connected.
- Org settings → AI agents → Registered applications: replace an application's secret (the old one stops working at once), or disable it for every member.
What is recorded
Connector access leaves its own trail, separate from the document audit log. Authorising an application, declining one, being refused access, requesting access and revoking a connection are each recorded with a timestamp. So the question an auditor asks, which is who allowed an outside system to reach controlled content and when, is answerable from the record rather than from memory.
Document edits an assistant makes are recorded where all edits are: in the document's audit trail, against your name.
Good practice
- Revoke connections you no longer use.
- Review a departing member's connections as part of offboarding.
- Leave Require AI change review on for regulated projects.
10. Troubleshooting
| Symptom | Cause and fix |
|---|---|
| Sign-in loop, or the connector reports it is unauthorised | MCP access is not enabled for your user. Ask an org admin to turn on Enable MCP access. |
| The connector was working and suddenly stopped | Connections can drop briefly while Traceable is being updated. Reconnect, or ask the assistant to retry, and it re-authorises. |
| "This action requires the documents:write scope" | The connection was authorised for reading only. Remove it in Account → Security → Connected apps and reconnect, approving both permissions. |
| "Document not found or access denied" | You are not a member of that project, or your role cannot edit. Check your role, or ask to be added. |
| "This document has no published version available to your role" | You are an auditor on that project and the document has no published version. Auditors read published documents only. |
| A grid change is refused, or the document will not accept edits | The target may be a template, or the write may be blocked by role. Templates can be read and cloned, not edited through the connector. |
| Edits do not appear on the page | Check the Agent panel: the rows are probably pending your acceptance. |
| A trace link was created but no chip is visible | The source row has no link column. Add one, then ask for the link again. |
| "This document has changed since the revision you read" | Someone edited the document after the assistant read it, so the write was refused and nothing changed. Ask the assistant to re-read and carry on. If it keeps happening, another assistant session is probably working on the same document. |
| The assistant stops part-way and says what is next | It reached your client's limit on tool calls in one reply. Reply "continue". |
| "The Free plan allows a limited number of agent requests an hour" | The hourly allowance is used up. Wait the number of minutes shown, or upgrade. |
| A diagram the assistant wrote shows as "not yet rendered" | Diagrams are drawn by the app the first time the document is opened in it. Open the document, and the picture appears. If the source is broken, the app says so, and the assistant's next read reports the diagram as failed with the message. |
| A library search finds nothing | The item may not be indexed, or its type may be unsupported (PDF, PowerPoint, images). Ask for it to be indexed first. |
| Content the assistant wrote to the title page does not show | The document's title page is switched off. Turn it on in the app and the content renders. |
11. Every tool, in full
You never call these by name. The assistant chooses them, and this section exists so you can check what it is able to do and on what terms. Every tool below is listed with the permission it needs and every parameter it accepts, taken from the implementation rather than from a summary, so it does not drift from what the server actually exposes.
A parameter marked required must be supplied for the call to run at all. One marked optional has a default the description names. Where a parameter takes a fixed set of values they are listed; anything else is rejected before the tool runs.
There are 43 tools: 15 need read access and 28 need write access.
Each tool below also says whether it changes anything, whether asking for it twice does the job twice, and whether it reaches outside Traceable. Your assistant is told the same three things, and uses them to decide what to confirm with you. Claude, for example, lets you approve all the read-access tools in one go, because they change nothing, and asks every single time for the others.
Workspace
Find your way around: what exists, and where.
traceable_workspace_projects
Read access. Changes nothing, safe to ask for twice.
Your workspace: every organisation you belong to (id, name, org number, your role), each with the active projects in it you are a member of (id, name, project number, your role, document count, last-updated time). Start here, a projectId from this listing is the input to traceable_workspace_map. Organisations you belong to but have no project in are listed with an empty projects array: their organisationId is what traceable_library_search and traceable_workspace_templates take. Projects with no organisation come back under projectsWithoutOrganisation. Pass organisationId to narrow to one organisation, which is how you disambiguate same-named projects across organisations.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
organisationId |
UUID | no | Only list this organisation and its projects |
traceable_workspace_templates
Read access. Changes nothing, safe to ask for twice.
List the document templates available to you (system templates plus your organisations'): id, name, TraceID prefix, document type, band previews, body outline, and the owning organisation (organisationId + organisationName; null for a system template). Pass a template's id as templateId to traceable_doc_create to clone its styled header/footer bands and body scaffold.
Takes no parameters.
traceable_workspace_map
Read access. Changes nothing, safe to ask for twice.
Survey a project before opening any document. include=structure (default) returns the group/document/outline tree: each document's number, ID prefix, type, status, version, item counts and H1-H6 headings, use it to decide what to read. include=links returns the document-to-document trace graph instead: which documents link to which, how many trace links each edge carries and how many distinct source rows they leave from, including one-to-many relationships and links to external documents. include=both returns the two together. Returns Markdown by default (token- efficient, readable); pass format=json for the structured object.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
projectId |
UUID | yes | The project UUID (from traceable_workspace_projects) |
include |
structure | links | both |
no | structure (default): the document tree. links: the trace graph between documents. both. |
format |
markdown | json |
no | markdown (default) or json |
traceable_board_read
Read access. Changes nothing, safe to ask for twice.
Read a project's board: the Design Phases board of a product or process project, or the quality system diagram of a Quality project. Returns every cell with its phaseId and workstreamId (the cell's address), a label naming where it sits ("Phase × Workstream" on the Design Phases board, "Workstream › Phase › Cell" on the diagram), the cards in it in order (documents and placeholders, each with its cardId), and the documents on no cell. Pass a cell's phaseId and workstreamId as placement to traceable_doc_create or traceable_doc_update_meta to put a document in it, or to traceable_board_placeholder_create to plan a document not yet written there. A controlled release (Agents can plan and place documents on the board).
| Parameter | Type | Required | Meaning |
|---|---|---|---|
projectId |
UUID | yes | The project UUID (from traceable_workspace_projects) |
Documents
The document as a whole: read it, make one, change its metadata, remove it.
traceable_doc_read
Read access. Changes nothing, safe to ask for twice.
Read a document or a template. mode=outline returns metadata + heading outline + item counts (cheap; default when exploring). mode=full returns the content as Traceable Markdown (TrMD): segments as [[segment …]], each block prefixed with its [[row N]] anchor annotation, including ID- grid structure ([[id-header types=…]]). Bound a full read with fromOrder/toOrder (row orders from the outline or a prior read) to load only a section. Accepts a template id (from traceable_workspace_templates) so you can inspect a template body and its column structure before cloning it with traceable_doc_create.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | A document or template UUID (from traceable_workspace_map / traceable_workspace_templates) |
mode |
outline | full |
no | outline (default) or full |
fromOrder |
number |
no | First row order to include (full mode) |
toOrder |
number |
no | Last row order to include (full mode) |
traceable_doc_create
Write access. Only adds things, asking twice does it twice.
Create a document in a project. templateId clones an org/system template (header/footer bands, revision + signature scaffolding come along, discover templates with traceable_workspace_templates); trmContent then authors the body. Without a template, default header/footer bands are seeded for any segment trmContent does not provide. To put the new document on its project's board, pass placement with a cell's phaseId and workstreamId from traceable_board_read; a placement that is refused is reported as a warning and the document is still created. To write the document a placeholder planned, pass placeholderId instead: the document takes the placeholder's card, in its cell and position. Returns the new documentId and the created rows with their row orders.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
projectId |
UUID | yes | The project UUID (from traceable_workspace_projects) |
name |
string |
yes | Document name |
documentNumber |
string |
no | Document number (e.g. PRJ-003) |
idPrefix |
string |
no | TraceID prefix (uppercase letters/digits/hyphens, e.g. FR) |
documentType |
string |
no | Document type from the organisation taxonomy |
groupId |
UUID | no | Document group UUID (from traceable_workspace_map) |
templateId |
UUID | no | Template document UUID to clone |
trmContent |
string |
no | Initial TrMD content (body only when templateId is set) |
placement |
object | no | A board cell: phaseId and workstreamId (from traceable_board_read), and optionally position (0 is the top of the cell; defaults to the end) |
placeholderId |
UUID | no | A placeholder card (its cardId from traceable_board_read) this document is written for; it takes the card. Not with placement |
traceable_doc_update_meta
Write access. Overwrites or removes things, safe to ask for twice.
Update a document's metadata: name, document number, document type, group, the numberedHeadings toggle, and its placement on the project's board. Placement changes no document content and opens no new draft. Turn numberedHeadings on so the app auto-numbers headings, then author heading text WITHOUT section numbers (see the headingNumbering note in traceable_capabilities). Only the fields you pass are changed. To change the TraceID prefix use traceable_doc_rename_prefix (it re-derives existing ids); it is not settable here.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document UUID |
name |
string |
no | New document name |
documentNumber |
string | null |
no | New document number, or null to clear |
documentType |
string | null |
no | New document type, or null to clear |
groupId |
UUID | null |
no | Move to this group UUID, or null to ungroup |
numberedHeadings |
boolean |
no | Turn heading auto-numbering on or off |
placement |
object | null |
no | Move to this board cell (phaseId, workstreamId, optional position, from traceable_board_read), or null to take it off the board |
traceable_board_placeholder_create
Write access. Only adds things, asking twice does it twice.
Plan a document not yet written as a placeholder card in a cell of a project's board (a Design Phases cell, or a cell of the quality system diagram). To write the planned document, pass the placeholder's cardId as placeholderId to traceable_doc_create. A controlled release (Agents can plan and place documents on the board).
| Parameter | Type | Required | Meaning |
|---|---|---|---|
projectId |
UUID | yes | The project UUID |
title |
string |
yes | The planned document's title |
placement |
object | yes | The cell to put it in (phaseId, workstreamId, optional position, from traceable_board_read) |
documentType |
string | null |
no | The planned document's type |
traceable_board_placeholder_update
Write access. Overwrites or removes things, safe to ask for twice.
Change a placeholder card's title or document type, or move it to another cell. A card that holds a document is not a placeholder: move it with the document's placement instead.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
cardId |
UUID | yes | The placeholder's cardId (from traceable_board_read) |
title |
string |
no | The planned document's new title |
documentType |
string | null |
no | The planned document's type, or null to clear |
placement |
object | no | A cell to move it to |
traceable_board_placeholder_delete
Write access. Overwrites or removes things, safe to ask for twice.
Remove a placeholder card from the board. It removes only the plan: no document is deleted.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
cardId |
UUID | yes | The placeholder's cardId (from traceable_board_read) |
traceable_doc_rename_prefix
Write access. Overwrites or removes things, safe to ask for twice.
Rename a document's TraceID prefix in place, re-deriving every existing row's visible id (traceable rows, native-table trace cells, and ID-grid id cells). Trace links are preserved, only the human-readable ids change, so you do NOT need to recreate the document to re-prefix it. The document must be an editable draft (published documents are read-only).
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document UUID |
newPrefix |
string |
yes | New prefix: 1–12 uppercase letters, digits, or hyphens (e.g. IQ-R) |
traceable_doc_archive
Write access. Only adds things, safe to ask for twice.
Archive a document: move it to the project's Archive group, as the app's Archive action does. Its trace links are marked broken so the trace views show the gap, and restoring it in the app heals them. A document under review is refused (finish or withdraw the review first). Archiving an archived document changes nothing. Agents cannot delete documents: a person deletes an archived document in the app, and restores one there too. Use it to retire a superseded document after replacing it.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document UUID to archive |
Content
Authoring inside a document: segments and blocks.
traceable_segment_write
Write access. Overwrites or removes things, safe to ask for twice.
Replace a whole segment with the given TrMD, the primary bulk-authoring tool. Existing rows in the segment are soft-deleted (links to them are marked broken), so use traceable_block_write/traceable_block_update for incremental edits. Author multi-column bands with [[column-start count=N]] … [[column-break]] … [[column-end]] (one rich-text cell per column), and ID grids with [[id-header types=id,text,link]] + a label row followed by [[id-row id=…]] rows (link cells take whitespace-separated TraceID names). The title_* segments are the optional title page; writing to them on a document whose title page is switched off stores the content but it will not render until the page is enabled in the app.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document UUID |
segment |
header | body | footer | title_header | title_body | title_footer |
yes | Which segment to replace |
trmContent |
string |
yes | Traceable Markdown (TrMD). GitHub-flavored Markdown plus [[directive]] blocks, see traceable_capabilities. Read-only annotations ([[row]]/[[document]]) are rejected. |
traceable_block_write
Write access. Overwrites or removes things, asking twice does it twice.
Insert one or more body blocks at an anchor: after a TraceID (afterItemId), after a [[row N]]
anchor (afterOrder, from a document read), or at the start/end of the body (position; default
end). Returns the created rows with their new row orders, plus a renumbered marker when the
insert shifted existing rows. IMPORTANT: an insert renumbers every row after the anchor, so row
orders from earlier reads/responses go stale, re-read before further order-based calls, or anchor
by TraceID (immune to renumbering).
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document UUID |
trmContent |
string |
yes | Traceable Markdown (TrMD). GitHub-flavored Markdown plus [[directive]] blocks, see traceable_capabilities. Read-only annotations ([[row]]/[[document]]) are rejected. |
afterItemId |
string |
no | Insert after the row with this TraceID (e.g. FR-003) |
afterOrder |
number |
no | Insert after this row order (the [[row N]] anchor) |
position |
start | end |
no | Fallback position in the body when no anchor is given (default end) |
traceable_block_update
Write access. Overwrites or removes things, safe to ask for twice.
Replace one block. Identify it by its TraceID (itemId, e.g. FR-003) or by its [[row N]] anchor (atOrder, must come from a read issued after the last insert; inserts renumber later rows). trmContent must parse to exactly one block; page/section breaks in it replace the row's break flags. TraceID renames are not supported, use traceable_trace_id_rename.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document UUID |
trmContent |
string |
yes | Traceable Markdown (TrMD). GitHub-flavored Markdown plus [[directive]] blocks, see traceable_capabilities. Read-only annotations ([[row]]/[[document]]) are rejected. |
itemId |
string |
no | TraceID of the block to replace |
atOrder |
number |
no | Row order of the block to replace (the [[row N]] anchor) |
traceable_block_delete
Write access. Overwrites or removes things, safe to ask for twice.
Soft-delete one block (recoverable in the app). Deleting a table or ID header cascades to its children, and links to deleted trace targets are marked broken, the same semantics as deleting the row in the editor. atOrder must come from a read issued after the last insert (inserts renumber later rows); the response echoes the deleted row's itemId, verify it hit the intended row. Prefer itemId anchoring.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document UUID |
itemId |
string |
no | TraceID of the block to delete |
atOrder |
number |
no | Row order of the block to delete (the [[row N]] anchor) |
traceable_test_plan_read
Read access. Changes nothing.
Read a Test Plan, Test Report or Test Summary row: the record (its kind, its source documents and, for a report or summary, the published version each source is locked to), the columns the row shows, and every entry with its protocol TraceID, protocol cells, all column values, its evidence, the tester signature (if signed) and, for a protocol with test steps, each step (numbered from 1) with its text, acceptance criteria and recorded result.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document holding the row |
row |
{ kind?, itemId?, atOrder? } |
yes | The row: by kind (plan, report or summary, one of each per document), by TraceID, or by its [[row N]] anchor |
traceable_test_plan_entry
Write access. Overwrites or removes things, safe to ask for twice.
Record data in one entry of a Test Plan, Test Report or Test Summary, as {column: value}, in the columns that record holds. The entry's own columns are decision
(include or exclude), rationale, result_text, test_notes, samples, location, equipment, result
(pass, fail, or empty to clear), assessment, baseline_notes and resolution (passed, failed,
passed_with_deviation, failure_accepted, or empty for the derived default). With step, the
columns are that test step's result_text, notes and result. The same validation and limits apply
as in the editor. The tester's signature cannot be applied, and the row goes to review.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document holding the row |
row |
{ kind?, itemId?, atOrder? } |
yes | The row, as for traceable_test_plan_read |
entry |
{ entryId?, protocol? } |
yes | The entry, by id or by its protocol TraceID |
fields |
{ column: value } |
yes | The columns to write |
step |
number |
no | A test step, numbered from 1; omit for the entry's own columns |
traceable_test_plan_evidence_add
Write access. Only adds things, safe to ask for twice.
Attach file evidence to a Test Report entry, or to one of its test steps. The evidence is a Reference Library item the document references, named by REF code or item id; add the reference first with traceable_library_add_reference. It shows as a chip labelled in the document's citation format. To upload a new image or file, see traceable_test_plan_evidence_upload. The row goes to review.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document holding the row |
row |
{ kind?, itemId?, atOrder? } |
yes | The row, as for traceable_test_plan_read |
entry |
{ entryId?, protocol? } |
yes | The entry |
reference |
string |
yes | The Reference Library item's REF code or UUID |
step |
number |
no | A test step, numbered from 1; omit for the entry's own evidence |
traceable_test_plan_evidence_remove
Write access. Overwrites or removes things, safe to ask for twice.
Remove file evidence from a Test Report entry, or from one of its test steps. Any item of the project that is on the entry can be named, whichever document attached it. The Reference Library item itself is not deleted. The row goes to review.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document holding the row |
row |
{ kind?, itemId?, atOrder? } |
yes | The row, as for traceable_test_plan_read |
entry |
{ entryId?, protocol? } |
yes | The entry |
reference |
string |
yes | The Reference Library item's REF code or UUID |
step |
number |
no | A test step, numbered from 1; omit for the entry's own evidence |
traceable_test_plan_evidence_upload
Write access. Adds things without overwriting, asking twice does it twice.
Upload a file as evidence on a Test Report entry, or on one of its test steps. The file travels as base64 with its name. An image (PNG, JPEG, GIF or WebP, recognised from the file itself rather than its name) is shown inline in the Evidence column, exactly as an upload in the editor is. Any other file type is added to the project's Reference Library, referenced by the document, and attached as a file chip labelled in the document's citation format. At most 3 MB per file, because that is the largest request the server accepts once base64 has added its third. The row goes to review.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document holding the row |
row |
{ kind?, itemId?, atOrder? } |
yes | The row, as for traceable_test_plan_read |
entry |
{ entryId?, protocol? } |
yes | The entry |
name |
string |
yes | The file name |
content |
string |
yes | The file, base64-encoded |
step |
number |
no | A test step, numbered from 1; omit for the entry's own evidence |
traceable_image_upload
Write access. Adds things without overwriting, asking twice does it twice.
Upload an image to a document and get back the src to place it with. The image travels as base64
with its name. PNG, JPEG, GIF, WebP and AVIF are accepted, recognised from the file itself rather
than its name. SVG is not, because an SVG can carry script and the document is opened by other
people. At most 3 MB, for the same reason as Test Plan evidence. The result includes trmd, the
image written as , ready to put in a text row, a table cell or a text cell of an ID row
with traceable_block_write, traceable_block_update, traceable_segment_write or traceable_grid_cell. Add
{width=60%,align=center} straight after it to size and align it. Uploading places nothing by
itself.
A write may only place an image Traceable holds. An image on another website could change or
disappear after the document is published and signed, so a src on another site, or an image
embedded as a data: URI, is refused, and the assistant is told to upload it instead. Images
already in a document are kept when it is read and written back, including an image in an ID
grid cell, which reads as  in its cell.
In an organisation under controlled releases, this tool works once an organisation admin turns on Agents can upload images in Org settings > Releases.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document the image will be placed in |
name |
string |
yes | The file name |
content |
string |
yes | The image, base64-encoded |
alt |
string |
no | Alternative text; defaults to the file name |
Traceability
ID grids and the links between rows. An ID grid is the mechanism traceability is made of, so the grid tools and the link tools live together.
traceable_image_view
Read access. Changes nothing in the document, safe to ask for twice.
Look at an image in a document the assistant can read. It names the image by its src, exactly as a read of the document shows it. What comes back is a reduced copy, at most 512 pixels on its longer side and with its metadata (camera, location and the like) removed, never the stored file, together with the image's name, size and full dimensions. Only an image the document holds can be viewed.
Every view is recorded. The Review drawer's Agent changes tab lists the images agents viewed, and so does the Agent Changes row of a Review Log, under the changes, so a reviewer sees what the assistant looked at as well as what it changed. In an organisation under controlled releases, this works once an organisation admin turns on Agents can view images in Org settings > Releases.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document holding the image |
src |
string |
yes | The image src, as a read of the document shows it |
traceable_grid_column_add
Write access. Only adds things, asking twice does it twice.
Add a column to an ID grid. Every id-row gets a fresh empty cell, and existing cells and trace links are preserved. Identify the grid by its HEADER row (header.itemId or header.atOrder). Only one id column is allowed per grid. To set a CELL's value use traceable_grid_cell.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document UUID |
header |
object |
yes | Identify the row by itemId or atOrder (pass one). |
type |
id | text | link | calculation | dropdown | test-result | checkbox |
yes | The new column's type |
label |
string |
no | Header label (default: the type's default label, ID / Link / Column) |
insertAt |
number |
no | 0-based column position to insert at (default: append) |
traceable_grid_column_rename
Write access. Overwrites or removes things, safe to ask for twice.
Rename an ID-grid column: change its header text in place, leaving its type and cells alone. Use it to correct a mislabeled header (e.g. a default "Column").
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document UUID |
header |
object |
yes | Identify the row by itemId or atOrder (pass one). |
colIdx |
number |
yes | 0-based index of the column to rename |
label |
string |
yes | The new header text |
traceable_grid_column_set_type
Write access. Overwrites or removes things, safe to ask for twice.
Change an ID-grid column's type, converting each id-row cell to it. For typed columns pass config: { "options": ["Open","Closed"] } for a dropdown, { "op": "product", "sources": [1,2] } for a calculation. Trace links are preserved. Only one id column is allowed per grid.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document UUID |
header |
object |
yes | Identify the row by itemId or atOrder (pass one). |
colIdx |
number |
yes | 0-based index of the column to convert |
type |
id | text | link | calculation | dropdown | test-result | checkbox |
yes | The column's new type |
config |
object |
no | Per-column config: dropdown {options:[…]} or calculation {op, sources:[colIdx…]} |
traceable_grid_cell
Write access. Overwrites or removes things, safe to ask for twice.
Set one ID-grid cell's value, identified by the id-ROW (row.itemId or row.atOrder) and the 0-based
colIdx. NON-DESTRUCTIVE: the cell keeps its identity and the row's trace links survive, setting
the id column changes the visible TraceID without breaking links (unlike traceable_segment_write).
id/text columns take the raw value, and a text column also takes an image as
{width=60%} (upload it with traceable_image_upload); test-result normalises PASS/FAIL; checkbox normalises to
true/false (true/yes/1/✓ vs false/no/0/✗); dropdown takes the chosen option. Link cells are NOT
settable here, use traceable_link_create instead.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document UUID |
row |
object |
yes | Identify the row by itemId or atOrder (pass one). |
colIdx |
number |
yes | 0-based index of the column whose cell to set |
value |
string |
yes | The new cell value |
traceable_trace_id_rename
Write access. Overwrites or removes things, safe to ask for twice.
Rename a row's visible TraceID in place (a traceable row or an ID-grid row). The row keeps its database identity, so every trace link into or out of it survives; an ID-grid row's id cell is kept in sync and cached link labels that reference the old id are refreshed project-wide. Use this instead of delete-and-reinsert, which would break links. To renumber a whole grid, call this once per row (re-read afterwards is not needed, anchor by TraceID).
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document UUID containing the row |
fromItemId |
string |
yes | The current visible TraceID (e.g. UN-1.1) |
toItemId |
string |
yes | The new visible TraceID (e.g. UN-1), unique within the document |
traceable_link_create
Write access. Only adds things, safe to ask for twice.
Create a trace link between two TraceIDs (traceable rows, ID rows, or table trace rows), resolved
server-side within one project and addressed by the pair of TraceIDs, which is the address a
document read gives you. It is idempotent on the PAIR, not the direction: if an edge already
exists between the two rows in EITHER direction, the existing edge is returned and nothing is
written, existingDirection says "same" or "opposite", and on "opposite" a warning explains that
no chip was placed because a second edge would be a cycle. When the source row is an ID Row, the
link is also written into its link column so the chip SHOWS on the page, and placedInColumn says
which column took it: the row's first OUTPUT link column, since the target is downstream of the
source. Pass toColumnIndex to place it elsewhere. If the row has no link column the edge is still
created and pinned, and a warning explains why nothing is shown.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
fromDocumentId |
UUID | yes | Document UUID containing the source TraceID |
fromItemId |
string |
yes | Source TraceID (e.g. UN-4) |
toDocumentId |
UUID | yes | Document UUID containing the target TraceID |
toItemId |
string |
yes | Target TraceID (e.g. FR-012) |
toColumnIndex |
number |
no | Which of the source row’s link columns shows the chip; defaults to its first OUTPUT link column |
traceable_link_delete
Write access. Overwrites or removes things, safe to ask for twice.
Delete a trace link, addressed by the same pair of TraceIDs. It removes the edge AND the chip from the source row's link cell. Direction is not guessed: if the pair exists only the other way round, nothing is deleted and the error says so, because in a traceability chain the direction carries meaning.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
fromDocumentId |
UUID | yes | Document UUID containing the source TraceID |
fromItemId |
string |
yes | Source TraceID (e.g. UN-4) |
toDocumentId |
UUID | yes | Document UUID containing the target TraceID |
toItemId |
string |
yes | Target TraceID (e.g. FR-012) |
Library
The Reference Library, and citing from it.
traceable_library_search
Read access. Changes nothing, safe to ask for twice.
Find Reference Library items you can access (org-scoped items plus items in projects you are a member of). With query: keyword search across each item's name, REF code, and locally-extracted text (case-insensitive substring, no semantic/embedding search), returning matches with a short snippet around the first hit. WITHOUT query: lists every accessible item, REF code, name, kind (file | webpage), file type, scope (org | project), and whether its text has been indexed. Search only finds text that has been indexed, so if a search comes back empty, list first and check the indexed flag: an unindexed item is invisible to search until traceable_library_index runs on it.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
query |
string |
no | Keyword or phrase to search for. Omit to list every accessible item. |
organisationId |
UUID | no | Restrict to this organisation (defaults to your active org) |
traceable_library_read
Read access. Changes nothing, safe to ask for twice. Fetches from the web, so it reaches outside Traceable.
Return the extracted plain text of a Reference Library item, identified by its REF code (e.g. REF-00001A) or its id. Returns the stored indexed text when available, otherwise extracts on the fly without persisting. Unsupported types (PDF, PowerPoint, images) return empty text with an explanatory note, call traceable_library_index to persist supported text for search.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
code_or_id |
string |
yes | The item's REF code (e.g. REF-00001A) or its UUID |
traceable_library_index
Write access. Only adds things, safe to ask for twice. Fetches from the web, so it reaches outside Traceable.
Extract and persist the plain text of a Reference Library item (identified by its REF code or id) so it becomes searchable via traceable_library_search and cheap to read. Text extraction runs locally (docx, spreadsheets, CSV, and text/markup formats; webpage items are fetched). Returns the number of characters indexed, unsupported=true for types this slice cannot extract (PDF, PowerPoint, images), or noContent=true with a note for a reference that has no file or link (it records a document by its details only, so there is nothing to index).
| Parameter | Type | Required | Meaning |
|---|---|---|---|
code_or_id |
string |
yes | The item's REF code (e.g. REF-00001A) or its UUID |
traceable_library_add_reference
Write access. Only adds things, safe to ask for twice.
Attach a Reference Library item, or another document, to this document's reference list, and
ensure a Reference Table row exists to display it (created at the end of the body if absent). Pass
code_or_id (a library item's REF code e.g. REF-00001A, or its id, from traceable_library_search)
OR targetDocumentId (a document to cite), exactly one. The referenced version defaults to the
target's current/published version; override with referencedVersion. Idempotent: re-adding an
existing reference succeeds without duplicating it. Returns the referenceId, which a citation
uses: [label](cite:<referenceId>) in any text.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document to add the reference to |
code_or_id |
string |
no | Reference Library item REF code (e.g. REF-00001A) or its UUID |
targetDocumentId |
UUID | no | Instead of a library item, cite another document by its UUID |
referencedVersion |
number |
no | Pin a specific version (default: the target's current/published version) |
traceable_library_upload
Write access. Only adds things, but asking twice files the file twice.
Upload a file (a standard, a manual, a report: any type) to the Reference Library of the document's
project, and by default add it to the document's references in the same call. title sets the
name shown in the library (the file name by default) and number its designation, for example
"ISO 13485:2016". At most 3 MB; upload a larger file in the app. Returns the REF code, and the
referenceId a citation uses: [label](cite:<referenceId>). Its text is indexed straight away
where the type has text, so traceable_library_search finds it. To reference a file that is already
in the library, use traceable_library_add_reference instead. In an organisation under controlled
releases, this works once an organisation admin turns on Agents can upload reference files in
Org settings > Releases.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | A document of the project whose library receives the file |
name |
string |
yes | The file name, with its extension, e.g. "quality-manual.pdf" |
content |
string |
yes | The file, base64-encoded (a data: URL prefix is accepted) |
title |
string |
no | The name shown in the library (default: the file name) |
number |
string |
no | The reference's own designation, e.g. "ISO 13485:2016" |
addToDocument |
boolean |
no | Add it to the document's references (default true) |
traceable_glossary_search
Read access. Changes nothing, safe to ask for twice.
List the organisation glossary a document draws on, or the terms whose term or description contains
the query. Each term comes back with its id, the term, its kind (definition or acronym), its
description and its categories. Use an id with traceable_glossary_add_term, or in a
[[glossary terms=...]] row. In an organisation under controlled releases, this works once an
organisation admin turns on Agents can fill a Glossary in Org settings > Releases.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | A document in the organisation whose glossary to search |
query |
string |
no | Text to look for in terms and descriptions; omit to list every term |
traceable_glossary_add_term
Write access. Only adds things, safe to ask for twice.
Add a term to the document's Glossary. If the document has no Glossary row, one is created at the
end of the body; to put it somewhere else, write [[glossary]] there first. Name the term by its
id, from traceable_glossary_search, or by its text. A term the organisation glossary does not have
yet is created from the text, a description (required then), a kind and existing category names,
as any member can do in the Glossary panel. Adding a term the Glossary already shows changes
nothing. In an organisation under controlled releases, this works once an organisation admin turns
on Agents can fill a Glossary.
A Glossary row reads as [[glossary terms=<id>,<id>]], with any display option that differs from
the default (type, category, source, filter, title and column widths), so writing a read back keeps
the row exactly as it was. A term id from another organisation is left out with a warning.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | yes | The document whose Glossary to add the term to |
termId |
UUID | no | An existing term's id |
term |
string |
no | The term's text; created in the organisation glossary if it is new |
description |
string |
no | The definition, or what the acronym stands for; needed only for a new term |
kind |
definition | acronym |
no | For a new term; definition by default |
categories |
string[] |
no | For a new term: names of existing glossary categories |
Skills
Your organisation's skills, as published in its documents.
traceable_skill_list
Read access. Changes nothing, safe to ask for twice.
List your organisation's skills: the Skill rows in the latest published version of each document in the projects you belong to, each with its skill id, name, description (when to use it), tags, document type, the version it comes from and its source document and project. The assistant is told to call this when it connects. Draft skills are added only when asked for, marked as draft, and only for roles that can read drafts. In an organisation under controlled releases this works once an admin turns on Agents read skills.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
projectId |
UUID | no | Only this project |
tag |
string |
no | Only skills with this tag |
documentType |
string |
no | Only skills for this document type |
query |
string |
no | Text to look for in the name and description |
includeDrafts |
boolean |
no | Also list draft skills, marked as draft; false by default |
traceable_skill_read
Read access. Changes nothing, safe to ask for twice.
One skill as a SKILL.md file: front-matter with its name, description, title, tags,
document type, status, version and source document, then the instructions. It serves the skill
as it stands in its document's latest published version, or the open draft when status is
draft.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
skillId |
UUID | yes | A skill id from traceable_skill_list |
status |
published | draft |
no | Which copy to read; published by default |
Messages
Your document Discussions and your direct and group conversations, read and posted in as you.
traceable_thread_list
Read access. Changes nothing, safe to ask for twice.
List the document Discussions in your projects, each with its document id, name, how many messages you have not read and when it was last active, and your direct and group conversations in one organisation, each with its id, kind, name, members, unread count and last message. The conversations are those of your active organisation unless you name another you belong to. Nothing is marked read.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
organisationId |
UUID | no | List the conversations of this organisation instead of your active one |
traceable_thread_read
Read access. Changes nothing, safe to ask for twice.
Read one document's Discussion or one conversation: every message oldest first, with its replies, author, the assistant it was posted via if any, time, text, reactions, the tasks assigned from it and the lines recording what happened to them. It also says whether you can post there and lists the people you can mention, with their ids. It reaches your direct and group messages as well as Discussions, and leaves every message unread for you.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | one of the two | The document whose Discussion to read |
conversationId |
UUID | one of the two | The conversation to read |
traceable_thread_post
Write access. Only adds things, asking twice does it twice.
Post a message, or a reply under a top-level message, in a document's Discussion or a conversation, as you, marked as posted via the assistant. Everyone in the thread sees it and is told about it as for any message, and anyone it mentions gets a mention. It is refused where you could not post yourself: a Discussion needs a reviewer role or above, and a conversation needs you to be in it.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
documentId |
UUID | one of the two | The document whose Discussion to post in |
conversationId |
UUID | one of the two | The conversation to post in |
content |
string |
yes | The message, up to 4000 characters |
replyTo |
UUID | no | A top-level message to reply under |
mentions |
UUID[] | no | People to mention, by the ids traceable_thread_read lists |
Capabilities
What the format itself supports.
traceable_capabilities
Read access. Changes nothing, safe to ask for twice.
The Traceable Markdown (TrMD) format spec and capabilities manifest: row types, block directives, layout directives, segments, property tokens, and paper sizes. Read this before reading or authoring documents.
Takes no parameters.
12. Where to get help
- In-app: Help (guides and search), or the Support menu to ask a question.
- Org admins control MCP access and the AI change review setting.
See Traceable on your own documents
Import your existing requirements and see live traceability in minutes.