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

Annotations only declare write/non-idempotent/non-destructive; the description adds far more: the marker is RETAINED rather than cleared, the acceptance covers only the named revision so the next write is validated fresh, and accepted markers are counted separately from open ones at session start. It also states the audit-facing durability of the reason.

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

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

Front-loaded with the core action, then layered with genuinely useful lifecycle behavior. Every sentence carries weight, though the closing constraint note slightly overlaps the schema and keeps it from being maximally tight.

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

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

For a 6-param write tool with full schema coverage and no output schema, the description covers purpose, lifecycle, persistence, and validation semantics well. It stops short of naming sibling alternatives, but an agent has what it needs to call it correctly.

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

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

Schema coverage is 100%, so doc_id, reason, source, exchange, etc. are already documented. The description reinforces the ≥10-character reason constraint and its audit purpose, but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: 'Record the written disposition for a nonconformance that will not be corrected.' It makes the scope unmistakable (only for nonconformances deliberately left uncorrected) and clearly separates this action from the alternative path where a revision later passes.

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

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

It gives clear selection context: use it when a marker will not be corrected, since it otherwise leaves only via a passing revision. However, it never names the sibling tools (e.g. validate_doc or write_doc) that represent the other path, so the routing is implied rather than explicit.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior, so the description's job is to add context. It does so by disclosing the empty-result condition ('returns nothing unless a corpus has been populated') and the separate-corpus scope, both of which are useful traits not visible in the annotations or schema.

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

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

Two tight sentences with the primary action front-loaded and the scoping caveat immediately after. No filler, though the second sentence's second clause slightly overlaps the first sentence's 'loaded separately from memory' idea.

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

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

For a 3-parameter, no-output-schema read tool with full schema coverage, the description supplies the key precondition and scope boundary. The only real gap is the absence of explicit routing guidance relative to recall/semantic_recall.

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

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 adds no syntax, format, or default details for query, limit, or corpus beyond what the schema already documents.

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

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

States a specific verb and resource: semantic search over a supplementary knowledge corpus. It also explicitly rules out session memory, which helps separate it from the recall/semantic_recall siblings, but it never names those siblings directly.

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

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

It gives a precondition (a corpus must have been populated) and implicitly signals usage via the contrast with session memory, but there is no explicit statement of when to choose this over recall, semantic_recall, or query_layer.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: the floor ships in server code, setup cannot overwrite it, installs cannot lose it, and the character document layers user modifiers on top. The closing note that re-reading is not the same as being bound by it also characterizes the operation's limits.

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

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

Front-loaded with the definition, then provenance, then the initialize relationship, then the compact tip. Every sentence carries information, though the server-code/character-document provenance sentence is denser than strictly needed for invocation.

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

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

For a zero-required-parameter, read-only tool with no output schema and full schema coverage, the description supplies everything needed: what the floor is, why it persists, how it relates to initialize, and when to use the compact form. No meaningful gap remains.

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

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 — both compact and section are already documented in the schema. The description goes one step further by supplying the situational trigger for compact (long session, distant conversation start), which the schema's terse 'short re-assertion form' does not convey.

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

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

States a specific verb+resource ('Read the floor') and then defines what the floor is — the standing description of how the assistant engages with the user. It explicitly distinguishes itself from the sibling emet_initialize, noting that initialize already returns the whole floor at session start, so an agent can route correctly without opening either schema.

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

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

Names the alternative (emet_initialize) and the exact condition for choosing this tool instead: re-reading without re-running initialize. It also gives concrete when-to-use guidance for the compact parameter ('partway through a long session, when the start of the conversation is far behind').

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds value beyond them: "identifies and never fills," the return expectation "digest mismatches (the alarm - expect zero)," and the note that counts are complete while ids are capped. It stops short of describing the response shape in full.

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

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

Dense but front-loaded: the operation and its read-only nature come first, then the enumerated classes, then usage. The list of gap classes is long but each item is distinct and informative. The opening metaphor is a minor flourish that costs a few words.

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

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

For a read-only diagnostic query with no output schema, the description is largely sufficient: it names every gap class, states counts are complete, and explains what closing a gap entails. Only the exact response structure and id-format remain unspecified, which is a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents layer, limit, and since in detail. The description adds no parameter-level syntax or defaults; its references to tags, sessions, and the 2026-09-05 boundary describe gap classes rather than inputs. Baseline 3 applies.

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

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

After a metaphorical opening ("the record's honesty about its own holes"), it states a concrete verb and resource: "Counts, with the ids behind them, for each gap class," and enumerates those classes (unsourced assertions, digest mismatches, broken supersession, etc.). This distinguishes it from siblings like emet_status or query_layer, though the poetic framing costs some immediate clarity.

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

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

Explicit triggers are given: "Call it when asked how trustworthy the record is, before a consolidation pass, or after any migration." It also names the follow-up path, routing remediation to revise_memory "with a real derived_from where the source is knowable," and clarifies the tool itself never fills gaps.

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

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

Annotations declare idempotent, non-destructive, and readOnlyHint=false; the description adds real behavioral detail beyond that - paginated startup, the read-page_notice/recall loop, load_id threading, and the conditional new-store interview vs. established-store profile. It doesn't explain why readOnlyHint is false despite describing a largely read-oriented setup, a minor gap.

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

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

Front-loaded with the imperative call-to-action and ordered logically (when to call, then paging, then outcomes). It is dense and long, but each sentence carries procedural meaning, so little is wasted.

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

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

With no output schema, the description carries the burden and does: it explains paged returns, the load_id contract, both new-store and established-store outcomes, and the sequencing with emet_session_open. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the paging workflow ('read page_notice first and call again'), the role of load_id across pages and into emet_session_open, and the defaulting behavior around recent context - value beyond the raw field descriptions.

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

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

States a specific action (start/set up the session for a memory store) with front-loaded imperative 'START HERE. Call this FIRST,' and distinguishes its role from siblings like emet_session_open by naming the setup step it owns. An agent immediately knows this is the session-initiation tool.

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

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

Explicitly says when to call (first in every session, when the user opens with 'initialize'/'start'/'begin'/'hello', or before any answer relying on prior context) and how to sequence it with emet_session_open and the paging loop. Both the trigger conditions and the alternative/next-step tool are named.

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

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

Annotations already declare the safe/one-shot profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuinely new context: the code is one-time, access defaults to read-only, and creation is restricted to the owner — a meaningful permission constraint not captured elsewhere.

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

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

Four short, front-loaded sentences with no filler. The core action leads, followed by mechanism, constraints, and a routing note to the sibling tool.

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

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

For a small three-parameter mutation tool with full schema coverage and no output schema, the description covers purpose, auth restriction, defaults, and sibling disambiguation. Only the returned artifact (the actual code) is left implicit, a minor gap.

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

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

Schema coverage is 100%, so the schema already documents display_name, days (default 14), and scopes (default emet.read). The description's 'default access is read-only' merely restates the scopes default, adding no syntax or meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('create a one-time code for a guest') and explains the mechanism (pasted on the connect screen instead of the passphrase). It also explicitly distinguishes itself from the sibling emet_member_access_create by calling member access 'a different door'.

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

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

Clear context for when this applies (guest access via a code rather than a passphrase) and it names the adjacent alternative (EMET Member Access). It stops short of spelling out the selection criteria between guest vs. member access beyond the metaphor.

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

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

Annotations only cover the generic safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds substantive behavior beyond them: creator authorization ('Only the owner can create it'), the fact that it does not confer ownership, the redeem-on-connect-screen flow, single-use nature of the code, and a feature-flag prerequisite.

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

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

The purpose is front-loaded in the first sentence, followed by disambiguation and constraints in compact form. The telegraphic fragments ('Only the owner can create it. Off unless EMET_MEMBER_ACCESS=1.') are slightly clipped but each carries real information.

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

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

With no output schema, the description should indicate what the call yields; it implies a generated code but does not state the return shape or what happens when the tool is disabled or the caller lacks owner rights. Otherwise it covers prerequisites and scope well for a simple two-parameter tool.

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

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

Schema description coverage is 100%, so both parameters (display_name, days) are already fully documented in the schema, including the important note that a name never selects an existing person. The description adds no additional parameter-level detail, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('create a one-time code for a new person with read and write access') and explicitly frames the scope against 'EMET Guest Access' and ownership. However, it never distinguishes itself from the actual sibling tool 'emet_invite_create', which is the closest candidate for confusion, so sibling differentiation is incomplete.

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

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

It states clear conditions: only the owner can call it, the recipient uses the code on the connect screen instead of the passphrase, and the tool is inactive unless EMET_MEMBER_ACCESS=1. What is missing is an explicit routing statement against alternatives such as emet_invite_create or the guest-access path.

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

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

It discloses behavior far beyond the annotations: the receipt-comparison protocol, that omitted/mismatched receipts, a non-last handoff, or an uncited transcript yield state 'blocked'; that three blocked closes yield 'escalate' and that the counter persists across receipt changes; and that every 'speak' line must be relayed. One mild tension: readOnlyHint=false implies side effects while the text says it 'does not write anything itself', though the persistent blocked-close counter plausibly accounts for the non-idempotent annotation.

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

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

The text is long but dense, and the most consequential rules are front-loaded (when to call, then what it does, then RECEIPTS ARE REQUIRED) with emphasis markers for the blocked/escalate branches. A few clauses, such as the repeated warnings about relaying speak lines, could be tightened, but almost every sentence carries an operative rule.

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

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

Despite a complex 6-parameter schema with a nested receipts object and no output schema, the description covers the return states ('complete', 'blocked', 'escalate'), the per-line 'scope' field, and the required 'speak' output, so an agent knows both how to call it and how to act on the result. Nothing essential is left unspecified.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema cannot: receipts are required for state 'complete', each receipt is compared against the store, and each missing line carries a 'scope' telling the agent to touch only what it names. It also stresses receipts must come from tool returns, not recall, which is meaningful usage guidance for the nested object.

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

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

The description states a precise verb+resource: it 'Checks whether this session's work has actually been written to the store and reports exactly what is missing' and explicitly disclaims writing ('It does not write anything itself'). This distinguishes it cleanly from sibling write tools like save_to_layer, write_doc, and emet_transcript_append, and from the sibling emet_status.

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

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

It gives explicit triggering conditions ('user says goodbye, asks you to wrap up, mentions restarting or opening a new session, or you are about to run out of room') and an explicit exclusion ('An acknowledgement of the turn just completed - thanks, great, perfect - is not a session end'), plus a tie-breaker ('if it is ambiguous, ask rather than close'). This is exactly the when/when-not guidance the dimension rewards.

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

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

Goes well beyond the annotations: discloses the timezone (EMET_TIMEZONE, default America/New_York), the CLOSED-slug collision rule (session opens as <id>-2, -3 with a `notice`), and the refusal path for a missing/unmatched load_id. These are non-obvious behavioral traits that the readOnlyHint/not-destructiveHint/not-idempotentHint annotations cannot convey.

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

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

Front-loaded with the core action and return values, then the load_id gate and workflow. Dense with information, though a couple of sentences are long and slightly clause-heavy; little is wasted.

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

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

No output schema exists, and the description covers the return (session_id, timezone, `notice`) plus the prerequisite gate and the required follow-up call. An agent has everything needed to invoke it correctly and continue the session workflow.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains why load_id is optional in the schema yet required by policy, and clarifies slug collision semantics. It gives more semantic context than the schema alone.

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

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

States a specific verb and resource ("Open a transcript session") and immediately specifies what it returns (session_id) and the scoping behavior. An agent can distinguish it from emet_session_close and emet_transcript_append without opening any schema.

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

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

Explicitly instructs to pass load_id from startup_page and states the refusal condition when it is missing or unfetched, naming the gate. It also prescribes the follow-up workflow ("After every reply, call emet_transcript_append with that id") and warns against dumping the whole chat, which routes the agent correctly.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false; the description adds substance beyond them: every write is read-back verified, bot-tag refusal, and the key safety nuance that on re-run prior versions are archived, never destroyed. That directly informs the agent about irreversibility and preconditions.

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

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

Front-loads the scoping statement ('First-time setup, the owner's only') and packs multiple constraints into a tight block. Slightly dense and repeats the bot-tag refusal that also appears in the schema, but no sentence is wasted.

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

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

For a destructive, bot-refusing, non-idempotent mutation with a nested answers object and no output schema, the description covers preconditions, re-run semantics, and archival behavior well. It does not state what the tool returns, which is the only notable gap.

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

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

Schema description coverage is 100%, so the schema already documents source, answers, and reissue. The description adds context (owner-only, explicit-word requirement for reissue, refusal otherwise) but no parameter syntax or format detail beyond what the schema provides. Baseline 3 applies.

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

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

Names a specific effect (record interview answers into bootstrap/IDENTITY.md, CHARACTER.md, USER.md plus an identity-layer entry, and create the owner person) with a clear actor/scope ('the owner's only'). This is unmistakably distinct from siblings like emet_initialize, emet_status, and write_doc.

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

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

Gives explicit when-to-use ('First-time setup'), when-not ('Refused under a bot tag'; refused on an already-set-up store unless reissue is true), and the escape hatch (reissue = owner's explicit word). Conditions for selecting the behavior are fully spelled out.

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

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

With readOnlyHint=false already declared, the description explains why: probe:true writes a document, reads it back, then removes it, so the agent understands the write and its cleanup rather than assuming a pure read. That closes the apparent gap between a 'status' tool and a non-read-only annotation. It does not cover auth requirements or failure modes.

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

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

Three front-loaded sentences with no filler; the diagnostic scope comes first, then the probe semantics, then the routing hint. The parenthetical list of replaced tools is the only slightly bulky element, but it earns its place as a migration cue.

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

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

There is no output schema, so the description carries the burden of describing the return surface - and it does, enumerating environment, database, collections, index, identity/user documents, and counts. Combined with the probe explanation and the emet_initialize route, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds real value beyond the schema by explaining the rationale - 'a read alone cannot reveal a broken write path' - which tells the agent why probe exists, not just what it does.

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

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

States a specific purpose - a one-call diagnostic - and enumerates exactly what it reports (environment, database, collections, vector index, identity/user docs, per-layer counts and health). It also names the siblings it replaces and distinguishes itself from emet_initialize, so an agent can tell it apart 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.

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

Explicitly routes the agent: 'Prefer emet_initialize for a normal session start' names the alternative and its condition, and the probe parameter is scoped to 'after a deploy or a configuration change'. Both when-to-use and when-not-to-use are stated.

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

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

Goes far beyond the annotations: part rolling after 8 exchanges, the single closing-exchange exception after close, the grace window, the lock state, refusal semantics, and the first-append machine-line gate. The only blemish is the claim "Idempotent on exchange_index" sitting against idempotentHint=false; it is defensible as scoped idempotency (a repeated index writes nothing) rather than a safety-relevant contradiction, but the two signals are not obviously reconciled for the agent.

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

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

Front-loads the core purpose and routing rule in the first two sentences, then layers edge cases in descending priority. It is long and occasionally dense (the closing-exchange paragraph is a single run-on chain), and "whatever session_id it names" is a minor detour, but almost every sentence carries operational weight.

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

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

For a complex, stateful, multi-constraint write tool with no output schema, the description covers the full lifecycle: normal append, part rollover, close grace append, retry resolution, and refusal. It even describes the observable result field (`closing_exchange`) that confirms acceptance, so an agent can act and verify without further documentation.

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

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

Schema coverage is only 29% across 7 parameters, so the description must compensate. It does add real meaning for exchange_index (whole number of 1 or more, number or its textual form) and for assistant_message on the first append (must carry the measured machine line or "no local shell MCP"), but source, channel, session_start, user_message and the closing-exchange assistant_message content are left to the schema or undocumented.

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

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

States a precise verb and resource ("Append ONE exchange to the session transcript") and even emphasizes the unit of work with capitalised "ONE", which separates it from bulk siblings like save_transcript and revise_transcript. An agent knows exactly what this writes and at what granularity 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.

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

Explicitly says "Call after every reply", then spells out the when-not cases: appends to a closed session are refused and "that exchange belongs in the next session you open the usual way", with a named exception window (EMET_CLOSE_GRACE_MINUTES). This is textbook when/when-not guidance with the alternative route named.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely non-obvious behavior: retired docs are retained but hidden by default, and when shown are flagged with retirement date and reason. This is useful context beyond the annotations, though it doesn't describe pagination or ordering.

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

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

Two tight sentences with no filler. The core purpose and the default-vs-override behavior are front-loaded, and every clause earns its place.

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

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

With no output schema, the description carries the return-value burden and does note 'metadata only' plus the retirement flagging. For a simple two-parameter read tool this is nearly complete; only ordering/pagination is left unstated.

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

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

Schema coverage is only 50% (prefix has no schema description), and the description compensates by explaining prefix as a doc_id prefix filter with an example ('threads/'). include_retired's semantics are reinforced in both places, so the description meaningfully closes the coverage gap.

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

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

States a specific verb+resource ("List continuity documents") and adds a clear scope qualifier (metadata only). It is instantly distinguishable from siblings like read_doc, write_doc, and retire_doc, which are single-document operations.

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

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

Explains the key usage condition: retired documents are hidden by default and you pass include_retired to see them. It does not, however, explicitly name an alternative tool (e.g. read_doc) or state when this listing is preferable over corpus_recall/semantic_recall, so the routing guidance is good but not exhaustive.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the mutation profile is known. The description adds genuinely useful behavior beyond that: exact-once match enforcement with ambiguous matches rejected rather than guessed, empty new_str as delete, and parity with write_doc's versioning/archiving/sha256 read-back. It does not discuss permissions or what a failed multi-edit leaves behind (that detail lives in the schema).

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

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

Four tight sentences, front-loaded with the operation and its mechanism, then preference guidance, then the critical exact-match constraint, then delete behavior and parity guarantees. No filler and each sentence carries distinct information.

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

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

For an 11-parameter mutation tool with no output schema, the description covers the core mental model (substring replacement, ambiguity rejection, delete, versioning parity) and the schema carries the remaining parameters at 91% coverage. It omits any narrative about the session/exchange graph constraints and batch-edit atomicity, which are only in schema text, but 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.

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

Schema description coverage is 91%, so the schema already documents nearly every parameter including the edits array, origin, reason, exchange and expected_version. The description only restates old_str/new_str semantics already present in the schema, adding no syntax, format, or constraint detail beyond it. Baseline 3 is appropriate.

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

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

Names a specific verb+resource with its mechanism ('Replace one exact substring ... str_replace semantics') and explicitly distinguishes itself from the full-file alternative ('without resending the whole file'). An agent can tell this apart from write_doc and revise_memory from the first sentence alone.

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

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

Gives clear selection context: 'THE PREFERRED WAY TO MAKE SMALL EDITS to large docs like STATE.md' implicitly routes full rewrites to write_doc. It stops short of naming write_doc explicitly or stating when-not to use patching (e.g. multi-region rewrites), so it is clear but not fully exclusionary.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds essentially nothing behavioral beyond 'structured filters' — no note on superseded/expired handling, layer semantics, or result shape — even though the schema's include_superseded text shows there is non-trivial behavior worth surfacing.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity borders on under-specification for a tool with a nested options object and six-valued enum.

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

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

With annotations covering safety and a fully documented schema, nothing critical is missing to invoke the tool, but for a layered retrieval tool surrounded by recall siblings the description leaves the agent without routing or layer-semantics context. Adequate, not complete.

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

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

Schema description coverage is 100%, including detailed enum, filter, ordering, and include_superseded semantics, so the schema does the heavy lifting and the baseline is 3. The description adds no extra parameter meaning beyond what the schema already documents.

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

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

States a specific verb (query), a specific resource (a memory layer), and the mechanism (structured filters), which is much clearer than a restated title. However, it does nothing to distinguish itself from the many sibling recall tools (recall, semantic_recall, corpus_recall), so an agent cannot tell from the description alone which one to pick for a layered/filtered query.

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

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

There is no explicit when-to-use guidance, no mention of alternatives, and no conditions that select this tool over the recall-family siblings. The phrase 'structured filters' weakly implies the use case (filter-driven retrieval), but nothing tells the agent when filtering is preferred over semantic recall.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond them: it discloses that reads span two collections (live store + legacy archive June 2025–June 2026), that nothing is migrated between them, and that each result carries a `source` field naming its origin.

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

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

Purpose is front-loaded in the first clause, followed by provenance detail and the usage trigger. Four sentences that each carry information; only the 'second tier, word for word' phrasing is slightly cryptic, but it earns its place by contrasting with the compressed layer.

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

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

With no output schema, the description usefully explains the return shape (sessions grouped, each carrying `source`) and the two backing stores. Annotations handle safety; parameters are fully covered by the schema. Adequate for a read-only query tool, though it could note ordering or pagination behavior.

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

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

Schema description coverage is 100%, so all four parameters (limit, session_id, timestamp_start/end) are already documented in the schema. The description adds no syntax or filtering nuance beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Retrieve session transcripts') and clarifies it reads both the live store and the legacy archive. This distinguishes it from query_layer/recall by framing it as the 'second tier' depth source, though the tier jargon is not self-evident without sibling context.

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

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

Gives a concrete when-to-use condition ('when a layer entry is relevant but thin: the transcript around its timestamp holds the depth the layer compressed out'), implicitly positioning it against query_layer. No explicit exclusions or negative guidance, but the selection condition is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavior beyond them: paging rules, refusal-and-restart semantics when a document changes between pages, and the guarantee that `sha256`/`size` describe the whole document rather than the page. These are exactly the traits an agent needs to avoid joining pages of two versions.

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

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

Front-loads the core action, then layers paging, pinning, and invariants in dense sentences with no filler. Every sentence carries operational information an agent must act on.

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

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

No output schema exists, so the description must describe return values, and it does: `page` with `next_offset`, `version`, `sha256`, `size`, and `size_bytes`. Combined with the paging protocol, an agent can call and consume the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: `expected_version` must be the first page's version, and `expected_sha256` is the same pin and the only pin for shipped guides. That interaction logic goes beyond per-field schema text.

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

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

States a specific verb and resource ('Read a continuity document from the versioned document store'), which clearly separates it from write_doc, list_docs, and read_doc_history. The pagination framing further distinguishes it from sibling read tools.

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

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

Gives explicit operational guidance: call again with `next_offset` until it is null, pin `expected_version` to the first page's version, and do not act on a partial document. It does not, however, say when to prefer this over siblings like corpus_recall, semantic_recall, or read_doc_history, so routing among read tools is left to inference.

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

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

Annotations already cover read-only, idempotent, and non-destructive, yet the description adds substantial context: every write archives the prior copy, nothing is deleted, and a returned revision is re-hashed against its stored digest. This is genuine behavioral disclosure beyond the structured hints.

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

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

Front-loaded with the core action, then the archive rationale, then the two parameter behaviors and use cases. Information-dense, though the middle clauses are slightly long and could be trimmed without losing meaning.

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

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

With no output schema, the description carries the return-value burden and does so: it describes both the list form (digests and dates) and the single-revision form (full content, re-hashed). Combined with the archive semantics, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds return-shape meaning per parameter value: omitting version yields the list of revisions with digests and dates, supplying version yields that revision's full re-hashed content. That is more than the schema's terse per-field notes.

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

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

States a specific verb (read/list) plus resource (retained revision) and scope ('Every write archives the prior copy... this is the reader for that archive'), clearly separating it from the sibling read_doc which reads the current copy. An agent can distinguish it 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.

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

Explicit use cases are given: 'audit question - what did this document say at version N' and 'compare a document with what it replaced.' This is clear context for when to reach for it. It does not name read_doc explicitly as the alternative for current content, so it stops short of a full when/when-not statement.

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

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

Annotations already declare the full safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the description is not the primary carrier of behavior here. It adds some value by disclosing the retrieval mechanism (keyword matching) and cross-layer scope, but says nothing about result volume, ordering, or pagination behavior.

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

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

A single short sentence with no filler, and the core verb and scope are front-loaded. Nothing in it is wasted.

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

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

For a simple three-parameter read tool with no output schema and safety fully covered by annotations, the description is minimally sufficient. It falls short on the one thing that actually matters in this crowded sibling set: telling the agent when to pick recall over query_layer, semantic_recall, or corpus_recall.

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

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

Schema description coverage is 100%, so all three parameters (query, layer enum, limit) are already documented, and the baseline is 3. The description adds only marginal meaning beyond the schema – 'by keyword' hints at matching semantics and 'across layers' corresponds to the layer filter, but no format or syntax detail is added.

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

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

The description states a clear verb+resource ('search and retrieve memories') plus the mechanism ('by keyword', 'across layers'), so the basic purpose is legible. However, the sibling set contains several closely overlapping retrieval tools (corpus_recall, query_layer, semantic_recall), and the description offers no differentiation between them, leaving an agent unable to tell which retriever applies.

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

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

There is no when-to-use guidance and no mention of alternatives, despite obvious candidates such as query_layer and semantic_recall. The only implicit signal is that the tool is keyword-based, which the agent must infer as a routing criterion on its own.

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

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

Far exceeds the annotations: it specifies the write ordering (destination written first, then retire_doc), that NOTHING IS DELETED, that the old id stays readable and is flagged retired with a reason, that it is hidden from list_docs, and the merge-refusal rule. The destructiveHint=false annotation is corroborated and richly explained rather than merely restated.

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

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

Front-loads the core action and ordering before elaborating on the retire semantics and refusal rule; every sentence carries information. It runs slightly long, and the tombstone sentence is somewhat redundant with the preceding NOTHING IS DELETED clause.

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

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

With no output schema, the description covers the mutation's effects, ordering, and refusal behavior thoroughly for a 7-parameter write tool. It leaves the source/exchange/session_id write-path parameters to the schema, which is reasonable given their full descriptions there.

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

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 seven parameters. The description reinforces new_id/old_id semantics (destination must not exist; old id is retired, not removed) but adds no syntax or format detail beyond the schema, which is the expected baseline.

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

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

States a precise verb+resource ('Reissue a continuity document under a new doc_id') and immediately frames it against the related retire_doc operation. An agent can distinguish it from write_doc, retire_doc, and patch_doc 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.

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

Explains the operational context clearly (reissue an existing doc under a new id) and names an explicit refusal condition (destination already exists, because that would be a merge decision). It does not spell out when to prefer this over, say, patch_doc or write_doc, but the context is unambiguous.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known. The description adds real context beyond that: the retained row goes through the normal write path and no rows are deleted, which usefully qualifies what 'destructive' means here. It still doesn't state permission requirements or failure behavior beyond what the schema carries.

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

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

Three short sentences, front-loaded with the action, and the clarifying 'Nothing is deleted' earns its place by tempering the destructive hint. No filler.

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

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

For a mutation tool with annotations and a fully documented six-parameter schema, the description covers the essential mechanism. It lacks any note on permissions, partial-failure behavior, or what the caller gets back, but with no output schema and rich annotations those gaps are minor.

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

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

Schema description coverage is 100%, so every parameter (including the source-tag allowlist and exchange ordering rule) is already documented in the schema. The description alludes to 'a reason' and 'retained revision' but adds no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: writing a retained revision back as the current document. An agent understands the operation immediately, but the description never distinguishes it from siblings like patch_doc, write_doc, or read_doc_history.

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

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

Usage is implied by the mechanics described (restoring a retained revision), but there is no explicit when-to-use guidance, no exclusions, and no mention of the sibling tools that also write document content. The agent must infer that this is the revert path rather than a normal write.

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

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

Annotations already declare destructiveHint=false and idempotentHint=true, but the description goes far beyond them: it states nothing is deleted, the id/content/version/digest are retained, read_doc still returns it flagged retired, and list_docs hides it unless include_retired is true. It also discloses reversibility via write_doc and that the store has no delete by design.

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

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

Front-loaded with the core action, and each sentence carries information (retention, visibility, reversibility). The ISO 7.5.3 exposition and the revise_memory analogy are slightly discursive but still earn their place by anchoring intent.

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

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

For a non-destructive mutation with annotations covering the safety profile, the description supplies everything an agent needs: what changes, what is preserved, effect on list_docs and startup scans, and how to undo it. No output schema is needed since the visibility behavior is fully explained.

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

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

Schema description coverage is 100%, so every parameter including doc_id, reason, source, exchange and retired_by is already documented in the schema. The description adds no format or syntax detail about parameters, so the baseline 3 for a fully-covered schema applies.

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

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

States a precise verb+resource ("Mark a continuity document OBSOLETE") and immediately scopes what that means versus deletion. It distinguishes itself from siblings by naming read_doc, list_docs, write_doc and revise_memory and describing how each relates to a retired document.

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

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

"Use for genuine litter: tombstones, merged staging documents, test scratch" gives clear positive guidance, and the revise_memory comparison situates it among alternatives. It stops short of explicit when-not-to-use exclusions beyond the implicit "not for live documents," so it falls just shy of a 5.

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

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

No annotation contradiction: destructiveHint=false is actively supported by the disclosure that superseded entries still surface in recall/query_layer/semantic_recall marked with superseded_by and is_superseded, while idempotentHint=false aligns with each revision minting a new id. The description goes well beyond the annotations by disclosing the exact write mechanics (new entry carrying metadata.supersedes, target marked metadata.superseded_by), the read-visibility consequence, and the immutability constraint on episodic.

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

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

Front-loaded with the core semantics in the first sentence, then layers in write mechanics, read visibility, and the prohibition in tight, non-redundant sentences. Every sentence carries distinct information an agent needs.

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

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

For a six-parameter, non-idempotent write with no output schema, the description is complete: it explains the effective outcome (a new id plus a superseded target), how superseded content remains visible to readers, and the immutability carve-out. Nothing an agent needs to invoke this safely is missing.

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

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

Schema description coverage is 100%, and the schema already documents layer, content, exchange, metadata, target_id and session_id in detail (including the session-graph refusal behavior). The description adds the constraint 'episodic is prohibited' echoed from the schema, but contributes no additional syntax or format meaning to the parameters, so the baseline 3 applies.

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

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

The description opens with a specific verb+resource and immediately disambiguates the operation: 'Supersede an existing entry with a revised one (supersession, not mutation).' It distinguishes this from mutation-style updates and from creation by naming the mechanics (new entry + metadata.supersedes), so an agent can tell it apart from save_to_layer or patch-style siblings 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.

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

It clearly states the condition for use (revising an existing entry rather than creating one) and an explicit exclusion ('Episodic revision is prohibited - events are immutable'), plus the read-side alternative (query_layer options.include_superseded=false for the live-only view). It stops short of explicitly naming the sibling to use for a fresh write (e.g., save_to_layer), so this is clear context rather than full when/when-not/alternatives routing.

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

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

Annotations declare non-read-only, non-destructive, non-idempotent, and the description explains why: nothing is edited or deleted, a new document is written and the parent marked superseded. It adds behavioral facts beyond the annotations, including the mandatory reason ('an unexplained correction is a silent rewrite') and the closed-session exchange-number rules. No contradiction with the annotations.

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

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

Dense but well front-loaded: the mechanism comes first, then when-to-use, then the closed-session caveat. Each sentence carries distinct information, though the final clause is long and could be split for readability.

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

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

For an 8-parameter mutation tool with no output schema, the description covers replacement semantics, the required audit reason, sibling routing, and edge-case behavior on closed sessions. An agent has everything needed to invoke it correctly; return values are not its burden.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by requiring the reason and explaining the closed-session constraint that exchanges must match exactly and text numbers are stored as numbers. It does not add syntax detail for source/channel/session_start/session_end beyond the schema, keeping it at 4 rather than 5.

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

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

States the specific verb and resource ('Supersede a stored transcript part with a corrected one') and immediately clarifies the mechanism (new document, incremented revision, parent superseded). It distinguishes itself from the sibling save_transcript by contrast. An agent can identify the operation 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.

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

Explicitly names the trigger ('when a saved part has a mispaired, missing or wrong exchange') and the alternative ('To ADD a new part, use save_transcript instead'). It further qualifies usage on a closed session with concrete constraints, leaving nothing to inference.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds substantial behavior beyond that: the server stamps derived_from with the in-progress exchange, semantic/procedural entries are REFUSED without a source, and nothing is written when refused. That refusal atomicity is exactly the kind of consequence an agent must know before calling.

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

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

The purpose is front-loaded in the first clause, followed by the critical session_id directive and the refusal consequence. Three dense sentences, all earning their place, though the emphasis-shift to the refusal rule makes it slightly less cleanly ordered.

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

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

For a mutation tool with no output schema but full annotation coverage, the description supplies the key behavioral facts an agent needs: source requirement, refusal semantics, and derived_from stamping. Remaining gaps (return shape, interaction with revise_memory) are minor given the annotations and detailed schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a bump by tying session_id to a concrete outcome (derived_from is stamped) and to the refusal rule, reinforcing the interaction between session_id and metadata.derived_from. It does not add format detail beyond the already-rich schema.

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

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

States a specific verb and resource ('save memory to a specific layer') with an explicit scope ('full control over metadata'), which is clearly distinct from siblings like save_transcript or revise_memory. It does not name an alternative directly, so it lands at a strong 4 rather than a 5.

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

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

Gives an explicit operational rule: pass session_id on every save made inside a session, and semantic/procedural entries are refused without a source. This is clear usage context, but it never contrasts with sibling tools or states when to prefer this over revise_memory, so it stops short of 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the tool is a non-preferred fallback, it accepts two distinct input modes, and it is refused for a session closed as complete — a failure mode the annotations do not convey.

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

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

Four dense sentences with the fallback status front-loaded and no filler; every clause carries routing, mode or refusal information. It is packed tightly rather than bloated, though the compression makes it slightly telegraphic.

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

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

Covers the key call decisions for an 8-parameter, 2-required, non-idempotent write: when to use it, which parameter family matches which host, and a refusal condition. It does not describe what a successful write returns, but no output schema exists and the primary selection/invocation needs are met.

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

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 exceeds it by mapping parameters to operating modes ('Pass exchanges (chat hosts) or jsonl_path (CLI)'), which tells the agent which grouping of parameters applies to its host before it reads the schema.

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

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

States a concrete verb+resource ('Saves the full word-for-word dialog of a session') and immediately bounds the scope ('full transcripts only, no summaries'). It also distinguishes itself from the sibling emet_transcript_append by naming it as the primary path this tool falls back from.

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

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

Front-loads 'FALLBACK' and spells out the preferred alternative (emet_session_open + emet_transcript_append after every reply) and the exact conditions that select this tool instead (host cannot append per reply, or loading a CLI JSONL session). It also names a when-not case: refused for a session already closed complete.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real value beyond them by disclosing the retrieval mechanism (vector search, server-side autoEmbed) and scope (all six layers), which explains result behavior. It does not describe ranking or result shape, but annotations and the limit param carry much of that burden.

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

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

Three tight sentences, front-loaded with the core purpose and mechanism, with no filler. The final sentence routing to keyword-based siblings is efficiently placed at the end, though the phrasing could be marginally tighter.

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

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

For a read-only search tool with full annotation coverage, a fully documented schema, and no output schema, the description supplies enough: what it does, how it differs from keyword search, and the embedding mechanism. Return format and pagination with limit are not covered, but that is a minor gap given the structured data available.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces that search spans all six layers, implicitly mapping to the layer enum's default, but adds no syntax or format detail beyond the schema's own per-parameter descriptions (including the voyage-4 embedding note).

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

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

States a specific verb (semantic search) and resource (memories across six layers), and names the mechanism (Atlas Vector Search autoEmbed) plus the distinguishing property (finds conceptually related memories without keyword overlap). It explicitly contrasts itself with the keyword-based siblings recall/query_layer, so an agent can differentiate 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.

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

The description names the alternatives (keyword-based recall/query_layer) and states the condition that selects this tool (when there is no keyword overlap but conceptual relation is expected). It stops short of explicit when-not/exclusion phrasing, but the routing signal is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial behavior: no writes occur, the previous revision is pulled from the archive so the carry-forward check runs, and the check scope is bounded to FORM and CONTINUITY. It additionally discloses what the tool cannot do (verify truth or honest scope of a 'none'), which is exactly the kind of limit an agent needs.

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

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

Front-loaded with the purpose and the no-write guarantee, then use cases, then parameter behavior, then scope limits. Dense and mostly waste-free, though the middle sentence packs three use cases and the boundary paragraph is long relative to the rest.

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

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

For a 3-optional-param, no-output-schema tool, the description is nearly sufficient: it explains inputs, the archive comparison, and the check's boundaries. It does not describe the shape of the result (e.g., that a report/count of findings is returned), leaving the response format to inference.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: doc_id pulls the prior revision from the archive for carry-forward comparison, content requires template_id or a covered doc_id, and template_id is read from the shipped copy rather than the store copy. These interaction rules go beyond the field-level schema text.

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

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

Specific verb ('Check') plus resource ('controlled document against the template that governs it') and an explicit scoping qualifier ('WITHOUT writing anything'). It distinguishes itself from the write path it mirrors and from doc-mutating siblings, so an agent can identify it 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.

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

Enumerates three concrete use cases (auditing pre-validation records, counting adoption impact, pre-write checks of unstored content) and notes it is the freestanding counterpart of the write-path check, which implicitly routes agents away from write_doc/patch_doc. It lacks an explicit 'do not use this for X' exclusion or a named alternative tool.

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

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

Annotations only declare destructiveHint=true and idempotentHint=false; the description adds substantial behavioral detail beyond them - the prior copy is archived to documents_history and marked obsolete, the write is sha256 read-back verified, and record writes must carry supersedes pointing at the version in force. That is exactly the kind of consequence information an agent needs before a mutation.

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

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

Purpose is front-loaded in the first clause, followed by behavioral guarantees and the record rule. The parentheticals (documents_history, sha256, ISO references) are dense but each carries real information; the single long sentence is slightly heavy but not padded.

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

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

For a mutation tool with annotations present and no output schema, the description covers the versioning, archival and record-supersession workflow well. Remaining gaps (reason minimum length, session_id floor semantics, exchange ordering) are left to the schema, which is acceptable given 75% coverage.

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

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

Schema description coverage is 75% and the schema already documents reason, source, exchange, session_id and supersedes in detail. The description restates the supersedes requirement rather than adding format or syntax beyond the schema, so with the schema doing the heavy lifting this sits at the baseline 3.

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

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

States a specific verb (write or update) and resource (continuity document in the document store), and immediately distinguishes itself from patch_doc by naming the record case where patching is refused. An agent can tell it apart from read_doc, retire_doc, rename_doc and patch_doc without opening any schema.

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

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

It gives explicit routing for RECORDS: those are superseded, never amended, and patch_doc is refused on them, so write_doc is the required path. However, it never states the inverse condition for ordinary documents (i.e. when a small edit should go through patch_doc instead), so the alternative-usage guidance is one-sided rather than complete.

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