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

Annotations only declare the basic safety profile (not read-only, not destructive, not idempotent, closed-world). The description adds real behavioral context beyond that: writes are confined to DATACRON_WRITE_PATHS, history is content-addressed, writes are atomic, and human review comes via the MCP client's tool approval. It also pins down the exact placement semantics within the target section.

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 sentences, front-loaded with the selection condition, then the mechanics, then the behavioral 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?

An output schema exists so return values need no explanation, and the annotations plus the description's write-path, atomicity and approval notes make the mutation profile clear. The remaining gap is the two optional parameters, which neither the schema nor the description explains.

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 0% across 5 parameters, so the description must carry the load. It implies the roles of rel_path, heading and entry through the placement narrative, but leaves request_id and expected_hash completely unexplained, and given the mention of content-addressed history these are likely the idempotency/concurrency controls an agent needs to understand.

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 ('Append a Markdown entry ... in an existing memory note') and names the exact insertion point (after the heading's own content, before its first subsection). This is clearly distinguishable from create_note_ai and the patch_note_* siblings, which modify other parts of a note.

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

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

Explicitly says when to use it: 'when new information extends a topic that already has a note, instead of creating a duplicate.' That gives the selecting condition and rules out the duplicate-creation path, though it doesn't name create_note_ai directly or state 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?

The description adds that the operation is read-only and never changes the journal or vault, providing specificity beyond the readOnlyHint annotation. It does not disclose return behavior or error conditions, but the annotation already establishes safety.

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 short sentences deliver the essential purpose and safety guarantee without redundancy.

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 query tool with an output schema and annotations, the description covers purpose, filtering dimensions, and safety. It could mention the default limit or return format, but the output schema likely covers the latter.

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?

The description maps the start/end parameters to 'time range' and mentions tool and note filters, but does not describe the 'limit' parameter or value formats. With 0% schema coverage, this partially compensates but leaves some parameters underspecified.

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 clearly states the tool queries committed operation metadata with filters for time range, tool, or note. It distinguishes itself from sibling note/search tools by focusing on the audit log.

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 usage for reviewing audit metadata but does not explicitly state when to prefer this over alternatives. No exclusions or alternative tool references are provided.

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

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

With readOnlyHint/destructiveHint already declared, the description still adds substantial context: what summary vs full detail omits, that confirm returns an exact write-tool call, that the tool never writes even after elicitation/confirmation, and a prompt-injection warning about untrusted new_content. This is far beyond 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?

Four sentences, front-loaded with the when-to-use trigger, then mode behavior, then safety. Dense but every sentence 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?

An output schema exists, so return-shape explanation is unnecessary, and the description covers modes, detail levels, non-write guarantee, and untrusted-content handling. It assumes the reader knows what 'indexed sections' means and doesn't state any prerequisite, keeping it just short of 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 0%, so the description carries the burden: it explains scan vs confirm for 'mode', summary vs full for 'detail' ('summary detail omits redundant alternative previews while full detail retains them'), and that 'proposal_token' is the token produced by scan and validated by confirm. It doesn't mention defaults, which is why it isn't a 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 a specific verb and resource ('Scan live contradiction candidates', 'sections may conflict or refine one another') and describes both operating modes, making the tool's job unambiguous. It doesn't name any sibling to differentiate against, but the scan/confirm split and the read-only posture set it apart from the patch_* write 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?

'Use this when indexed sections may conflict or refine one another' gives a clear triggering condition, and the description implies the scan-then-confirm workflow ('confirm mode validates one token'). No explicit when-not or named alternative is given, so it stops short of a 5.

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

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

Annotations already declare the write/safety profile, yet the description adds substantial context: confinement to DATACRON_WRITE_PATHS, no overwriting of existing files, creation of a durable operation record, and reliance on client tool approval for human review. This is genuinely useful 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-loads the proactive-call guidance, then the note type, then the write semantics, so the most decision-relevant content comes first. It is dense and mostly waste-free, though the final sentence is a long multi-clause run-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?

An output schema exists, so return values need not be explained, and the write semantics and scope constraints are covered well. The gap is parameter documentation, which is largely absent given the 10-parameter, 0%-coverage schema, but behaviorally the definition is nearly complete.

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

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

Schema description coverage is 0% across 10 parameters, so the description carries the full burden. It only adds meaning for the 'rejected' parameter (the 'option -- reason' format); rel_path, title, body, origin, confidence, tags, supersedes, last_verified, and request_id are left entirely undocumented in both places.

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: 'Write a new typed _memory Markdown note,' which an agent can distinguish from search/get/patch siblings. It does not, however, explicitly name which sibling to use instead (e.g., append_journal) in adjacent scenarios, so it falls short of full sibling 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?

Gives explicit triggering conditions ('when a durable fact, confirmed decision, or user preference emerges') and clear exclusions ('skip speculation and one-off chatter'), plus a proactive-call directive. It stops short of naming alternative tools for the excluded cases, so it is strong but not a 5.

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

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

Annotations declare destructive/non-idempotent, but the description adds real behavioral context beyond them: CAS via expected_hash, atomic write, exact prior history retained, and the refusal of all level-1 headings. These are non-obvious safety semantics an agent must know before calling.

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

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

Front-loaded with the when-to-use rule and otherwise dense with no filler; each sentence adds a distinct fact. It is slightly cramped, packing CAS, refusal, and duplicate-title rules into one block, but nothing is redundant.

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, six-parameter tool with 0% schema coverage the description covers the risky, ambiguous parameters and the refusal semantics. Return values are handled by the existing output schema, so not explaining them is acceptable; only the trivial params are left implicit.

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 0%, so the description carries the full burden and does well on the hard cases: expected_hash as CAS, 1-based heading_occurrence combined with heading_level, and its document-order semantics for the hashed bytes. rel_path, heading, and request_id remain unexplained, but the two required params are self-evident by name.

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 ('remove') plus the exact resource ('H2-H6 Markdown section and all of its subordinate headings'), with scope that separates it from patch_note_section and rename_note_section. An agent can identify the operation and its blast radius 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 when to use ('only to remove an explicitly obsolete section') and names the alternative with its condition ('Prefer lifecycle invalidation with set_frontmatter when the fact must remain queryable'). It also gives a negative instruction ('Do not use chunk_id').

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral details: empty list for unresolved targets, truncation semantics with 'truncated=true', and the note that 'returned is not a count'. This goes beyond the annotations and helps the agent interpret results correctly.

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 description is compact and front-loaded with the primary use case, then covers resolution and truncation in a few dense sentences. Every sentence adds value; no filler or repetition of schema details.

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 an output schema, so return values are documented elsewhere. The description covers the key behavioral nuances: unresolved targets, truncation, and limit semantics. It lacks explicit mention of sorting or ordering of results, but given the output schema and annotations, this 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 0%, so the description must compensate. It explains the 'target' parameter's resolution semantics (ULID or alias via title -> filename -> aliases) and the 'limit' parameter's effect on truncation. However, it does not specify the exact format of the returned chunks or how 'truncated' is represented in the output, leaving some ambiguity.

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 clearly states the tool's purpose: find related context via backlinks, with a specific verb ('find') and resource ('chunks whose wikilinks point at the given target'). It distinguishes itself from siblings like search_text and get_note by focusing on wikilink-based relationships. The resolution order (title -> filename -> aliases) adds precision.

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 explains when to use it ('related context the user did not mention') and how the target is resolved, but it does not explicitly name alternative tools or state when not to use it. The context is clear enough for an agent to select it appropriately, but explicit exclusions are missing.

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/destructive flags, but the description adds substantial context: closed records hidden by default with history preserved, legacy prose not parsed, source freshness not revalidated, and an explicit injection-safety warning that summary/source_excerpt/identity_basis are stored data. It also warns that absence is not proof no commitments exist.

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 read purpose, then behavior and pagination notes. Dense but each sentence carries real signal. Some sentences pack multiple ideas (data-safety warning plus get_note routing) that could be split, but nothing 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?

Given an output schema exists, return values need not be explained, and the description covers what is missing elsewhere: pagination integrity, hidden-record defaults, freshness caveats, and injection safety. For a 4-param read tool with zero schema descriptions, this is complete enough to call 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 0%, so the description must carry the burden, and it does: next_offset for offset, keep note_paths/include_closed unchanged during pagination, expected_snapshot tied to snapshot_hash, and restart at offset 0. It never names the parameters literally, but the semantics of all four are conveyed well enough to invoke correctly.

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 first sentence names a specific verb ('Read') and resource ('structured follow-up revisions in explicit canonical notes'), and the definition explicitly routes legacy content to get_note. It is clearly differentiable from siblings like get_note, though the phrasing ('canonical notes', 'identity_basis') is somewhat jargon-heavy.

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 names get_note as the alternative for legacy notes and original evidence, and gives concrete continuation rules (next_offset, expected_snapshot=snapshot_hash, restart at offset 0 on source change). It states default hiding of closed records. No explicit when-not guidance beyond the get_note split, so not a full 5.

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

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

Annotations already declare readOnly/destructive/openWorld behavior, but the description adds substantial non-obvious context: limit capping against settings.max_result_count with <=0 meaning the server ceiling, fingerprint opacity, which path fields remain addressable, and that findings omit line numbers. This goes well beyond the annotations without contradicting them.

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 dense sentences with the purpose front-loaded and no filler, but the fingerprint/path-sanitization sentences are quite niche for a selection-time reader and could be trimmed or moved to docs.

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 an output schema present, return values need not be re-explained, and the description covers parameters, mode behavior, and data sanitization nuances. It is complete enough for correct invocation, with only minor gaps around summary-mode semantics.

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 0%, so the description must carry the load and largely does: it defines detail='full' and explains that in full mode limit<=0 selects the server ceiling while positive values are capped. It does not clarify limit's behavior in summary mode, a small remaining gap.

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

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

The description gives a specific verb ('Return') and expands 'health' into five concrete dimensions (index freshness, vault integrity, checksum, durability, invariants), so the agent knows exactly what the tool surfaces. It does not explicitly distinguish itself from siblings like audit_query or contradiction_scan, but the enumerated scope is unusually precise.

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

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

It states 'Use detail="full" to include bounded integrity findings,' which is real conditional guidance for one mode, but it offers no when-to-use vs. alternatives framing against siblings such as audit_query. Usage is implied rather than fully specified.

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 (readOnly, non-destructive), while the description adds substantial behavioral detail the schema cannot convey: stale-chunk errors on parent-hash mismatch, chunk reads ignoring offset/limit, per-format pagination semantics, reading next_offset until null with an unchanged content_hash, metadata_truncated flagging, and the DATACRON_MAX_READ_RESPONSE_CHARS cap. This is exactly the kind of context that goes beyond structured fields.

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 motivation and identity of the tool, then progresses through format-specific behavior. Every sentence carries real information, though the dense single-block prose around format/offset semantics could be easier to scan if slightly more segmented.

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 read tool with an output schema, the description covers identifier kinds, all format modes, pagination, error conditions, and section-read requirements, so nothing an agent needs to invoke it correctly is missing. Return-shape details are partly covered by the output schema, so the extra envelope notes are additive rather than redundant.

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 0%, so the description must carry all parameter meaning, and it does: it defines all four format enum values with their distinct return and pagination behavior, explains id_or_path's three accepted identifier kinds, and clarifies offset/limit semantics per format (character range, heading count, character count) plus 1-based heading_occurrence for repeated paths.

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 ('Fetch a single note by its ULID, indexed chunk_id, or vault-relative path') and immediately distinguishes itself from the search siblings by framing itself as the follow-up to a search hit. An agent can tell this apart from search_text, list_notes, and get_note_history 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?

The opening sentence gives clear context ('before answering from a snippet alone'), effectively telling the agent to use this after a search. However, no explicit alternatives or 'when not to use' conditions are named (e.g., vs get_backlinks or get_note_history), so it stops short of full routing 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 assert read-only and non-destructive, and the description reinforces this while adding the retention distinction between restore_available and history_stored, which is not visible in the schema. This helps agents avoid wrongly assuming a restore is always possible.

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 dense sentences carry the core action, scope, and a nuanced caveat without padding. The first sentence leads with a secondary use case rather than the main listing behavior, but it is still economical.

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?

Combined with the output schema and read-only annotations, the description covers the essential decision logic, including when a restore is possible, and routes to revert_note. Minor undefined terminology ('ordinary-write receipt') and lack of limit semantics keep it from being fully 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?

The request_id parameter gets real semantics (filter to a single write receipt) and the response field restore_available is explained. However, note and limit are left to their bare schema names, which is a gap given 0% schema description coverage.

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 action ('List committed operation metadata for one note') and explicitly scopes what it does not do ('without reading history content or modifying the journal'), separating it from get_note and write/restore tools. The phrase 'ordinary-write receipt' is domain-specific, but the main purpose remains 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 specifies the request_id path for retrieving a write receipt and tells the agent that restore_available determines whether before_hash can be passed to revert_note. It does not explicitly enumerate sibling alternatives, but the conditional guidance is concrete and actionable.

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?

Beyond the readOnlyHint and destructiveHint annotations, the description explicitly discloses 'Never writes or retries' and the important nuance that missing receipts do not prove the absence of pending writes. It also reveals the return content ('per-request receipt, current-byte and index evidence with next actions'), which is valuable context not present in 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?

The description is five compact sentences with no filler. It front-loads the purpose, then covers optional parameters, return evidence, safety behavior, and a critical caveat—all without redundancy.

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 single-parameter tool with an output schema and read-only annotations, the description covers the essential context: what the tool checks, when to use it, what inputs matter, what it returns, what it never does, and an important interpretation caveat. An agent has enough to call it correctly without additional 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?

The parameter-level schema coverage is reported as 0%, so the description carries the burden of explaining the requests parameter. It clarifies that requests are retained note/request_id references and explains the optional expected_hash's purpose ('to detect conflicts'), though it does not detail the request_id format or note path constraints beyond what the nested schema already says.

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 ('Check') and resource ('retained note/request_id references after a partial multi-note update'), which is clear and not tautological. It does not explicitly name a sibling tool as an alternative, but the write-progress focus and 'Never writes or retries' help distinguish it from write-oriented and history-oriented siblings.

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 gives clear context for when to use the tool: after a partial multi-note update, with optional expected_hash to detect conflicts. It does not explicitly state when not to use it or name alternatives, but the behavioral caveat 'Missing receipts do not prove no pending write exists' is a useful precaution.

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 the safety profile (readOnly, non-destructive, closed-world), so the bar is lower, and the description still adds real behavior: offset/limit pagination and the stable ULID identity of entries. It does not mention sort order or total counts, which matters for a paging tool.

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

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

Three tight sentences, front-loaded with the discovery use case before mechanics. Minor overlap between 'optionally scoped to a subfolder and/or filtered by tags or top-level frontmatter' and the parameter list, but no padding.

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?

An output schema exists so return values need not be documented, yet the description still summarizes entry fields, and it covers filtering and paging. It is essentially complete; only pagination ordering/total-count behavior is absent.

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 0%, so the description must carry the parameters, and it does: it explains folder scoping, tag filtering, frontmatter matching with a concrete example, and offset/limit paging. The limit default of 20 and the tags AND/OR semantics are left unstated, keeping it out of 5 territory.

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 ('Return ... list of notes in the vault') plus the scope mechanism (subfolder, tags, frontmatter). The opening line positions it relative to deeper reads, which distinguishes it from get_note/search_text siblings.

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

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

'Use this to discover vault structure before deeper reads' gives a clear when-to-use context and implies the alternative (targeted reads). It does not name search_text/search_regex explicitly or state when-not to use this listing, so it stops short of a 5.

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

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

Annotations only declare the basic safety profile (not read-only, destructive, non-idempotent, closed-world). The description adds considerable context beyond that: dry-run vs commit semantics, durable history and index reconciliation on commit, byte-level preservation including frontmatter, refusal of mixed EOLs/unsafe boundaries/invalid child hierarchy, and the request_id replay mechanism. This is exactly the behavioral detail annotations cannot carry.

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 and mode switch are front-loaded, and each sentence carries distinct operational information (mode, preconditions, refusals, selectors, disambiguation). It is dense and long, but for a destructive 10-parameter tool almost every clause earns its place; only minor tightening is possible.

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?

An output schema exists so return values need not be restated, yet the description still tells the agent what the dry-run returns (selection coordinates, before/projected hashes). Combined with precondition handling, refusal cases, and duplicate-heading disambiguation, it gives an agent everything needed to invoke this complex mutation 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 description coverage is 0% across 10 parameters, so the description must compensate, and it does for most: confirm (default false preview vs true commit), expected_hash (required), request_id (stable, for durable replay receipts), and the level/occurrence pairs (duplicate titles require the respective level and 1-based occurrence). rel_path is left self-evident and the level/occurrence tie-in could be stated more directly, so not quite a 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 a specific verb+resource and scope: an exact single-note H2-H6 subtree move to an existing heading's final child position. The scope qualifiers (single-note, no releveling, H2-H6) let an agent distinguish this from rename_note_section, delete_note_section, and patch_note_section 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?

Opens with 'Use this to preview...' and clearly separates the two modes (confirm=false returns coordinates/hashes without writing; confirm=true commits). Preconditions are explicit (both headings must exist, expected_hash required, no releveling). It does not explicitly name sibling alternatives to route against, so it stops short of 5.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds substantial context beyond them: CAS via expected_hash, empty new_content removing the preamble, byte preservation under uniform line endings, dominant-EOL normalization for mixed files, and fail-closed refusal for missing headings or unbalanced code fences/HTML blocks.

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 usage statement, then layers edge-case behavior in a tight sequence. Dense with mechanical detail but nearly every clause conveys a distinct constraint (CAS, removal semantics, EOL handling, refusal conditions), with little redundancy.

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?

Output schema exists, so return-value explanation is unnecessary, and annotations cover safety. For a destructive, non-idempotent mutation the description supplies the missing pieces an agent needs: concurrency control, failure modes, and byte/EOL preservation guarantees.

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 0%, so the description carries the burden: it explains new_content semantics (empty/whitespace removes the preamble) and expected_hash's CAS role. However, rel_path and request_id are left undocumented, so the compensation is partial.

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 (replace or remove) and a precisely scoped resource (content strictly before the first recognized Markdown heading). It clearly distinguishes itself from the sibling patch_note_section by scoping to the preamble, so an agent can tell them apart 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?

Opens with an explicit use case ('Use this to replace or remove content strictly before the first Markdown heading...') and the selector scope makes it clear when this applies versus the section siblings. It does not explicitly name an alternative tool or a when-not condition, so it falls short of a 5.

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

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

Goes well beyond the destructiveHint/idempotentHint annotations: it discloses atomic writes, exact prior-history storage, preservation of the heading line and non-target sections, and enumerated refusal conditions with error codes (section_has_subsections, section_structure_changed, open code fence/HTML block). This is exactly the behavioral detail an agent needs before a destructive in-place rewrite.

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 in the first sentence, then layers constraints. Every sentence carries information, but the duplicate-title and refusal clauses form a dense wall that could be split for scannability.

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 destructive mutation with an output schema present (so return values need not be explained), the description covers concurrency control, atomicity, failure modes and duplicate-title disambiguation. Nothing critical for a correct call 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 0%, so the description must carry the load, and it explains the non-obvious parameters well: expected_hash as CAS, heading_occurrence as 1-based document-order ordinal for duplicate titles alongside heading_level, and an explicit negative for chunk_id. It does not describe rel_path, new_content or request_id, so coverage is strong but not complete.

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 scope: rewrite an existing section in place under one Markdown heading, only when the topic already has a note. This clearly separates it from rename_note_section, delete_note_section, move_note_section and patch_note_preamble in the sibling list.

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

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

Explicitly says when to use it (outdated section, note already exists) and when not: sections containing subsections must be patched at the subsection level or deleted first, and it warns 'Do not use chunk_id.' It routes the agent to the correct alternative behavior in the failure cases.

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 readOnlyHint=true/destructiveHint=false, and the description reinforces this ('never writes', 'Validation is structural, not a truth verdict') while adding rich context: bounded plans, explicit refusal cases, and redaction behavior that names the offending field without examining the rest of the note.

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 purpose and the never-writes scope, then refusals, then constraints. The schema restatement is lengthy, but it is explicitly justified ('repeated because some clients strip them') and thus defensible rather than padding.

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 an output schema present for return values, the description supplies everything else an agent needs: refusal rules, redaction semantics, identity-confirmation gating, batching limit, and the follow-on writer workflow. Nothing material 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 0% and the nested FollowUpRecord has no per-field docs, so the description carries the full burden — and it does, restating required fields, patterns, enums, defaults, and the 20-record runtime cap. This compensates completely for the coverage gap.

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

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

State a specific verb+resource: validates sourced actions/interactions/objectives/state revisions against live note IDs/hashes and excerpts, returning bounded plans rather than writing. This clearly distinguishes it from the sibling writer append_journal and from get_follow_up.

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?

Tells the agent exactly how to sequence: 'Use stable record/revision IDs, then apply with existing writers and verify receipts.' It also enumerates refusal conditions and the identity-confirmation requirement for person targets, so when-to-use and when-not-to-use are 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 declare destructive=true and idempotent=false, but the description adds substantial context beyond them: CAS via expected_hash, H1 refusal, collision refusal through the same AST selector, ATX/Setext support with fenced-code exclusion, and duplicate-title ordinal resolution. This is unusually rich behavioral disclosure for a mutation tool.

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 scope sentence and dense but largely non-redundant detail after it. Sentences are long and pack several constraints each, but for a 7-parameter CAS-guarded mutation tool the length is justified.

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 an output schema present, return values need no explanation, and the description covers refusals, CAS, markdown dialect handling, and duplicate resolution. Missing coverage of rel_path and request_id slightly weakens completeness for a 7-parameter tool.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it does for expected_hash (CAS semantics), heading_level, and heading_occurrence (1-based, document order over hashed bytes). It leaves rel_path, request_id, and heading itself unexplained, so it does not fully close the coverage gap.

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

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

States a specific verb (rename), resource (H2-H6 Markdown section title), and scope limits, which cleanly separates it from siblings like move_note_section, delete_note_section, and patch_note_section. 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?

"Use this only to rename..." plus explicit refusals (H1, collisions, chunk_id) give clear when-to-use and when-not boundaries. It stops short of naming a sibling alternative for the H1/frontmatter-title case, so it is strong but not fully routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that: the revert is 'durable, reversible, indexed, and operation-logged,' and it explains the CAS precondition. No contradiction with destructiveHint=true, since overwriting current bytes is itself destructive.

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

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

Four short sentences, front-loaded with the purpose before the CAS mechanics and behavioral traits. Slight redundancy between the first two sentences ('restoring exact prior bytes' vs 'restore a note to exact content-addressed history bytes'), but nothing 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?

An output schema exists, so return values need not be described. The description covers when to use it, the CAS guard, and post-write behavior; the remaining gaps are the semantics of request_id and the note identifier, which are minor for a 4-parameter tool.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does explain expected_hash explicitly (current content_hash for CAS) and implies to_hash (target history bytes), but leaves request_id and the note identifier undocumented, so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource: 'undo a bad write by restoring exact prior bytes' / 'Restore a note to exact content-addressed history bytes.' The content-addressed/bytes framing distinguishes it from sibling write tools (patch_note_section, append_journal) and from read-only history tools like get_note_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?

Gives a clear triggering condition ('Use this to undo a bad write') and invocation guidance ('Pass the current content_hash as expected_hash for CAS'). It does not name alternatives (e.g., when to prefer patching a section instead of reverting the whole note), so it stops short of 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?

Annotations already indicate a read-only, non-destructive operation, and the description adds significant behavioral detail beyond that: frontmatter matches are excluded, ripgrep syntax is used, and without rg on PATH it falls back to slower Python regex scanning of indexed content. This gives an agent an accurate model of what will happen.

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 description is compact and front-loaded: it opens with the core mechanism and result format, then covers scope restriction, requirements, exclusions, and fallback behavior in order. Every sentence adds necessary information without redundancy.

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?

Given the output schema exists, the description covers the remaining operational essentials: prerequisites, scope filtering, frontmatter exclusion, regex dialect, and fallback behavior. An agent has enough information to invoke the tool correctly and anticipate outcomes.

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 0%, so the description carries the parameter-explanation burden. It clearly explains glob usage with an example and states that pattern uses ripgrep syntax, adding meaning the schema lacks. The limit parameter is not explicitly described, but its name and default make it self-explanatory.

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 clearly states it performs regex search via ripgrep over note content, returning ranked, highlighted, sandbox-wrapped match lines resolved to indexed chunks. It also specifies exact scope (note bodies, not frontmatter), which distinguishes it from sibling tools like search_text.

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 concrete usage context: how to restrict file scope with glob, the dependency on datacron index, and the fallback behavior when ripgrep is unavailable. It does not explicitly name an alternative tool like search_text, but the regex-versus-text distinction is strongly 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 already cover the safety profile (readOnly, non-destructive, non-idempotent), and the description adds genuine behavioral context beyond them: indexing prerequisite, ranking boost for titles/heading trails, **term** highlighting in sandbox-wrapped snippets, and the default demotion of superseded notes with the include_superseded escape hatch.

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 search-first imperative, then prerequisites, ranking, and parameter behavior in an order an agent can act on. It is dense and mostly waste-free, though the opening clause listing note types is slightly 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?

An output schema exists, so return values need no explanation, and the description covers the index prerequisite and superseded-note demotion default. What remains thin is the untold behavior of query syntax and the limit parameter, minor gaps for a 7-parameter tool.

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

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

Schema description coverage is 0%, so the description must carry the load, and it meaningfully explains folder, tags, frontmatter (cross-referencing list_notes semantics), group_by_note and include_superseded. It leaves query and limit undocumented, though those are largely self-evident.

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 and resource ("Full-text BM25 search over the FTS5 index") and states the scope precisely: notes, projects, decisions, past work. It clearly differentiates from siblings like search_regex and list_notes by describing the full-text ranking model and highlighting behavior.

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?

"First stop for any question about the user's notes... search before saying you do not know" gives a strong explicit when-to-use trigger, and the index prerequisite is stated. However, it never names the alternative tools (search_regex, get_backlinks) or when those would be preferred, so one dimension of the guideline is left implicit.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so safety is covered; the description still adds real value beyond them: pagination behavior, that coverage is explicit, that candidates never establish identity, and that a matching contract hash short-circuits instruction repetition. No auth/rate-limit detail, hence not a 5.

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 purpose and reasonably tight at five sentences, but the phrasing is dense and cryptic ('common discipline', 'repairing the index', 'coverage is explicit'), which costs clarity without obvious economy gains.

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?

An output schema exists, so return values needn't be detailed, and the description usefully covers contract-hash and paging behavior. Against a five-parameter, zero-coverage schema, though, the omission of domain, max_tokens, and note_paths semantics leaves the definition incomplete for an agent trying 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 description coverage is 0%, so the description must carry semantics for all five parameters. It explains subject ('finds ranked candidates without repairing the index') and known_contract_hash (when to send, what a match returns), but says nothing about domain, max_tokens, or note_paths, leaving three parameters undefined in both schema and prose.

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 opening 'Start memory-dependent work here' states a clear verb and entry point, and the returns are named (versioned common discipline, effective write capability, bounded live notes). It is distinguishable from the sibling read/patch/search tools. However the terminology ('common discipline', 'repairing the index') is idiosyncratic enough that the resource being fetched is not fully transparent.

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 clear context cue ('start memory-dependent work here'), a conditional for known_contract_hash ('send only when that exact contract is already in context'), and an instruction to page ('Read next pages before relying on incomplete context'). What is missing is any explicit naming of alternative siblings or when-not-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?

Although annotations already declare destructiveHint=true and readOnlyHint=false, the description adds field-level scope (the exact list of frontmatter keys mutated plus the automatic updated timestamp), the guarantee that the body is preserved, and the constraint that last_id requires expected_hash and cannot decrease an existing valid counter — all behavior beyond what annotations 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?

The sentences themselves are dense and earn their place, but the structure is back-loaded: the actual purpose ('Update frontmatter fields on an existing memory note') appears as the fourth sentence, after usage guidance, so an agent scanning for what the tool does hits examples before the verb. The 'only changes ...' enumeration is long but defensible.

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 13-parameter mutation with an output schema (so return values need not be described) and annotations covering the safety profile, the description covers the critical behavior: mutation scope, body preservation, and the last_id/expected_hash invariant. It is only slightly short on identity/path parameters (rel_path, request_id) and conflict reporting.

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 0% across 13 parameters, so the description must carry the load. It provides real meaning for the tricky ones (last_id format and monotonicity, expected_hash coupling, rejected 'option -- reason' format) and enumerates the mutable fields, but gives no semantics for rel_path, origin, request_id, archived, valid_from/invalid_at/invalidated_by beyond their names.

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: 'Update frontmatter fields on an existing memory note,' and immediately scopes it by declaring 'The Markdown body is preserved,' which cleanly separates it from the sibling body-editing tools (patch_note_section, patch_note_preamble). An agent can tell what class of operation this is 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 gives explicit triggering conditions ('when a fact's lifecycle changes: verified today, superseded by a newer note, or confidence raised or lowered') and an explicit preference over an alternative action ('Prefer invalidating an outdated fact... over deleting or rewriting it'), plus a convention for the rejected field so a future agent does not re-propose discarded options.

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