EMET

write_doc_begin

Start a staged write for documents too large for one write_doc call. Append each part, then commit them as a single revision.

Instructions

Open a staged write when a document will not fit in one write_doc argument. The stage is not a document and does not change the current revision. Send each part with write_doc_append, then write_doc_commit. A record (HANDOFF.md and any id in EMET_RECORD_DOCS) still needs supersedes and reason; commit writes one whole revision through write_doc. Limits: 16000 characters per part, 128 parts, 2000000 characters total, 30 minutes from begin, 4 open stages per writer. Same source, session, and writer stamp as write_doc.

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": {
      "doc_id": "<doc_id>"
    },
    "name": "write_doc_begin"
  }
}

Input Schema

Name	Required	Description
`doc_id`	Yes
`reason`	No	Required on a record revision (at least 10 characters). Stored on the stage and passed to write_doc at commit.
`source`	No	Source tag - which host produced this write. One name on every write since 2026-09-27.
`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.
`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).
`supersedes`	No	Required when staging a new revision of a RECORD: the version currently in force. Stored on the stage and passed to write_doc at commit.
`updated_by`	No	Alias of `source` (the older name, kept one release). Prefer `source`.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.3.2Oct 29, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations only say this is a non-idempotent, non-destructive write; the description adds far more: the stage has no effect on the current revision until commit, hard limits (16000 chars/part, 128 parts, 2M total, 30-minute window, 4 open stages per writer), and the record-revision requirements. That is exactly the operational context an agent needs before opening a stage.

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?

The precondition is front-loaded, the sequence follows in one sentence, and the limits are compressed into a single tight line. Nearly every clause carries new information; nothing is redundant with the title or annotations.

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 stateful, multi-step write flow with no output schema, the description covers the trigger, the full call sequence, the no-op-until-commit semantics, resource limits, and the record-revision exception. Nothing essential to invoking 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 coverage is 86%, so the schema already carries most parameter meaning (reason, supersedes, session_id, exchange). The description adds the linkage that reason and supersedes are stored on the stage and passed to write_doc at commit, plus the 'same source, session, writer stamp as write_doc' rule, which is genuine value 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?

The opening sentence gives a specific verb and resource ('Open a staged write') and immediately states the triggering condition ('when a document will not fit in one write_doc argument'), which cleanly separates it from write_doc, write_doc_append, and write_doc_commit. An agent can pick this tool without opening the 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?

It names the full workflow (append each part with write_doc_append, then write_doc_commit) and the alternative (write_doc for a whole revision at commit). It also states what the tool is not ('the stage is not a document and does not change the current revision') and flags the record special case requiring supersedes and reason.

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