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 flag this as destructive and non-idempotent, and the description adds real context beyond them: the read-limited state of unapproved clients and the authorization constraint (only the owner or the EMET_COS_TAG chief-of-staff bot may decide). It does not explain consequences of a deny (e.g., whether the client is blocked permanently), which is the main remaining 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 action and resource, then state model, then authorization, then discovery. Four sentences that each carry information; the parenthetical definition of a client is slightly verbose but aids disambiguation.

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, non-idempotent mutation with no output schema, the description covers the state transition, the authority requirement, and where to find pending items. The main omission is the outcome/aftermath of a deny decision.

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 80%, so the schema already documents tag, as, from, reason, and decision with meaningful descriptions. The description adds no syntax or usage detail for these parameters beyond pointing at client_approvals.pending, so the 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?

States specific verbs (approve or deny) and a specific resource (a new client EMET flagged on first write), and defines what a 'client' is. This is clearly distinguishable from siblings like emet_invite_create or emet_member_access_create.

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 trigger context (clients pending after being flagged on first write) and points to emet_initialize/emet_status as where pending clients are listed. It doesn't explicitly name a sibling alternative to use instead, but the authorization condition and discovery path give clear when-to-use guidance.

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, idempotentHint, destructiveHint=false), so the bar is lower. The description still adds non-obvious context: the floor ships in server code so setup cannot overwrite it, and 're-reading is not the same as being bound by it' clarifies a semantic effect no annotation covers.

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 purpose before any caveats, and no sentence is filler. It is somewhat dense and long for a read-only getter, but each clause (immutability, initialize overlap, compact, gem, read-only framing) 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?

With no output schema, the description must convey what is returned, and it does: the whole floor, the compact short re-assertion, a single section, or one GEM's floor. It also explains how to discover valid section names (call with no arguments), leaving nothing important unstated for a 3-param, all-optional 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 coverage is 100%, so the baseline is 3 and the schema carries the syntax. The description nonetheless adds usage meaning for two parameters: compact is framed as the short form for late in a long session, and gem is framed as reading one GEM without enabling it. The section parameter is left to the schema, which documents it adequately.

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 the floor') and immediately defines the domain-specific noun as 'the standing description of how this assistant engages with the person using it.' It also distinguishes itself from the closest sibling by noting emet_initialize already returns the floor at session start and this re-reads it without re-running initialize.

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 alternatives and conditions: use this instead of re-running emet_initialize, use compact:true when 'the start of the conversation is far behind,' pass gem to read a specific GEM's floor. It also states a boundary ('reading does not turn that GEM on'), so the agent knows what this tool does not do.

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 idempotentHint=true and readOnlyHint=false; the description is consistent, explaining that a load_id and session state are produced (the non-read-only behavior) and that paged results are safe to re-request. It discloses the paged-startup loop, the new-store interview branch, and the authoritative 'character' voice, though pagination mechanics are also restated 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?

Front-loaded with the imperative 'START HERE' and organized as one dense but purposeful paragraph; every sentence carries information (ordering, paging, branch outcomes). Slightly long, 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?

No output schema exists, so the description must describe returns, and it does: interview for a new store, identity/voice/principal/last-state for an established one. It stops short of naming concrete return fields (e.g. startup_page), which are only discoverable in the load_id parameter text, leaving a small gap for a tool whose output is the whole point.

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 must be carried across pages and into emet_session_open, and frames 'source' as reporting the tag the agent's writes will carry. That is interpretive context beyond the 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 action (session initialization) with an imperative scope ('START HERE. Call this FIRST in every session') and explicitly distinguishes the setup role from other memory tools. An agent can tell at a glance that this is the entry point versus siblings like emet_session_open or 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?

Gives explicit conditions for invocation ('first in every session', 'before answering anything that might have prior context', plus trigger words like 'initialize', 'start', 'hello'), and coordinates with emet_session_open via the load_id parameter. The only missing element is a when-not-to-use clause, which the 'always first' framing makes largely moot.

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 mutation profile (readOnlyHint false, destructiveHint true, idempotentHint false). The description adds meaningful behavioral context beyond annotations: owner-only authorization, default read-only access, and that the code is one-time. It does not explain the destructiveHint or the return value, but the added auth and default-access details are valuable.

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?

Five short sentences, front-loaded with the tool name and core action. Each sentence carries distinct information: purpose, usage mechanics, access default, authorization rule, and sibling differentiation. There is no filler or repetition.

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 creation tool with no output schema, the description covers purpose, usage context, authorization, and alternative routing. However, it does not state what the tool returns (presumably the one-time code) or how expiration defaults work beyond the schema's 'days' parameter. These are minor gaps for an otherwise complete definition.

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 are already documented in the schema. The description reinforces that guest invites accept only 'emet.read', which maps to the scopes parameter, but adds no new syntax or format details. This is the baseline case where the schema does the heavy lifting.

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 specific verb and resource: 'create a one-time code for a guest'. It immediately scopes the tool to EMET Guest Access and explicitly distinguishes it from 'EMET Member Access', which is named as a different door. An agent can identify exactly what this tool does 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?

It provides clear usage context: guests paste the code on the connect screen instead of the passphrase, only the owner can create a guest code, and member access is a separate path. The alternative (EMET Member Access) is explicitly named and visually separated as 'a different door'. This leaves little ambiguity about when to use this tool versus its sibling.

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, idempotentHint=false and readOnlyHint=false, so the mutation profile is covered. The description adds real value beyond that: it is a one-time code granting read/write access, it never confers ownership, it is owner-only, and it is gated behind an environment flag.

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 sentence, and the follow-on sentences carry distinct, non-redundant information (connect-screen usage, non-ownership, owner-only, env gate). Slightly long at five sentences but each 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?

For a credential-creation tool with no output schema, the description covers who may invoke it, what it grants, and its activation prerequisite. It does not describe what is returned (the code itself) or how approval/expiry interacts, but annotations and schema carry most of the remaining load.

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 display_name, days and source. The description adds no syntax or format detail beyond the schema (only that the code is one-time and expiring), 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 (create) and resource (a one-time code for a new person with read/write access), and clarifies it is not Guest Access nor ownership. However it never distinguishes itself from the sibling emet_invite_create, leaving the agent to infer which credential-creation tool to pick.

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 preconditions: only the owner can create it, the recipient pastes it on the connect screen instead of the passphrase, and it is off unless EMET_MEMBER_ACCESS=1. It excludes Guest Access but does not explicitly compare against the sibling emet_invite_create.

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 declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, but the description goes further by disclosing the exact write-path sequence (connect, write, read back, remove) and why it matters ('a read alone cannot reveal a broken write path'). It still doesn't say what permissions the probe requires or whether it leaves residue on failure.

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 purpose and the tool-replacement note, then the probe semantics, then the routing hint. Slightly dense – the '(replaces ... 2026-09-27)' parenthetical is historical trivia – but every other 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 compensates by enumerating the reported sections, which is enough for an agent to know what to expect. It stops short of describing the response shape or pagination/format details, but for a diagnostic tool that 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains the probe's rationale (proving the write path) and that 'source' causes the report to echo the tag your writes will carry plus its approval state. That is more than the schema's terse 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?

The description states a specific verb+resource (diagnostic status of the store) and enumerates exactly what is reported: environment, database, collections, vector index, identity/user documents, per-layer counts and health. It also names the three tools it replaces, so an agent can confidently distinguish it from siblings like emet_setup_complete or emet_initialize.

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 explicitly routes the agent: 'Prefer emet_initialize for a normal session start,' and the probe flag is scoped to 'after a deploy or a configuration change.' Both the when and the when-not are stated, with the alternative 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?

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 the safety profile is covered; the description adds real behavioral context beyond that: results are metadata only, current documents sort first, retired documents are always present and annotated with retired_at plus rename lineage. It stops short of disclosing pagination or result-size 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?

Three compact sentences, front-loaded with purpose and the prefix example, then ordering and retired-document behavior. The parenthetical is dense but every clause carries information; 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 read-only list tool with no output schema, the description covers scope, ordering, and the retired/renamed edge cases an agent would otherwise be surprised by. Pagination and the shape of returned metadata are left unstated, which is the main remaining 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 only 50% and the 'prefix' parameter has no schema description, so the description's 'doc_id prefix filter, e.g. threads/' carries the load for that parameter. It also clarifies include_retired's semantics ('always listed... this flag does not hide them'), reinforcing the schema note rather than contradicting it.

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 ('List continuity documents') and narrows the scope with 'metadata only', which implicitly separates it from read_doc/read_doc_history. It never names a sibling tool explicitly, so it falls short of full differentiation.

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 implies enumeration use via the prefix filter and ordering rules, but never states when to choose this over read_doc, read_doc_history, or read_doc_history/restore_doc. No prerequisites, no exclusions, no named alternative.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds nothing beyond that: no mention of result ordering, superseded/expired entry handling, or pagination semantics — all of which are behavioral facts an agent should not have to dig out of 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?

A single front-loaded sentence with no wasted words. It is efficient, though its brevity shades into under-specification rather than crispness given the tool's complexity.

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?

The tool has a rich nested schema at full coverage, but no output schema and no sibling differentiation, so the agent lacks guidance on return shape and on choosing this over recall/semantic_recall. Adequate but with clear gaps for a query 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 the schema already documents layer, filters, ordering, history, and include_superseded thoroughly. The description adds no syntax or format detail beyond the schema, which is the expected baseline 3 when structured fields do the heavy lifting.

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 ('Query a specific memory layer') and adds scope ('with structured filters'), so the agent knows the operation. However, it does nothing to differentiate from closely related siblings such as recall, semantic_recall, or corpus_recall, which an agent must distinguish.

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?

No when-to-use guidance and no mention of alternatives, despite overlapping siblings (recall, semantic_recall, query_transcripts) that clearly invite confusion. The agent is left to infer that this tool is the layer-scoped filtered variant.

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 establish read-only, idempotent, non-destructive behavior, so the lower bar applies; the description still adds meaningful result-composition behavior: ranking is by word-match count then importance, current entries sort first in every order, and expired/superseded entries remain in results marked with their end date and replacement. It does not describe pagination beyond the limit, but that is minor against the annotation coverage.

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 core ('Search memories by keyword', ranking, ordering) is front-loaded, which is good. But the middle is dense and repetitive, dwelling on edge cases like hyphenated 'latest-budget' and 'not the latest', and restating the 'latest' reordering rule several times; those sentences do not clearly earn their place for an agent's decision-making.

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 appropriately carries the burden of describing what comes back: ranked matches, current-first ordering, and marked ended entries with end dates and replacements. Layer filtering and limit defaults are only covered by the schema, but the description covers the return semantics an agent needs.

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, and the description goes beyond the schema by explaining the special keyword semantics of 'order' and 'query' (bare/hyphenated/negated 'latest', standalone 'newest'/'most recent' reordering matches without changing the match set) and the interaction between history and the limit. This is genuine added meaning, though some of it restates the 'order' schema description almost verbatim.

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 ('Search memories by keyword') and even specifies the matching mechanism (keyword vs. presumably semantic siblings). It does not name any sibling such as semantic_recall or corpus_recall, so an agent must infer which search tool to pick, but the purpose itself is unambiguous.

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 trigger conditions for two parameters ('Pass order: latest for time order', 'Pass history: true to read ended entries when current ones fill the limit'), which is real usage guidance. However it offers no guidance on when to choose this tool over the many sibling search tools (semantic_recall, corpus_recall, query_layer), so selection is only implied.

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 say readOnlyHint=false and destructiveHint=false; the description goes well beyond them by stating nothing is deleted, the old id stays readable, it is flagged retired with reason 'Reissued as <new_id>', and list_docs shows replaced_by. It also discloses the refusal semantics on an occupied destination, which is behavior no structured field 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?

Front-loaded with the core action and mostly disciplined, but the 'No tombstone document is needed' sentence and the closing rationale about merges are discursive justification rather than call-critical instruction. Still, each sentence maps to a distinct behavior an agent should know.

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 7-parameter mutation tool with no output schema, it covers destructive-vs-retain semantics, ordering, refusal, and downstream list_docs effects well. What remains unstated is the response shape and whether the destination write is transactional if the retire step fails.

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 all seven parameters including old_id/new_id semantics and the exchange/session graph rule. The description reinforces old_id/new_id but adds no new syntax or format detail for the four context parameters (source, exchange, session_id, updated_by). 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 ('Reissue a continuity document under a new doc_id') and immediately distinguishes the operation from a plain rename or delete. It names the collaborating siblings (retire_doc, list_docs) so the agent can place it in the corpus 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?

Gives a clear when-not condition ('Refuses if the destination already exists') and explains the internal ordering (destination written first, then retire_doc marks the old id). It references sibling behavior but does not explicitly route to an alternative tool for the merge case, only saying merges are not guessed.

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 flag idempotentHint and destructiveHint=false, but the description goes far beyond: it enumerates exactly what is preserved (id, content, version, digest), how read_doc and list_docs surface the retired state (retired_at, replacement), and that the operation is reversible via write_doc on the same id. This is exactly the added context the bar asks for.

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 core action and its non-destructive nature are front-loaded, and most sentences carry real routing or behavioral information. The ISO 7.5.3 framing and 'a retired drop is not an unhandled drop' add flavor that is less essential, keeping it just below top marks.

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 compensates by describing the resulting state (flagged retired, retained in listings, reversible). Combined with annotations that align with the described behavior, an agent has everything needed to call this correctly and predict the outcome.

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 doc_id, reason, source, exchange, and the retired_by alias. The description only echoes the reason ('with the reason') without adding format or constraint 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?

States a specific verb (mark OBSOLETE) and resource (continuity document), and explicitly distinguishes itself from siblings: read_doc still returns it, list_docs keeps it, write_doc restores it, and revise_memory is named as the analogous layer operation. An agent can route to it 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?

Gives concrete when-to-use cases ('genuine litter: tombstones, merged staging documents, test scratch') and rules out the delete mental model with 'THE STORE HAS NO DELETE, BY DESIGN'. It stops short of explicitly contrasting against a near-alternative tool for the same state change, so it is strong context rather than full when/when-not 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?

Goes well beyond the annotations by disclosing the exact side effects: a NEW entry is created rather than the target being mutated, the target is marked with superseded_by/superseded_at, and crucially the old entry stays readable (not hidden, is_live not cleared). It also explains how recall/query_layer/semantic_recall surface the superseded entry, which is non-obvious behavior 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-loads the most decision-relevant fact (supersession, not mutation) and each following sentence carries distinct behavioral information. It is dense rather than padded, though the trailing sentence about ordering ('The current entry is listed first') sits slightly oddly at the end.

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-parameter, nested-object write tool with no output schema, the description covers the mutation model, the after-state of both entries, downstream read behavior, and the layer restriction. Nothing essential for correct invocation appears to be 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%, so the baseline is 3 and the schema already documents layer, content, exchange, metadata, target_id and session_id semantics. The description restates that metadata.supersedes is set automatically, which largely duplicates the schema text rather than adding format or value guidance.

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 ('Supersede an existing entry with a revised one') and immediately draws the key distinction 'supersession, not mutation', which separates it from the mutation-style siblings. It then specifies the concrete mechanism (new entry with metadata.supersedes=<target_id>, target marked with superseded_by/superseded_at).

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 clear negative constraint ('Episodic revision is prohibited - events are immutable') which routes the agent away from episodic-layer targets. However, it never explicitly contrasts with siblings like save_to_layer or revise_transcript, so the agent must infer when supersession is preferred over a plain 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 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 already establish non-readOnly, non-destructive and non-idempotent. The description adds genuinely new behavior: the server auto-stamps derived_from from the in-progress exchange, semantic/procedural writes are refused without a source, and nothing is written on refusal. It omits what a successful write returns, but for a write tool with no output schema this is solid added context.

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 sentences, purpose front-loaded before the operational caveats, with no filler. The all-caps emphasis (PASS, REFUSED) is slightly heavy but each sentence carries distinct, load-bearing 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 a 5-parameter, nested-object write tool this covers the main agent-facing risks: source attribution requirements, refusal behavior, and session stamping. Return values are undescribed and there is no output schema, but since the tool's observable outcome is whether the write succeeded or was refused, the description is effectively 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 coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining the runtime effect of session_id (reads the session counter and stamps derived_from) and its precedence over metadata.derived_from, plus the practical requirement that overrides the schema's optional-looking status.

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 (save) and resource (memory layer) plus the distinguishing capability of full metadata control. It separates itself from query/recall siblings but does not explicitly contrast with the closely-named save_transcript, leaving that distinction to be inferred.

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 that semantic/procedural saves are refused without a reachable source. This is strong when-to-use guidance, though it never names an alternative tool (e.g. save_transcript) or states when not to use this 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 the safety profile (non-read-only, non-destructive, non-idempotent), so the description carries real extra weight: it discloses that exchanges must be passed inline, that the server does not read a file, and that the call is refused for a session already closed complete. It does not address duplicate-write behavior despite idempotentHint=false, which is the one remaining 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-loads 'FALLBACK.' so the routing decision is the first thing read, and every clause carries a distinct constraint (primary path, per-reply alternative, inline payload, no file read, refusal condition). The dense second sentence is slightly packed but nothing is wasteful.

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-idempotent write with no output schema, the description covers the key operational facts: inline data, no server-side file read, whole-transcript requirement, and the closed-complete refusal. Only success/response behavior and duplicate-write handling are 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 description coverage is 100%, including ordering rules for exchange and naming/aliasing notes for source vs channel, so the schema does the heavy lifting. The description only adds the generic 'pass exchanges in the call' instruction, which is the baseline 3 for a fully documented 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+resource (saves a full word-for-word session transcript) and explicitly positions itself as the fallback against named siblings emet_session_open and emet_transcript_append. An agent can distinguish it from the primary append path 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?

Gives an explicit when-to-use condition ('use this only where a host cannot append per reply') plus the preferred alternative path, and adds an exclusion ('full transcripts only, no summaries'). Nothing about selection 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 carry the safety profile (readOnly, idempotent, closed-world, non-destructive), so the bar is lower. The description adds real context beyond them: the search is vector/embedding based, embedding happens server-side automatically, and results can be conceptually related without lexical overlap. It does not mention pagination or result scoring, but the substance added is meaningful.

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 that are front-loaded with the primary capability and end with the routing hint. Every clause carries information: what it does, how, and what it complements.

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 4-parameter, all-optional-but-one search tool with 100% schema coverage and a full annotation set, the description covers purpose and differentiation adequately. The only gap is return-shape detail, but the history parameter's schema text and the absence of an output schema make this a minor omission.

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% — every parameter including the layer enum, limit default, and the history semantics is documented in the schema itself. The description adds only the broad 'across all six memory layers' framing, which loosely relates to the layer parameter, so 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?

States a specific verb+resource ('Semantic memory search across all six memory layers') plus the mechanism (Atlas Vector Search autoEmbed) and the distinguishing property ('finds conceptually related memories even without keyword overlap'). It also names the siblings it is not — keyword-based recall/query_layer — so an agent can pick it apart from them without opening schemas.

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 frames itself as a complement to keyword-based recall/query_layer, which gives the agent a clear selection rule: use this for meaning-based matching, those for keyword matching. It stops short of spelling out an exclusion (e.g. when keyword search is strictly preferable) or cost/latency tradeoffs, so it is clear context rather than full when/when-not guidance.

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.