EMET

write_doc_append

Idempotent

Append the next ordered chunk of an open stage, enforcing sequential parts and size limits so documents stay consistent. Refuses skipped parts, mismatched bytes, or chunks over 16000 characters without changing the document.

Instructions

Append the next ordered chunk of an open stage. part starts at 1 and increases by one. The same part with the same bytes is a no-op. A different byte string, a skipped part, or a chunk over 16000 characters is refused and the current document is unchanged.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "stage_id": "<stage_id>",
      "part": "<part>",
      "chunk": "<chunk>"
    },
    "name": "write_doc_append"
  }
}

Input Schema

Name	Required	Description
`part`	Yes	The 1-based part index. The next part is next_part from the previous call. A whole number sent as text is accepted.
`chunk`	Yes	The next slice of the document, at most 16000 characters. Chunks are concatenated in order at commit.
`source`	No	Source tag. Must be the same source the stage was begun with.
`exchange`	No	The exchange (turn) this write belongs to, counting from 1. A write for exchange n while exchange n-1 was never appended is refused by the session graph until n-1 is appended.
`stage_id`	Yes	The stage_id write_doc_begin returned.
`session_id`	No	Your transcript session id from emet_session_open. The session graph reads this session's state before the write and returns `session_graph.next` - the next step. A governed write with no session is refused (open one with emet_session_open and load_id).
`updated_by`	No	Alias of `source`. Prefer `source`.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.3.2Oct 29, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare destructiveHint=false and idempotentHint=true, so the description earns credit for going beyond that: it explains the no-op condition (same part, same bytes), the three refusal conditions, and crucially that a refused write leaves the document unchanged. It omits the session-graph refusal behaviour, though the schema's session_id description covers that.

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?

Four short sentences, front-loaded with the core action, then the ordering rule, then the safety guarantees. The ordering and size sentences partially duplicate the schema, keeping it just under top marks.

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?

No output schema, yet the description covers the mutation semantics, idempotency, and failure atomicity that an agent needs before calling a write tool. It does not explain the returned next_part/next-step signal itself, relying on the schema for that, which is a minor gap for a 7-parameter governed write.

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

Parameters3/5

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

Schema coverage is 100% and each of the 7 parameters is documented in the schema, including the part/next_part relation and the 16000-character chunk limit. The description restates the ordering and size rules without adding syntax or format detail beyond the schema, so baseline 3 applies.

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

Purpose4/5

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

Specific verb+resource: 'Append the next ordered chunk of an open stage' tells the agent exactly what happens and that it targets a staged document rather than a committed one. Sibling tools like write_doc, write_doc_begin and write_doc_commit are never named, so differentiation is inferred from the word 'stage' rather than stated.

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

Usage Guidelines3/5

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

The sequencing contract (part starts at 1, increases by one, next part is next_part from the previous call) gives strong implied usage for the staged-write flow. However, there is no explicit guidance on when to choose this over write_doc or when to move on to write_doc_commit/write_doc_abort, and no exclusions.

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