Traceable

Create document

traceable_doc_create

Create a document in a project. Start from a template: pass templateId to clone an org/system template (header/footer bands, title page, revision + signature scaffolding come along — discover templates with traceable_workspace_templates); trmContent is then APPENDED after the template's body, so read the template first (traceable_doc_read) and do not repeat its headings or scaffold rows; change template rows afterwards with traceable_block_update or traceable_block_delete. To put content under one of the template's own headings (for example an ID grid under "Functional Requirements"), create the document first, read it, then traceable_block_write with afterOrder set to that heading's [[row N]]. Without a template, only default header/footer bands are seeded for any segment trmContent does not provide. A controlled document should end up with a Revision Table, a Reference Table, a Glossary (add its terms with traceable_glossary_add_term) and ID rows for everything that must be linked: see documentComposition in traceable_capabilities. A test report places its Test Plan with [[test-plan plan=""]], naming a plan that already exists in Project settings. To put the new document on its project's board (a Design Phases cell, or a cell of the quality system diagram), pass placement with a cell's phaseId and workstreamId from traceable_board_read. To write the document a placeholder card planned, pass placeholderId (a placeholder's cardId from traceable_board_read) 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.

Input Schema

Name	Required	Description
`name`	Yes	Document name
`groupId`	No	Document group UUID (from traceable_workspace_map)
`idPrefix`	No	TraceID prefix (uppercase letters/digits/hyphens, e.g. FR)
`placement`	No	A board cell to put the document in (from traceable_board_read)
`projectId`	Yes	The project UUID (from traceable_workspace_projects)
`templateId`	No	Template document UUID to clone
`trmContent`	No	Initial TrMD content. With templateId it is body content appended after the template body
`documentType`	No	Document type from the organisation taxonomy
`placeholderId`	No	A placeholder card (its cardId from traceable_board_read) this document is written for; it takes the card
`documentNumber`	No	Document number (e.g. PRJ-003)

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 18, 2026

addedInput schema / properties / placeholderId

Added value: +{
+  "description": "A placeholder card (its cardId from traceable_board_read) this document is written for; it takes the card",
+  "format": "uuid",
+  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+  "type": "string"
+}

addedInput schema / properties / placement

Added value: +{
+  "description": "A board cell to put the document in (from traceable_board_read)",
+  "properties": {
+    "phaseId": {
+      "description": "The cell's phaseId (from traceable_board_read)",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+      "type": "string"
+    },
+    "position": {
+      "description": "Where in the cell, 0 being the top. Defaults to the end.",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "workstreamId": {
+      "description": "The cell's workstreamId (from traceable_board_read)",
+      "format": "uuid",
+      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+      "type": "string"
+    }
+  },
+  "required": [
+    "phaseId",
+    "workstreamId"
+  ],
+  "type": "object"
+}

Changed1 schema field changedOct 15, 2026

changedInput schema / properties / trmContent / description

Previous value: -"Initial TrMD content (body only when templateId is set)"New value: +"Initial TrMD content. With templateId it is body content appended after the template body"

Changed1 schema field changedOct 5, 2026
- changedInput schema / properties / documentNumber / description
```
Previous value: -"Document number (e.g. TD01-003)"New value: +"Document number (e.g. PRJ-003)"
```
First observedOct 4, 2026

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower; the description still adds non-obvious behavior: trmContent is APPENDED after the template body, only default header/footer bands are seeded for segments trmContent omits, and the call returns documentId plus created rows with row orders. It does not disclose permission requirements or any rate limits, keeping it out of the top band.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then organized by concern (template, content, composition, board placement, placeholder, returns). It is long and somewhat run-on with many parenthetical cross-references, but the length is largely justified by a 10-parameter tool with nested placement and no output schema; the test-report and composition sentences are the most tangential.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex create tool with 10 parameters, a nested placement object, and no output schema, the description covers template interaction, content append semantics, board placement, placeholder consumption, and the return shape. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description earns an upgrade by explaining interactions the schema cannot, notably that templateId clones an org/system template including bands and revision/signature scaffolding, that trmContent is appended after the template body, and that placeholderId makes the document take the placeholder card's cell and position. It does not add syntax guidance for idPrefix or documentType beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ("Create a document in a project") and immediately differentiates itself from read/update/archive siblings by describing clone-from-template, append, and placement behavior. An agent can distinguish this from traceable_doc_read, traceable_doc_update_meta, and traceable_block_write without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes to alternatives and conditions: discover templates via traceable_workspace_templates, read the template first with traceable_doc_read before appending, use traceable_block_update/delete to change template rows, and traceable_block_write with afterOrder to nest under a template heading. It also states what happens without a template (only default bands seeded), which is a genuine when-not branch.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Traceable tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?