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?

The description adds significant behavior beyond the readOnly/destructive annotations: closed records are hidden by default, history remains intact, legacy prose is not parsed, and source freshness is not revalidated. No annotation is contradicted; the openWorldHint=false applies within the canonical-note scope, while the caveat warns about commitments outside that scope.

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 the purpose first, followed by behavioral limits and routing guidance. Every clause contributes useful information with 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?

With an output schema present, return-value description is unnecessary. The definition covers scope, default filtering, hidden history, legacy parsing limits, freshness, and the correct sibling for alternative use, making it fully actionable.

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 context. 'Explicit canonical notes' defines what note_paths should reference, and 'Completed/cancelled records are hidden by default' matches include_closed's default. It does not name the parameters, but their names are self-explanatory and the semantics are reasonably covered.

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

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

The description states a precise verb and resource: 'Read latest structured follow-up revisions in explicit canonical notes.' It also distinguishes the tool from get_note, which handles legacy notes and original evidence, so an agent can select it correctly without opening sibling schemas.

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

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

It explicitly defines when to use the tool (structured follow-ups in canonical notes) and when not to ('Use get_note for legacy notes and original evidence'). The caveat that absence is not proof adds a clear decision rule against over-interpreting empty results.

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?

Annotations already mark this as read-only (readOnlyHint=true), but the description adds substantial behavioral detail: chunk_id returns format='chunk' with sandbox-wrapped body, parent-hash mismatch returns a stale-chunk error, chunk reads ignore offset/limit, and format='full' paginates by character range. This goes far beyond the annotations.

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

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

The description is dense but well-structured: purpose, id forms, chunk behavior, then full/map behavior. Every sentence earns its place, and semicolons keep related ideas together. It is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity and the presence of an output schema, the description covers all necessary aspects: input types, format behaviors, pagination, and error conditions. It leaves no ambiguity about what to expect, making it complete for effective tool use.

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%, but the description compensates fully. It explains the meaning of id_or_path (ULID, chunk_id, path), the format enum values (full, map, chunk), and clarifies that offset/limit page by character range in full format and are ignored for chunk reads. This adds significant meaning 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 function: 'Fetch the full context behind a search hit' and 'Fetch a single note by its ULID, indexed chunk_id, or vault-relative path.' This is a specific verb+resource that distinguishes it from siblings like search_text or get_note_history.

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

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

The opening sentence gives clear usage context: use this before answering from a snippet alone. It also provides guidance within the tool, such as using format='map' as a 'cheap to scan' option. However, it does not explicitly name sibling alternatives or state when not to use this tool, so it misses the full 'when/when-not' explicit guidance.

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

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

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

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?

Beyond the readOnlyHint and destructiveHint annotations, the description adds important behavioral context: validation is structural, not a truth verdict; existing headings are required; person targets require identity confirmation; and results are bounded plans, not writes. This gives the agent a genuinely accurate mental model.

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

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

Five dense sentences, each adding real value: scope, prerequisites, identity caveat, non-writing behavior, and follow-up workflow. Information is front-loaded and there is 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?

Given the output schema exists and annotations cover the read-only safety profile, the description is complete enough for safe and correct invocation. It covers preconditions, identity handling, output type, and post-invocation steps like verifying receipts.

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

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

Schema description coverage is 0%, so the description must compensate. It does provide key conceptual guidance: use stable record/revision IDs, compare against live hashes and exact source excerpts, and confirm identity for person targets. However, it does not meaningfully explain the richer nested fields like status, due_date, event_date, or previous_revision, leaving some semantics to 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 names a specific verb ('Validate') and a specific resource ('sourced actions, interactions, objectives and state revisions') and makes the output explicit: 'Returns bounded append_journal plans, never writes.' This clearly distinguishes it from writer tools like append_journal and readers like get_follow_up.

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

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

The description gives clear preconditions: existing target history headings are required, person targets need identity confirmation, and homonyms should be clarified first. It also states when not to use it ('never writes') and instructs to apply generated plans with existing writers, though it does not name the specific sibling tools to use.

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 declare readOnlyHint and destructiveHint, so the safety profile is known. The description adds valuable behavioral context: output is ranked, sandbox-wrapped, highlighted, resolved to indexed chunks, and depends on external binaries. It does not mention pagination or limit behavior, but the output schema exists to cover return details.

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 concise sentences front-load the core purpose and then add essential details. Every phrase earns its place—output format, scoping, and prerequisites—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 presence of an output schema and read-only annotations, the description covers purpose, output characteristics, glob scoping, and external dependencies. It is sufficiently complete for an agent to correctly invoke and interpret results. The only minor gap is limit semantics, but the schema default mitigates that.

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 glob ('Restrict file scope') and pattern implicitly via 'Regex search', but limit is not mentioned at all. The schema provides the default and type, but not the meaning. This partial coverage leaves limit semantics 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 description opens with 'Regex search via ripgrep', a specific verb+resource statement that clearly differentiates this tool from sibling search_text. It further specifies the output format (ranked sandbox-wrapped match lines with term highlighting) and the prerequisite tools, leaving no doubt about what the tool 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?

It provides clear usage context: it is for regex search, file scope can be restricted with glob, and it requires rg and datacron index. It does not explicitly name alternatives or state when not to use it, but the purpose is distinct enough that no exclusion is necessary.

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 annotations (readOnlyHint=true, destructiveHint=false), the description adds critical behavioral context: requires `datacron index` to have been run first, demotes superseded notes by default, and explains the include_superseded flag. It also discloses the output format (ranked sandbox-wrapped snippets with term highlighting). This goes well beyond what annotations alone 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 four sentences, front-loaded with the key usage directive ('First stop...'), and every sentence adds value. No redundant or filler content.

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 a search tool: it covers the prerequisite (indexing), default behavior (superseded demotion), a key option (include_superseded), and output characteristics. An output schema exists to formalize the return structure, so detailed return values don't need to be in the description. It also provides enough context to differentiate from sibling search tools.

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 include_superseded and its default behavior, but does not explain `query` or `limit` beyond their existence in the schema. Since `query` is self-explanatory and `limit` has an obvious default, partial compensation is present, but it's not complete.

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

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

Description clearly states it performs full-text BM25 search over the user's notes, with a specific verb (search) and resource (FTS5 index). It also positions itself as the 'first stop' for questions, distinguishing it from siblings like search_regex by emphasizing it as the default search 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?

Provides clear when-to-use guidance ('First stop for any question... search before saying you do not know'), indicating it should be the initial tool. However, it does not explicitly mention alternatives such as search_regex or specify when not to use it, so it lacks 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 already mark this as destructive, but the description goes beyond that by listing exactly which fields change, noting the body is preserved, and mentioning the automatic updated timestamp. It also reveals the invalidation convention that keeps history queryable, which is valuable behavioral context not available from annotations alone.

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

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

The description is tightly packed and front-loaded with the primary use case. Every sentence adds useful guidance or behavioral scope, and the field list is precise without being bloated.

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

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

For an 11-parameter tool with zero schema descriptions, this is a solid but incomplete definition: the core lifecycle workflow is well covered, yet several parameters remain unexplained in terms of accepted formats or vocabularies. The output schema exists, so missing return-value documentation is less of a concern, and the destructive scope is clearly bounded.

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 documenting parameters. It explains the lifecycle meaning of invalid_at/invalidated_by, the 'option -- reason' format for rejected, and the list of mutable fields. However, it leaves expected_hash, request_id, confidence values, origin values, and date formats undefined, so some parameters still lack usable 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 states a specific verb and resource: 'Update frontmatter fields on an existing memory note,' and it names the exact lifecycle triggers. It distinguishes itself from siblings like patch_note_section by limiting scope to frontmatter and enumerating the fields it affects.

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 when to use the tool ('when a fact's lifecycle changes') and gives a strong preference rule: invalidate outdated facts rather than deleting or rewriting them. It does not explicitly name sibling alternatives for body edits, but the claim that the Markdown body is preserved implies that boundary.

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