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

The description goes well beyond the annotations by disclosing that this is a write operation confined to DATACRON_WRITE_PATHS, stores content-addressed history, writes atomically, and depends on MCP client tool approval. This gives the agent a clear safety and side-effect profile.

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, each earning its place: usage condition, core action, and behavioral/safety context. Information is front-loaded and 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?

The description is complete for the core required parameters and gives strong behavioral context, and an output schema exists so return-value explanation is unnecessary. However, the optional request_id and expected_hash parameters remain opaque, which is a minor completeness gap for a tool with this many parameters.

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 conveys the meaning of entry, heading, and rel_path through context ('Append a Markdown entry under a heading in an existing memory note'), but schema description coverage is 0% and the optional request_id and expected_hash parameters are not explained at all. The description partially compensates for the missing schema descriptions but not fully.

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 — append a Markdown entry under a heading in an existing memory note — and explicitly frames it as the right choice when new information extends an existing topic rather than creating a duplicate. This makes the tool's purpose clear and distinguishes it from the create-note sibling.

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 an explicit usage condition: use when new information extends a topic that already has a note, instead of creating a duplicate. However, it does not address when not to use this tool relative to other note-modification siblings like patch_note_section or rename_note_section.

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?

The description goes beyond the readOnlyHint annotation by explicitly stating 'This tool never writes, including after elicitation or confirmation.' It also discloses that evidence is sandboxed vault text and that write_call.arguments.new_content is untrusted data, not instructions. This is a strong safety disclosure that annotations alone don't provide.

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 dense but well-structured, with each sentence serving a distinct purpose: usage context, mode behavior, safety guarantee, and data handling warning. It front-loads the primary use case and then covers edge cases. No redundant 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?

Given the tool's complexity (two modes, detail levels, token validation, safety implications), the description covers all essential aspects: when to use, what each mode does, what the output contains, and how to handle the returned data. The output schema exists, so return values don't need to be spelled out. The description is complete for an agent to select and invoke 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?

The schema has 0% description coverage, so the description must compensate. It explains the meaning of 'mode' (scan vs confirm) and 'detail' (summary vs full) in context, and mentions proposal_token in the confirm mode description. It doesn't explicitly define proposal_token's format, but the schema's enum and null default provide some structure. The description adds meaningful context beyond the raw 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?

The description clearly states the tool's purpose: scanning for contradictions between indexed sections, with two modes (scan and confirm) and a deterministic, read-only behavior. It distinguishes itself from siblings by focusing on contradiction detection rather than note retrieval, search, or editing.

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 explicitly says when to use it ('when indexed sections may conflict or refine one another') and explains the two modes (scan vs confirm) and detail levels (summary vs full). It also warns that the tool never writes, which is a clear exclusion criterion.

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 annotations only carry readOnly=false and destructive=false. The description adds meaningful behavioral detail: confinement to DATACRON_WRITE_PATHS, never overwriting existing files, writing a durable operation record, and relying on MCP client approval for human-in-the-loop review. This goes beyond the structured metadata and aligns 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?

Three sentences with no filler. The proactive call-to-action is front-loaded, and the safety constraints are compactly grouped. Every sentence carries useful 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?

The description covers the most important contextual gaps for a write operation with sparse annotations: when to use it, what to write, path confinement, no-overwrite guarantees, durable logging, and human-in-the-loop review. The remaining parameter-level ambiguity is minor given the output schema and self-descriptive parameter names.

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 does clarify the `rejected` parameter format ('option -- reason') and hints at the storage location through '_memory Markdown note', but it leaves other parameters like `rel_path`, `supersedes`, `last_verified`, and `request_id` to bare names and enums.

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 and resource: 'Write a new typed _memory Markdown note' for durable facts, decisions, and preferences. It clearly distinguishes this create-style tool from the many read, patch, and delete sibling 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?

It explicitly tells an agent when to call it proactively ('durable fact, confirmed decision, or user preference emerges') and when not to ('Skip speculation and one-off chatter'). It does not name specific sibling alternatives, but the trigger conditions are clear enough to route an 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?

The annotations already mark destructiveHint=true, and the description adds useful behavioral context: the operation stores exact prior history, writes atomically, refuses level-1 headings, and requires the current content_hash for CAS. This exceeds what annotations alone provide and aligns with the destructive hint.

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

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

Four dense sentences, all earning their place and front-loaded with the core purpose. There is no filler or repetition of schema field titles; each sentence adds critical operational guidance.

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 destructive nature and six parameters, the description covers scope, exclusion of H1, concurrency control via CAS, duplicate resolution, atomicity, history preservation, and the alternative lifecycle-invalidation approach. The output schema exists, so return-value explanation is unnecessary. The tool is fully callable from this description alone.

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 expected_hash as the current content_hash for CAS, and clarifies heading_occurrence and heading_level for duplicate titles. However, rel_path and request_id are not explained in the description, and heading is only indirectly described as the section title. Strong compensation for the complex parameters, but not complete coverage of all six.

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: remove an H2-H6 Markdown section and all subordinate headings. It also differentiates from the sibling set_frontmatter by declaring when that alternative should be preferred instead. This is unambiguous and not a tautology.

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 says to use this only for obsolete sections, directs to set_frontmatter when the fact must remain queryable, and gives concrete guidance for CAS via expected_hash and duplicate title handling. This clearly tells an agent when to choose this tool over alternatives.

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?

Beyond the readOnlyHint=true and destructiveHint=false annotations, the description discloses important behaviors: completed/cancelled records are hidden by default, history remains intact, legacy prose is not parsed, and source freshness is not revalidated. It also interprets the significance of an empty result, which is valuable for correct use. There is 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?

Every sentence earns its place: the core action, default filtering and history guarantee, parsing/freshness limitations, sibling routing, and pagination rules. The description is compact even while covering substantial operational ground, and it front-loads the most important semantic.

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 that an output schema exists, the description need not restate return values. It covers what is read, what is hidden, what is not validated, what the absence of results means, how to paginate, and how to keep reads consistent via the snapshot token. A caller has enough behavioral context to invoke 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 description coverage is 0%, so the description carries the full burden of explaining parameters. It operationally covers note_paths, include_closed, offset/next_offset, and expected_snapshot: 'keeping note_paths and include_closed unchanged,' 'Continue with next_offset and expected_snapshot=snapshot_hash,' and 'Restart from offset 0 if sources change.' This compensates completely for the schema's lack of parameter 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 opens with a specific verb-resource pair: 'Read latest structured follow-up revisions in explicit canonical notes.' It also explicitly distinguishes itself from get_note, saying 'Use get_note for legacy notes and original evidence,' so an agent can tell this tool apart from a key sibling without guessing.

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 when-to-use guidance by naming get_note as the alternative for legacy notes and original evidence, and warns that absence is not proof that no commitments exist. It also provides explicit pagination instructions: continue with next_offset and expected_snapshot, keep note_paths and include_closed unchanged, and restart from offset 0 if sources change.

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, the description discloses several key behaviors: truthful read-only, limit<=0 means server ceiling, positive limits capped, fingerprints are not hashes, only top-level paths are preserved, and line numbers never included. These are exactly the kind of nuances an AI agent would otherwise guess wrong.

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 structure is front-loaded with the purpose and then each subsequent sentence covers one meaningful behavioral nuance. It is a little dense on vocabulary like 'invariant evidence' and 'mixed_eol_notes', but no sentence is redundant, so it 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?

Given two parameters and an output schema not displayed, the description covers the importance of the details. It includes necessary caveats about what is and is not preserved and the limit ceiling, which could not be inferred from schema alone. It slightly enforces domain terms but is complete enough.

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 schema provides no descriptions for limit or detail, so both are explained in the description. It precisely defines what each value means, including the full-mode limit cap and the effect of selecting full. This fully compensates for the 0% schema 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 verb and resource: returns read-only health, and enumerates the exact dimensions (index freshness, vault integrity, point-in-time checksum, durability capability, invariant evidence). This gives a precise scope that distinguishes it from all sibling tools, none of which are operational health checks.

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 provides clear context: how to request a summary or full details and the effect of the limit parameter. It implies when to use the tool (when entire health is needed) and even describes the caching behavior of limits. It lacks an explicit exclusion or alternative pointer, but the clear scope makes that unnecessary.

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 annotations already declaring readOnly/no-destruction, the description goes well beyond them: chunk reads ignore offset/limit, a parent-hash mismatch yields an explicit stale-chunk error, section reads require full format and carry source line spans plus the original note hash, and pagination is relative to the redacted section. This is exactly the extra behavioral context 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?

Purpose and the snippet-vs-full rationale are front-loaded, and most clauses carry distinct operational information rather than filler. The middle section is dense and clause-heavy, but little of it is genuinely 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 6-parameter fetch tool with an output schema and read-only annotations, the description covers input forms, format-selection trade-offs, edge-case errors, and format-specific constraints. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description carries the full burden and largely meets it: it explains the format enum (full/map/chunk), the offset/limit character-range paging, heading_path ancestry plus subtree, and the 1-based heading_occurrence needed for repeated paths. limit's unit of measure is only implied via the offset/limit pairing rather than stated outright, keeping it from 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?

The opening states a specific verb and resource plus the three accepted identifier forms (ULID, indexed chunk_id, vault-relative path), so an agent knows exactly what it retrieves. It stops short of differentiating itself from siblings such as get_note_history or list_notes, so differentiation is left to inference.

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?

"Fetch the full context behind a search hit before answering from a snippet alone" gives a clear context for use, and the format='map' note ('cheap to scan before requesting full content') offers a concrete workflow trigger. No sibling tool is named as an alternative and there is no explicit when-not-to-use, so it falls just 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 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 declare this as read-only and non-destructive. The description adds valuable behavioral context: pagination with offset/limit, optional scoping to a subfolder, filtering by tags or frontmatter, and the specific fields returned per entry. No contradiction with 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 two sentences with no waste. It front-loads the primary use case, then concisely lists the key features (pagination, filters, entry fields), earning every word.

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 and annotations provide safety context, the description is complete for selection and invocation. It covers the use case, filter options, result contents, and pagination behavior, leaving no significant gaps for an agent.

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 meaning of tags, folder, frontmatter, and pagination, with a useful frontmatter example. However, limit and offset are only implied by 'paginated' and lack explicit semantic detail beyond what the schema's defaults suggest.

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 returns a paginated list of notes, with optional filters for subfolder, tags, and frontmatter. It uses a specific verb ('Return') and resource ('list of notes'), and distinguishes itself from siblings like get_note (deeper reads) by framing it as a discovery tool.

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

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

The first sentence explicitly instructs to use this tool for discovering vault structure before deeper reads, providing clear contextual guidance. It doesn't explicitly name alternatives or exclusions, but the contrast with 'deeper reads' implies when not to use it.

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 mutation (readOnlyHint=false), destructiveness, and non-idempotency, and the description adds substantial context beyond them: preview returns selection coordinates and before/projected hashes without writing, confirm commits with durable history and index reconciliation, bytes/frontmatter are preserved, and mixed EOLs, unsafe boundaries, and invalid child hierarchy are refused. This is rich behavioral disclosure.

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, then flows into preview/commit behavior and constraints with little waste. It is dense and slightly packed, but nearly every 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 a 10-parameter destructive mutation with an output schema present, the description covers preview vs commit, hashing, occurrence disambiguation, and refusal conditions. It omits what rel_path means and what happens on a hash mismatch, leaving minor gaps.

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 does for most params: expected_hash is required, confirm defaults to false, request_id is for durable replay receipts, and heading_level/occurrence and destination_level/occurrence resolve duplicate titles with 1-based occurrence. Only rel_path is left unexplained, keeping it from 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 with precise scope: 'preview an exact single-note H2-H6 subtree move to an existing heading's final child position.' This clearly distinguishes it from siblings like rename_note_section, delete_note_section, and patch_note_section without needing to open 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 clear when-to-use context: default confirm=false for preview, confirm=true to commit, and request_id for durable replay when committing. It does not name sibling alternatives (e.g., patch_note_section vs this) or state exclusions, 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?

Beyond the destructiveHint annotation, the description discloses exact mutation scope, CAS requirements, empty-content removal semantics, byte-preservation behavior under uniform vs mixed line endings, and fail-closed refusal for unheaded notes. It also explains the shared AST selector's edge-case behavior with ATX/Setext headings and fenced code. This is rich behavioral context that annotations alone cannot provide.

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 dense but every sentence earns its place: operation, CAS, removal semantics, EOL behavior, fail-closed behavior, and selector details. The main usage guidance is front-loaded, with edge cases following logically. There is no filler or repetition of schema 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?

Given the tool's complexity and the presence of an output schema, the description is complete. It covers what the tool does, how the heading selector behaves, when it refuses, how content removal works, and how byte preservation behaves across EOL styles. Nothing an agent needs to call this tool correctly is materially 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?

With 0% schema description coverage, the description compensates by explaining the key parameters: expected_hash must be the note's exact CAS value, and new_content can be empty or whitespace-only to remove the preamble. rel_path is not explicitly described, but its title 'Rel Path' makes its role clear. request_id is not explained, but it is optional and likely a standard correlation identifier, so this is a minor 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 opens with a specific verb and resource: 'replace or remove content strictly before the first Markdown heading.' This precisely defines the tool's scope and distinguishes it from siblings like patch_note_section, which target different structural regions. The operation is immediately understandable from the first sentence.

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 explicitly says 'Use this to...' and clearly defines when the tool applies: only to content before the first recognized Markdown heading. It also states that notes without such a heading are refused fail-closed, giving a hard boundary. It does not explicitly name alternatives or say when to prefer a sibling tool, which keeps it just 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?

Even though destructiveHint=true already signals mutation, the description goes further: it states the operation preserves the heading line and non-target sections, stores exact prior history, writes atomically, and enforces CAS via expected_hash. It also documents the duplicate-title ordinal behavior. No statement contradicts 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 explanation is dense and mostly front-loaded, with each sentence contributing operational detail. The 'Do not use chunk_id' sentence is out of place because that parameter does not appear in the schema, adding slight noise.

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, CAS-guarded patch operation this is close to complete: it covers target selection, duplicate resolution, atomicity, history, and a key refusal case. It does not state failure behavior when expected_hash mismatches or when expected_hash is omitted, but the output schema helps fill in return expectations.

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?

With no schema-level property descriptions, the description carries the burden and does explain the non-obvious parameters: expected_hash for CAS, and heading_level/heading_occurrence for duplicate titles. However, rel_path and request_id are left implicit, and it even mentions a chunk_id that is not present in the schema.

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

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

The description uses a specific verb and resource ('rewrite an outdated section in place', 'Replace the content under one existing Markdown heading'), so an agent knows what operation is performed. It does not explicitly name sibling tools such as patch_note_preamble or append_journal, so differentiation relies on the section/heading framing rather than an explicit contrast.

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 trigger ('when the topic already has a note') and a conditional instruction ('It refuses a level-1 heading that contains subsections; patch a lower-level heading instead'). It does not name alternative tools for creating a new note or patching the preamble, so exclusions are implicit 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 declare readOnlyHint=true and destructiveHint=false, but the description adds genuinely non-obvious traits: output is bounded append_journal plans rather than writes, validation is structural and 'not a truth verdict', and at most 20 records are checked at runtime. It does not cover auth/permission needs, but the behavioral profile is well beyond what the annotations supply.

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 first three sentences are tight and front-load purpose, prerequisites, and output behavior. The final mega-sentence dumping every pattern, enum, and default is a dense run-on, justified only by the stated client-stripping rationale; it inflates length without adding semantic value.

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 nested-record tool, the description covers prerequisites, validation semantics, runtime limits, and the apply-then-verify workflow, and an output schema exists so return values need not be explained. It is nearly complete, missing only feedback on failure modes or how validation errors are surfaced.

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 meaning; it does convey the conceptual role of target_id/expected_hash/source_hash/source_excerpt ('against live note IDs/hashes and exact source excerpts') and repeats the constraints clients may strip. However it mostly mirrors mechanical schema constraints rather than explaining fields like owner, status, event_date, or due_date semantics, leaving real gaps.

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 (validate/prepare) and resource (sourced follow-up records, i.e. actions, interactions, objectives, state revisions) with the exact validation basis (live note IDs/hashes and source excerpts). It also distinguishes itself from the writer siblings by noting it returns append_journal plans and never writes, so an agent can separate it from append_journal 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?

Gives a clear workflow ('Use stable record/revision IDs, then apply with existing writers and verify receipts') and prerequisites ('Existing target history headings are required', 'clarify homonyms first' for person targets). It stops short of naming the alternative writer explicitly or stating when NOT to use the tool, but the context is unambiguous.

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

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

Annotations already flag destructive behavior, and the description adds substantial operational detail beyond that: CAS via expected_hash, refusal of H1 and collision headings, ATX/Setext support, fenced-code headings being ignored, and duplicate-ordering semantics. This gives an agent a realistic model of how the tool behaves at runtime.

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 dense but every clause earns its place: scope, constraints, CAS, format handling, and duplicate behavior are all covered without repetition. The most important usage restriction is front-loaded, and the warning 'Do not use chunk_id' is a valuable, concise final sentence.

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 tool's complexity — 7 parameters, destructive write behavior, CAS, AST-dependent matching, and duplicate titles — the description is remarkably complete. It covers edge cases, format support, exclusions, and parameter semantics, and the presence of an output schema means return-value documentation is unnecessary.

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?

With 0% schema description coverage, the description must compensate, and it does for the most important parameters: expected_hash is explained as CAS, and heading_level/heading_occurrence are explained for duplicate titles with document-order semantics. However, the required rel_path parameter is never mentioned, and request_id is also unaddressed, leaving minor but real gaps.

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 names a specific operation (rename), a specific resource (H2-H6 Markdown section title recognized by the write selector), and explicit scope constraints (no level/content/subordinate changes, H1 refusal). This clearly distinguishes it from siblings like patch_note_section, delete_note_section, and set_frontmatter.

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 opens with 'Use this only to rename...', which establishes precise when-to-use guidance, and adds explicit exclusions: H1, collisions, fenced-code headings, and chunk_id usage. It does not name the alternative tool for H1 frontmatter changes, but the statement that frontmatter synchronization is 'outside this tool' makes the routing intent 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 mark the tool as destructive and idempotent. The description adds valuable context by stating the revert is 'durable, reversible, indexed, and operation-logged,' and it explains the CAS expected_hash behavior. This goes beyond what annotations convey 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?

Three dense sentences with no filler. Purpose is front-loaded ('undo a bad write'), followed by the mechanism and durability guarantees. Every sentence contributes essential 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?

The description covers the primary use case, the key safety behavior (reversible, operation-logged), and the CAS parameter. With an output schema present and annotations providing the safety profile, this is mostly complete. It could mention how to obtain to_hash (e.g., via get_note_history), but this is 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 0%, so the description must compensate. It explains expected_hash ('Pass the current content_hash as expected_hash for CAS') and implies to_hash is the content-addressed history target. However, the 'note' and 'request_id' parameters receive no explicit semantic guidance, leaving an incomplete picture of all four parameters.

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 verb ('undo', 'restore') and resource ('note' / 'exact content-addressed history bytes'), making the tool's function obvious. It does not explicitly name or differentiate against sibling tools like patch_note_section or get_note_history, but the 'undo a bad write' framing is sufficiently distinct from normal edit operations.

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

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

The description gives an explicit trigger condition: 'Use this to undo a bad write by restoring exact prior bytes.' This tells an agent when the tool is appropriate. It does not mention alternatives or explicitly say when not to use it, 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?

Beyond the readOnlyHint annotation, the description discloses the fallback to scanning indexed chunk bodies when rg is missing, notes the slower performance and limited visibility, and explains the dependency on 'datacron index'. This adds substantial behavioral context that annotations do not capture.

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 tight and front-loaded: it states the core function in the first sentence, then adds scope control, prerequisites, and fallback behavior in two more sentences. No redundant phrasing or 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?

Given an output schema exists, the return format is already documented. The description covers the glob parameter, the prerequisite index, and the fallback path. The only gap is the lack of explanation for the 'limit' parameter, which is minor but still leaves the agent guessing about its effect. Overall, it is nearly complete for a read-only search 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 explain all parameters. It explicitly explains glob ('Restrict file scope with glob') but does not mention 'limit' at all, and only implies 'pattern' as the regex. With three parameters, two of them (pattern and limit) lack explicit explanation, leaving the agent to infer semantics.

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 is a regex search tool using ripgrep, returning ranked match lines with highlighting and chunk resolution. It is specific about the resource (regex search) and the mechanism (ripgrep), making it distinct from sibling search_text which likely handles plain-text search.

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?

Provides clear usage context: how to restrict scope with glob (e.g., '*.md'), the prerequisite of 'datacron index' for chunk resolution, and a fallback behavior when rg is absent. However, it does not explicitly contrast with search_text or state when not to use it, so it stops short of a 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 cover readOnly and destructive safety, and the description adds substantial behavioral context: BM25 ranking, title/heading weighting, highlighted snippets, group_by_note behavior, demotion of superseded notes, and the index prerequisite. No contradiction with 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?

Five sentences, front-loaded with the primary use case, then mechanism, scoping options, prerequisite, and a key default. Every sentence earns its place with 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?

Covers use case, prerequisite, scoping, grouping, and superseded behavior, while the output schema handles return shape. Missing explicit routing to search_regex and minor limit/query syntax details, but the tool is still safely invokable.

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 folder/tags/frontmatter scoping, group_by_note=true, and include_superseded=true. It delegates frontmatter semantics to list_notes and omits details about limit and query syntax, leaving some 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 states a specific verb and resource: full-text BM25 search over the FTS5 index of the user's notes, projects, decisions, and past work. The phrase 'First stop' positions it among siblings, and the BM25 mechanism implicitly distinguishes it from search_regex.

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 tells the agent when to use it: 'First stop for any question... search before saying you do not know.' It also gives a prerequisite (datacron index) and explains default behavior for superseded notes. It does not explicitly name alternatives or exclusions such as 'use search_regex instead'.

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 goes well beyond the annotations by disclosing meaningful behavioral traits: subject search is non-mutating ('without repairing the index'), candidates never establish identity, coverage is explicit, and known_contract_hash has special match behavior that avoids repeating instructions. These details are not available from readOnlyHint or destructiveHint alone.

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 dense but not bloated: every sentence contributes a distinct fact about purpose, output, search behavior, coverage semantics, incomplete-context caution, or contract-hash handling. It is front-loaded with the core action and return value, then layers parameter-specific guidance 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?

With an output schema present and annotations covering the safety profile, the description adequately explains the tool's role, key behaviors, and important caveats. It does not explicitly map domain, max_tokens, and note_paths to their effects, nor does it mention alternative sibling tools, so a small completeness gap remains for an agent deciding among similar operations.

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?

Although schema description coverage is 0%, the description adds real semantic value for two nuanced parameters: subject returns ranked candidates without index repair, and known_contract_hash should only be sent when the exact contract is already in context. Domain, max_tokens, and note_paths are not explicitly described, but their names and enum values make them reasonably self-explanatory, and 'bounded live notes' hints at the token/path constraints.

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 identifies the tool as the entry point for memory-dependent work ('Start memory-dependent work here') and states what it returns: versioned common discipline, effective write capability, and bounded live notes. It further distinguishes its optional subject behavior as candidate ranking rather than index repair or identity resolution, which helps separate it from search-like 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: at the beginning of memory-dependent work. It also provides actionable precautions such as 'Read next pages before relying on incomplete context' and conditional guidance for known_contract_hash. It does not explicitly name alternative sibling tools or say when not to use this tool, 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?

While annotations declare destructiveHint:true, the description adds critical detail: it specifies exactly which fields are modified and explicitly states 'The Markdown body is preserved.' It also discloses constraints on last_id (requires expected_hash, format rules, non-decreasing counter). This goes far beyond the annotation signals and informs the agent of exactly what will change, reducing surprise.

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 dense but well-organized: it starts with the purpose, moves to usage guidance, then lists the fields and constraints. Every sentence carries useful information; no fluff. It could be slightly trimmed (e.g., listing fields is redundant with the schema), but the repetition aids comprehension. The front-loading is effective.

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 tool's complexity (13 parameters, destructive write), the description covers the behavioral essentials: when to use, what fields change, key constraints, and that the body is preserved. It doesn't detail return values (though an output schema exists) or enumerate all parameter formats, but it provides sufficient context for correct invocation. The description is comprehensive enough for an agent to act without additional 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?

The input schema has 13 parameters with zero description coverage in the schema itself. The description compensates by listing the affected fields and adding semantic context for key ones: last_id constraints (expected_hash, format, monotonicity) and the rejected entry format ('option -- reason'). It doesn't explain every parameter's format (e.g., date strings), but for a write tool with this many fields, it provides enough context to make intelligent calls.

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 function: updating lifecycle frontmatter on existing memory notes, with a specific list of fields. It distinguishes itself from sibling tools like patch_note_preamble and patch_note_section by focusing on the frontmatter rather than body content. The verb 'set' and resource 'frontmatter' are explicit, making the tool's purpose immediately understandable.

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 provides explicit when-to-use guidance: 'Use this when a fact's lifecycle changes' with specific scenarios (verified, superseded, confidence changes). It also offers behavioral preferences (prefer invalidation over deletion) and a clear convention for rejected entries. This gives an agent unambiguous criteria for choosing this tool over alternatives, even if sibling names aren't exhausted.

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