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

Annotations only set boolean hints to false, so the description carries the behavioral disclosure burden. It fully delivers: labels the operation a write, confines it to DATACRON_WRITE_PATHS, mentions content-addressed history, atomic writes, and reliance on MCP client approval for human-in-the-loop review. 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?

Three sentences with no filler: the first states usage, the second specifies exact placement, the third covers safety and execution details. Critical information is front-loaded and 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 purpose, usage, write behavior, path confinement, atomicity, and review flow, which is strong for a write operation. It omits explanation of the optional concurrency/request parameters, but an output schema exists for return values and the core invocation path is well covered.

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 adds meaning for rel_path (confined to DATACRON_WRITE_PATHS), heading, and entry (Markdown, placement). However, it does not explain the optional request_id or expected_hash parameters, which are opaque without schema descriptions.

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

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

States a specific verb and resource: append a Markdown entry under a heading in an existing memory note. The description also distinguishes the tool from creating a duplicate and gives precise placement semantics (after heading content, before first subsection), leaving no ambiguity about what it does.

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

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

Gives an explicit condition for use: 'when new information extends a topic that already has a note, instead of creating a duplicate.' This clearly identifies the scenario and the alternative (duplicate creation), though it could have explicitly named sibling create_note_ai or noted 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?

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?

Annotations only give the coarse profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), while the description adds genuinely new behavioral facts: writes are confined to DATACRON_WRITE_PATHS, existing files are never overwritten, a durable operation record is written, and human review happens through the MCP client's tool approval. That is exactly the extra context annotations cannot carry.

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

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

Front-loads the trigger condition before the mechanics, and every sentence carries information (trigger, exclusions, note format, rejected-option convention, write semantics). It is dense rather than padded, though the long middle sentence packs several distinct ideas together.

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

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

An output schema exists, so return values need not be described, and the behavioral side is well covered. However, for a 10-parameter tool with 0% schema description coverage, the description leaves most parameter semantics undocumented, which is a real gap even if an agent could guess from 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% across 10 parameters, so the description carries the full load, yet it only documents one field ('rejected' entries in 'option -- reason' format). Semantics for rel_path, origin, confidence, supersedes, last_verified, request_id and tags are left entirely to field 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?

States a specific verb and resource ('Write a new typed _memory Markdown note') and scopes it tightly to durable facts, decisions and preferences, which separates it from siblings like append_journal or patch_note_section. An agent can identify the operation without inspecting the schema.

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

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

Gives explicit when ('when a durable fact, confirmed decision, or user preference emerges - do not wait to be asked') and when-not ('Skip speculation and one-off chatter') conditions, plus a special sub-case for recording discarded options via 'rejected'. No sibling is named as an alternative, but the selection criteria are otherwise fully specified.

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

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

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?

The description adds substantial behavioral detail beyond the annotations: it discloses that completed/cancelled records are hidden by default but history remains intact, that legacy prose is not parsed and source freshness is not revalidated, and that certain fields come back inside vault_content envelopes and should be treated as data. There is no contradiction with readOnlyHint=true or openWorldHint=false; in fact, the 'absence is not proof' line reinforces the openWorldHint.

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 main purpose is front-loaded, followed by scoping restrictions, field type warnings, alternative routing, and pagination rules. The description is compact but information-dense, with no filler or redundancy.

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

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

Given that an output schema exists, the description does not need to detail return values. It covers the tool's scope, limitations, pagination, and relationships to siblings. For a read-only tool with 4 parameters and a clear output schema, this description is complete enough for an agent to call it correctly without additional context.

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 full burden of explaining parameters. It explains pagination semantics (offset, expected_snapshot), how to keep note_paths and include_closed stable across pages, and the meaning of include_closed by stating that closed/cancelled records are hidden by default. This is sufficient compensation for the absent schema 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 first sentence states a specific verb and resource: 'Read latest structured follow-up revisions in explicit canonical notes.' This distinguishes the tool from siblings like get_note by specifying 'structured follow-up revisions' and 'canonical notes', and it later names get_note as the alternative for legacy notes.

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 explicit guidance: 'Use get_note for legacy notes and original evidence; absence is not proof that no commitments exist' directly names the alternative and the condition for choosing it. It also provides clear pagination instructions (continue with next_offset and expected_snapshot, keep note_paths and include_closed unchanged, restart from offset 0 if sources change), leaving no ambiguity about how to invoke correctly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes far beyond that. It explains the 'truthful read-only' nature, how limit works in full mode (server ceiling vs capped by settings.max_result_count), fingerprint semantics (opaque baseline identifiers from raw keys, not hashes of sanitized keys), path preservation (only top-level violation rel_path and mixed_eol_notes preserve addressable paths), and that findings omit line numbers. These are detailed behavioral traits that the annotations do not convey, so the description adds substantial value.

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 contributes: purpose, usage detail, limit semantics, fingerprint clarification, path preservation caveat, and line number note. It is front-loaded with the core purpose before diving into specifics. It is somewhat long but all content is relevant and non-redundant, so a 4 is appropriate.

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 (multiple health dimensions, parameter interactions, output schema present), the description covers the essential operational details: how to request full findings, limit behavior, fingerprint definition, path addressability, and missing line numbers. The output schema likely defines return values, so the description need not repeat them. Nothing an agent needs to correctly call the tool is missing, so this 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 coverage is 0%, so the description must compensate. It does explain both parameters: detail (with enum values summary/full) is described as 'summary' default and 'full' to include bounded integrity findings; limit is explained in full mode with specific behavior (<=0 selects server ceiling, positive limits capped by settings.max_result_count). This adds meaningful semantics beyond the bare schema, though it could be slightly more explicit about summary mode and limit's default behavior outside full mode, hence a 4 rather than 5.

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

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

The description states a specific verb and resource: 'Return truthful read-only health' for several named aspects (index freshness, vault integrity, point-in-time checksum, durability capability, invariant evidence). This clearly distinguishes it from all sibling tools, which are note operations, search, and other non-health functions. The purpose is unambiguous and specific.

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 usage details (e.g., 'Use detail=\'full\' to include bounded integrity findings', limit behavior) but does not explicitly state when to use this tool versus alternatives or when not to use it. Since it is a unique health-check tool among siblings, the need for alternatives is low, but the description lacks an explicit usage context or exclusion statement, so it earns a mid score.

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?

Annotations already mark destructiveHint true, and the description goes further: CAS via expected_hash, empty-content deletion semantics, exact-byte preservation with EOL normalization, and fail-closed cases. 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?

Four dense sentences, each adding distinct information: operation, CAS, edge cases, and parser behavior. It is compact despite covering several important caveats, and the main use is front-loaded.

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 destructiveHint annotation, output schema, and moderate complexity, the description covers all critical calling context: exact scope, CAS requirement, deletion semantics, EOL normalization, and refusal cases. Nothing essential is missing for correct invocation.

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 (CAS) and new_content (empty removes; whitespace-only same), two of the three key parameters. rel_path and request_id are left to inference, but rel_path is self-evident and request_id has a default.

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?

Description states a precise action – replace or remove content before the first Markdown heading – and identifies the target resource (the note preamble) and the boundary (first heading). It clearly differentiates from section-level siblings by limiting scope to the preamble.

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?

Clearly states when to use (replacing/removing preamble content) and includes fail-closed conditions (no heading, open code fence/HTML block). It does not explicitly name sibling tools as alternatives, but the scope is explicit enough that an agent can decide.

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 state destructiveHint=true and readOnlyHint=false, meaning it's a write operation. The description adds context beyond that: it preserves heading line and non-target sections, stores exact prior history, writes atomically, and refuses on structural changes. This covers key behaviors like CAS (expected_hash), which is not in annotations. Minor gap: doesn't specify if changes are reversible via revert_note, but atomic write and history mention are sufficient.

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 focused, with the core purpose and key constraints in the first two sentences. Every sentence adds value: CAS, preservation, atomicity, error conditions, and disambiguation. 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?

Given the tool's complexity (7 params, duplicate titles, CAS, structural checks), the description covers the essential usage paths: how to handle regular sections, subsections, duplicate headings, and security constraints. It provides action for common errors (patch subsection or delete first). Output schema exists, so return format isn't needed. The reference to error codes (section_has_subsections, section_structure_changed) is enough for agents to recover.

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 expected_hash is for CAS, heading_occurrence is 1-based for duplicate titles, heading_level is used with it, and chunk_id is explicitly disallowed. It also clarifies new_content restrictions (no open code fences). It doesn't detail rel_path or request_id, but these are standard and inferable from context.

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 rewrites an outdated section under an existing heading, with the action 'rewrite' and the resource 'note section'. It distinguishes itself from siblings like patch_note_preamble and delete_note_section by specifying it targets an existing heading and preserves other sections, adding uniqueness beyond the name.

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 states when to use: when a topic already has a note and needs a section rewrite. It provides exclusions: do not use for subsections (patch them instead), do not use chunk_id, and implicitly for delete (use delete_note_section). The refusal conditions (has subsections, leaves code fence open) serve as clear guidance against misuse, and alternatives like delete- or move-section are implied by error codes.

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 richly discloses behavior: validation is structural rather than a truth verdict, refusal cases are enumerated, retrieval-redaction behavior is explained, record limits are stated, and the tool explicitly never writes. All statements are consistent 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?

The description is front-loaded with purpose and validation boundaries, then moves through prerequisites, refusals, redaction behavior, and workflow. It is dense but not bloated. The only cost to conciseness is the deliberate repetition of schema constraints, which is justified for clients that strip the schema but still makes the description longer than strictly necessary.

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 validation tool with one complex array parameter and an output schema, the description covers prerequisites, exact refusal conditions, redaction-sensitive behavior, runtime checks, identity-confirmation requirements, and follow-up application guidance. An agent has enough context to decide when to call it, construct valid inputs, and interpret its non-writing guarantee.

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 structural constraints, but the description adds essential runtime semantics: source_excerpt must exceed 20 non-blank characters, event_date cannot be after tomorrow, due_date must not precede event_date, identity_confirmed requires contextual confirmation, and records are capped at 20 per call. These meanings go well beyond the raw schema and help an agent construct valid 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 names a specific operation ('Validate sourced actions, interactions, objectives and state revisions against live note IDs/hashes and exact source excerpts') and clarifies what the tool produces: bounded append_journal plans, never writes. This distinguishes it from append-oriented siblings while making the tool's scope unmistakable.

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 usage context is given: existing target history headings are required, person targets need identity confirmation, and callers should use stable IDs, apply with existing writers, and verify receipts. It also distinguishes this from write tools by stating it 'never writes.' It stops short of explicitly naming sibling alternatives, so there is no direct when-to-use-versus-tool comparison.

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?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

It provides concrete usage context: how to restrict file scope with glob, the dependency on datacron index, and the fallback behavior when ripgrep is unavailable. It does not explicitly name an alternative tool like search_text, but the regex-versus-text distinction is strongly implied.

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

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

Annotations already cover 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?

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=false, openWorldHint=false). The description adds useful non-obvious context the annotations can't convey: coverage is explicit, candidates are ranked but never establish identity, and a incomplete-context warning. It stops short of describing what 'live notes' or 'write capability' look like, so the added value is moderate rather than rich.

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?

Six dense sentences with heavy domain-specific jargon ('versioned common discipline', 'known_contract_hash', 'bounded live notes'). It is front-loaded, but the phrasing is so compressed and system-specific that it reads as under-specified rather than concise; the agent expends effort decoding terms instead of acting.

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

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

An output schema exists, so return values needn't be explained, which lowers the burden. The description covers the session concept, coverage transparency, identity caution, and known_contract_hash behavior, but with 0% schema coverage and three undocumented params, plus no output or rate/pagination context, it is only marginally complete for a zero-required-param, five-parameter entry-point 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 compensate, and it partially does: it flags known_contract_hash semantics (send only when the exact contract is already in context; a match short-circuits and returns identity) and what subject does (finds ranked candidates without repairing the index). But domain, max_tokens, and note_paths get no semantic treatment, leaving three of five params undocumented.

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

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

The opening imperative 'Start memory-dependent work here' states a purpose, and the title restates it as 'Start a memory session.' However, the core action is described in abstract, system-specific jargon ('versioned common discipline', 'bounded live notes') that an agent cannot concretely map to a resource. It doesn't clearly distinguish this session-initialization tool from siblings like prepare_follow_up or get_write_progress beyond the 'start here' cue.

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?

Strong routing cues are present: 'Start memory-dependent work here' gives an explicit when-to-use, and 'Read next pages before relying on incomplete context' tells the agent not to treat a single call as authoritative. It doesn't name any sibling as an alternative, but the entry-point framing is clear enough to guide invocation ordering.

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.