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 disclosed that the tool never writes, even after elicitation or confirmation, which directly reinforces the readOnlyHint annotation and adds important context about the confirm mode's behavior. It also explains that scan mode returns deterministic candidates and read-only proposal tokens, and clarifies the difference between summary and full detail. These details go beyond what annotations 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 two sentences, front-loads the usage condition, and packs essential information about modes, detail levels, and safety without redundancy. Every sentence 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?

The description covers the tool's core behavior, modes, and read-only guarantee. Since an output schema exists, return values are not the description's responsibility. However, it could be slightly more complete by explicitly tying proposal_token to confirm mode, but this is a minor gap. Overall it is sufficient for an agent to use 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?

With 0% schema description coverage, the description must compensate, and it does. It explains the 'mode' parameter (scan vs confirm), the 'detail' parameter (summary vs full), and implies the 'proposal_token' parameter through 'confirm mode validates one token.' However, it does not explicitly name the proposal_token parameter or state that it is required for confirm mode, leaving some inference to the reader.

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 scans for contradiction candidates between indexed sections that may conflict or refine each other. It distinguishes itself from sibling tools by describing its specific analytical purpose and the two modes (scan/confirm). The verb 'scan' and explicit resource 'contradiction candidates' make the purpose 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?

The description provides explicit usage context: 'Use this when indexed sections may conflict or refine one another.' It distinguishes between scan and confirm modes and explains when each is appropriate. However, it does not explicitly mention when not to use this tool or name alternative sibling tools, so it lacks explicit exclusions or 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?

Adds substantial context beyond the annotations: confinement to DATACRON_WRITE_PATHS, the never-overwrite guarantee, the durable operation record, and reliance on MCP client approval for human-in-the-loop review. This gives an agent a full safety picture. The write claim is consistent with readOnlyHint=false and the non-destructive claim is consistent with destructiveHint=false.

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 tightly packed sentences, each earning its place: proactive trigger, what to skip, what to write plus rejected-format rule, and safety behavior. The most decision-relevant information is front-loaded before the safety 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 description fully covers the call decision (when, what, safety) for an 11-parameter operation, and the output schema covers return values so those need not be described. Minor gaps remain: no differentiation from append_journal as an alternative, and the optional metadata parameters (supersedes, expected_hash, last_verified, request_id) are unexplained — a small but real completeness cost for a tool this complex.

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 across 11 parameters, the description must compensate heavily. It does clarify one parameter concretely — 'rejected entries in option -- reason format' — and 'typed _memory Markdown note' hints at title/rel_path/body. However, the other required parameters (tags, origin, confidence) and optional metadata fields (supersedes, expected_hash, last_verified, request_id) receive no semantic explanation, leaving meaningful 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 states a specific verb and resource — 'Write a new typed _memory Markdown note' — and gives the exact trigger conditions (durable fact, confirmed decision, user preference). It differentiates from the patch/update siblings by emphasizing 'new' and 'never overwrites existing files,' and from append_journal by the memory-note vs journal distinction.

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 explicit when-to-use guidance ('Call this proactively when a durable fact, confirmed decision, or user preference emerges... do not wait to be asked') and clear exclusions ('Skip speculation and one-off chatter'). It stops short of naming sibling alternatives and stating when to choose them instead, so the alternative-routing dimension is not fully covered.

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?

The description significantly adds behavioral context beyond the annotations. It explains the target resolution order ('title -> filename -> aliases') and the empty list behavior for unresolved targets or no incoming links. This gives the agent a precise understanding of edge cases and resolution logic, which is valuable given the annotations only declare read-only 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?

The description is four concise sentences, each earning its place. It is front-loaded with the primary use case, then provides technical resolution details, and ends with the edge-case empty list behavior. There is no fluff or repetition, making it highly efficient for an agent to parse.

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 moderate complexity and the presence of an output schema (which negates the need to describe return values), the description covers the core aspects: use case, target resolution, and empty behavior. It does not explicitly address the limit parameter behavior, but that is a minor omission given the schema provides the default. Overall, it is sufficiently complete for an agent to use 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?

With 0% schema description coverage, the description carries the burden for parameter semantics. It thoroughly explains the 'target' parameter, including acceptable formats (ULID or wikilink alias) and resolution precedence. The 'limit' parameter is not mentioned, but its meaning is conventional and its default (20) is in the schema. The description adds significant meaning for the key parameter, so a 4 is appropriate.

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

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

The description clearly identifies the tool's function: 'Return chunks whose wikilinks point at the given target.' It also adds a specific use case ('find related context the user did not mention') that distinguishes it from general search tools like search_text or search_regex. The verb 'Return' and resource 'chunks with wikilinks' make the purpose 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?

The opening phrase 'Use this to find related context the user did not mention' provides a clear scenario for when the tool is appropriate. However, it does not explicitly mention alternatives or state when not to use it, so it lacks exclusion guidance. This earns a 4 for clear context without full differentiation.

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?

Annotations already set readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'truthful read-only.' It goes well beyond annotations by explaining sanitization behavior (fingerprints are opaque baseline identifiers derived from raw keys, not hashes of sanitized published keys), the addressability of rel_path and mixed_eol_notes entries, and that candidate_paths are sanitized display metadata. It also discloses that findings do not include line numbers. This is richly transparent about behavioral traits an agent must know before trusting the output.

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 each sentence adds a distinct fact: truthful read-only health, the purpose of detail='full', limit semantics, fingerprint semantics, and path sanitization caveats. It is front-loaded with the core purpose and then layers the caveats. 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?

The tool has an output schema, so return values need not be described in the description. What remains is the behavioral context needed to call it correctly: what full mode does, how limits are capped, what the fingerprints mean, which paths are addressable, and that line numbers are absent. Given the safety profile already carried by annotations and the output schema, this description is 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%, so the description must compensate. The description does explain the effect of both parameters: detail='full' to include bounded integrity findings, and limit semantics (<=0 selects server ceiling, positive capped by settings.max_result_count). The limit semantics are only explained in the context of full mode, so summary-mode limit behavior is not explicitly stated. The description adds meaning beyond the bare schema but leaves a small 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: 'Return truthful read-only health for index freshness, vault integrity, point-in-time checksum, durability capability, and invariant evidence.' This is not a tautology; it states exactly what the tool reports and even qualifies the response as truthful, echoing the readOnly annotation. It also distinguishes itself from siblings by being a health/read-only tool rather than a query, note-fetch, or mutation 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?

It clearly indicates when to use detail='full' vs the default summary mode: 'Use detail='full' to include bounded integrity findings.' It explains the limit semantics for full mode (limit <= 0 selects server ceiling; positive limits capped by settings.max_result_count). It doesn't explicitly say when not to use this tool vs alternatives, but the sibling list includes read-only tools like list_notes and get_note, and the health-specific scope implies when this is the right choice. There is no explicit exclusion of alternative tools, but the context is clear.

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

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

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 declare readOnlyHint=true and destructiveHint=false, lowering the burden on the description. The description usefully adds that it returns committed operation metadata, avoids reading history content, and does not modify the journal. 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?

Two compact sentences with no filler. The most important filtering behavior is front-loaded, and every clause adds meaningful 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 tool is simple, has an output schema, and annotations cover safety behavior. The description provides the core semantic context needed to call it correctly; the only notable gap is the undocumented limit parameter, which is optional and low-risk due to its default value.

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 that request_id filters for an ordinary-write receipt and that the call is scoped to one note, but it does not explain the limit parameter or its behavior. This is partial compensation, not full.

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: 'List committed operation metadata for one note.' It also distinguishes itself from content-reading tools by adding 'without reading history content,' making the tool's purpose 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?

The description clearly indicates when the tool is relevant ('Filter by request_id to retrieve an ordinary-write receipt') and states what it does not do ('without reading history content or modifying the journal'). It does not explicitly name sibling alternatives, but the usage context is easy to infer.

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?

Rich behavioral disclosure beyond the read-only annotation: ranking by BM25, title/heading weighting, snippet format with **term** highlighting, grouping by note, default demotion of superseded notes, and the prerequisite index requirement. No contradiction with annotations; it complements the readOnlyHint/destructiveHint.

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

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

Four dense sentences with the primary purpose front-loaded ('First stop...') followed by mechanism, return format, parameter semantics, and prerequisites. Every sentence adds operational value; no filler.

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

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

For a 7-parameter search tool with an output schema, the description covers the behavior, scoping, grouping, superseded handling, and setup prerequisite. The output schema already exists, so return-value details don't need to be repeated. Only an explicit alternative-routing statement is absent, which is minor given the 'first stop' framing.

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 group_by_note, include_superseded, and scope-narrowing via folder/tags/frontmatter with shared list_notes semantics. It also contextualizes query as BM25 over FTS5. Only 'limit' is left to its schema default, which is low-risk and 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?

States a specific verb and resource: full-text BM25 search over the FTS5 index. Positions itself as the 'First stop' for questions about notes/projects/decisions/past work, and the BM25 versus regex mechanism differentiates it from search_regex in the sibling list. Also ties to list_notes semantics, reinforcing its role.

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

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

Clear when-to-use guidance: use this first for any question about the user's notes before saying you don't know. It gives prerequisites ('datacron index') and scoping options, but does not explicitly state when to prefer alternatives like search_regex or when not to use it. Thus a clear context with no explicit exclusions.

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 declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail beyond that: the response is versioned and bounded, subject search does not repair the index, coverage is explicit, candidates never establish identity, and incomplete context requires further reading. No contradiction between description and 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 dense but purposeful sentences with the primary call to action front-loaded. Every sentence earns its place, and there is no repetition of information already present in the schema or annotations.

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 largely complete for an agent selecting and invoking the tool: it provides the entry-point signal, optional subject behavior, identity limitation, and pagination warning. The presence of an output schema reduces the need to document return values, though note_paths and domain semantics remain underexplained.

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. It clearly explains the subject parameter ('finds ranked candidates without repairing the index') and implies max_tokens/pagination via 'bounded live notes' and 'read next pages'. However, note_paths and domain receive no explicit semantic treatment, leaving a noticeable 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 clearly states a specific action ('Return the versioned common discipline, effective write capability and bounded live notes') and positions the tool as the entry point for memory-dependent work. It does not explicitly distinguish itself from sibling tools, but the resource and behavior are concrete enough to avoid confusion with note/search 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?

'Start memory-dependent work here' gives a clear when-to-use signal, and the note about reading next pages before relying on incomplete context sets expectations for multi-page sessions. It does not name alternatives or state exclusions, but the context is strong enough to route an agent.

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 this is a destructive, non-read-only, non-idempotent write; the description adds value beyond that by naming exactly which fields are mutated, confirming the Markdown body is preserved, and specifying the last_id format/auth-like constraint (expected_hash required, BL- prefix, no decreasing counter). It does not, however, explain what deletion/destruction actually occurs, which is notable given destructiveHint=true.

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 lifecycle trigger is front-loaded before the operational details, and sentences are dense with substance. Slightly long, but each clause (invalidating over deleting, rejected format, field list, last_id rules) earns its place.

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

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

For a 12-parameter destructive write with an output schema (so return values need not be explained), the description covers the lifecycle model, conflict/invalidations semantics, and the highest-risk parameter constraint. It stops short of explaining how several optional fields interact, but the essential calling context is present.

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 it does add real semantics for the tricky parameters: last_id format and its expected_hash dependency, and the rejected 'option -- reason' format. But the remaining ~9 parameters (origin, supersedes, confidence, valid_from, invalid_at, invalidated_by, last_verified, request_id, expected_hash) are only named, not explained. Partial compensation for a 0% coverage schema.

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

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

States a specific verb+resource ('Update frontmatter fields on an existing memory note') and enumerates the exact fields modified, distinguishing it from sibling note-mutation tools like patch_note_preamble and revert_note. It does not directly name alternatives, but the field enumeration makes scope 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?

Gives explicit trigger conditions ('when a fact's lifecycle changes: verified today, superseded by a newer note, or confidence raised or lowered') and a clear preference rule: prefer invalidating over deleting/rewriting, with a stated reason (history stays queryable). It also prescribes a format for the 'rejected' field. This is actionable when-to-use guidance.

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