Skip to main content
Glama

Traceable

by com.traceabledocs.app
OverviewDiscussionsAdmin

Update block

traceable_block_update
DestructiveIdempotent

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.

Input Schema

NameRequiredDescriptionDefault
itemIdNoTraceID of the block to replace
atOrderNoRow order of the block to replace (the [[row N]] anchor)
documentIdYesThe document UUID
trmContentYesTraceable Markdown (TrMD). GitHub-flavored Markdown plus [[directive]] blocks — see traceable_capabilities. Read-only annotations ([[row]]/[[document]]) are rejected.
baseRevisionNoThe revision (meta.revision) from the traceable_doc_read, or the previous write, this change is based on. When given, the write is refused with nothing changed if the document has changed since, so you never overwrite edits you have not seen. Each write returns the current revision. The revision tracks the document's content rows, so changes that touch no row (its name and other metadata, the reference list, Test Plan entries) return it unchanged. A revision is an opaque value: compare it whole, never read meaning into its parts (they are not a counter).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / baseRevision
      Added value: +{
+  "description": "The revision (meta.revision) from the traceable_doc_read, or the previous write, this change is based on. When given, the write is refused with nothing changed if the document has changed since, so you never overwrite edits you have not seen. Each write returns the current revision. The revision tracks the document's content rows, so changes that touch no row (its name and other metadata, the reference list, Test Plan entries) return it unchanged. A revision is an opaque value: compare it whole, never read meaning into its parts (they are not a counter).",
+  "type": "string"
+}
  2. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already cover the safety profile (destructiveHint=true, idempotentHint=true, readOnlyHint=false), but the description adds real behavioral context: inserts renumber later rows (invalidating stale anchors), page/section breaks in trmContent overwrite the row's break flags, and read-only annotations are rejected. It stops short of saying what happens to the replaced block's TraceID or its non-content metadata.

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

Conciseness5/5

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

Four tight sentences, front-loaded with the action, then identification, then content constraint, then the rename escape hatch. No filler and no repetition of schema text.

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

Completeness4/5

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

For a destructive single-block mutation with no output schema, the description covers identification, freshness preconditions, break-flag side effects, and routing to the rename tool. The remaining gap is the effect on the replaced block's TraceID and metadata, plus any reference/link handling, which an agent might need.

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 coverage is 100%, so the schema already documents all five parameters and a 3 would be the baseline. The description goes beyond it by glossing itemId as a TraceID example (FR-003), tying atOrder to the [[row N]] anchor with a freshness constraint, and constraining trmContent to exactly one block — semantics the schema descriptions do not carry.

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 ('Replace one block') and immediately scopes it to a single block, distinguishing it from a bulk or multi-block operation. It also names the sibling it is not (traceable_trace_id_rename) for the rename case, so an agent can route without opening another schema.

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

Usage Guidelines4/5

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

Gives explicit identification alternatives (TraceID via itemId vs [[row N]] anchor via atOrder) and the precondition that atOrder must come from a read issued after the last insert. It also states an exclusion (renames not supported, use traceable_trace_id_rename), but does not contrast this tool with traceable_block_write (insertion) or traceable_block_delete.

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

All Traceable toolsInspect
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