seekstone

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

Annotations already indicate it's a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds valuable behavioral detail: it preserves frontmatter and is safe for 'append-only workflows,' which provides context beyond the annotations. No contradiction exists.

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 concise sentences with no filler. The core purpose is stated first, and the additional safety/use-case context is provided in a second sentence. Every phrase adds value, making it appropriately sized and 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?

For a simple append operation with three parameters, the description covers the key points: it appends, preserves frontmatter, and indicates safe workflows. However, it does not mention error behaviors (e.g., what happens if the path doesn't exist) or whether it creates a note if missing. Given the low complexity and existing 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 100%, with each parameter (path, content, prevHash) already documented in the schema. The description does not add any additional parameter-specific semantics, so it remains at the baseline score of 3 given the complete 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: 'Append text to a note body without touching the frontmatter.' This is a specific verb (append) and resource (note body), and it explicitly distinguishes itself from other mutation tools by mentioning the frontmatter preservation, which differentiates it from patch_note or replace_in_note.

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

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

The description provides context on when the tool is appropriate ('Safe for meeting notes, daily logs, and append-only workflows'), but does not explicitly mention when NOT to use it or point to alternative tools. It implies usage scenarios but lacks explicit exclusions or sibling comparisons, leaving the agent to infer the boundary.

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 all annotations false, the description carries the full behavioral burden. It adds genuinely useful guarantees ('Preserves existing frontmatter exactly') and creation-flow detail ('from template if configured'), which go beyond the raw annotations. However, it omits the most salient risk of an append operation — non-idempotency (duplicate calls duplicate content) — even though the prevHash parameter hints at concurrency concerns.

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, zero filler. The primary action leads, the scoping list follows, and the creation behavior closes. Every clause serves a distinct purpose with no 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 moderate-complexity tool with 5 simple params and no output schema, the description covers the essentials well. Gaps remain: no mention of timezone handling for date-boundary behavior (critical for 'today' defaults), no duplicate-append warning, and no interaction with prevHash conflict recovery. These are real but not fatal omissions for an append operation.

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 100%, establishing a baseline of 3. The description adds value by clarifying the createIfMissing parameter's effect ('Creates the note first (from template if configured)') and confirming its default, which is not fully obvious from the schema text alone. This is a small but genuine increment over baseline.

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 leads with a specific verb+resource: 'Append text to a periodic note' and immediately scopes it to '(daily, weekly, monthly, quarterly, or yearly)'. This clearly differentiates it from sibling 'append_note' (regular notes) and 'get_periodic_note' (read path) without needing to inspect either schema.

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

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

The 'periodic note' qualifier implies the tool's niche, and the description notes the conditional creation behavior when createIfMissing is true. However, it never explicitly points to an alternative (e.g., 'use append_note for regular notes') or states when not to use this tool, despite siblings like append_note and patch_note existing. Usage context is implied rather than stated.

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 openWorldHint=false, and the description adds substantial behavior beyond them: a hard byte budget with default, lexical-by-default retrieval, backlink/outlink expansion, and the important failure semantics (empty excerpts with confidence 'none'/'low' means no vault coverage; with folder/tag set, 'none' can mean the filter excluded everything, distinguishable via totalMatches). That is exactly the kind of edge-case disclosure 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?

Content is front-loaded — the core purpose leads, routing guidance follows, and failure semantics come last. The sentences are long and information-dense, bordering on run-on, but nearly every clause carries distinct operational value rather than 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?

With no output schema, the description carries the return-value burden and discharges it, describing the shape of results and the confidence/totalMatches signals that disambiguate empty responses. For a read-only, five-parameter retrieval tool this is complete enough to call correctly without opening the schema.

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 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains the motivation for choosing hybrid/semantic mode and clarifies that folder/tag scoping works 'exactly as in search'. It does not, however, add syntax or precedence detail for budgetBytes or folder beyond what the schema states.

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 ('Assemble everything needed to ANSWER a natural-language question in one call') and enumerates the concrete outputs (ranked excerpts, neighbor notes with summaries, follow-up source paths). It is immediately distinguishable from search and query_notes, which are named explicitly.

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

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

It gives explicit routing: 'Use search to locate notes and query_notes for metadata filters; use context_pack when you want answer-ready context without multiple round-trips.' It also tells the agent when to switch modes ('for a question phrased in words the note itself may not use, pass mode hybrid or semantic'), covering both when-to-use and when-to-use-an-alternative.

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:true annotation, the description discloses three concrete behaviors: automatic parent-directory creation, the fail-on-existing-note rule, and the prevHash compare-and-swap guard that can gate the overwrite. These are non-obvious side effects and failure modes the annotations alone do not convey. The description is consistent with readOnlyHint:false and destructiveHint:true.

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

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

Three sentences, each earning its place: the core action first, then the optional parameters, then the critical existence-failure and CAS-guard behavior. No filler and no repetition of schema 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?

For a 5-parameter destructive write with no output schema, the description covers creation, optional fields, directory auto-creation, the existence failure mode, and the overwrite/CAS guard. The one notable gap is the return contract on success — the CAS workflow implied by prevHash would benefit from knowing whether the note's contentHash is returned — but the invocation semantics are fully specified.

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 100%, so every parameter (path, content, prevHash, overwrite, frontmatter) is already documented in the input schema. The description's only added semantic is the coupling between prevHash and overwrite ('prevHash may guard the overwrite'), a small increment over the schema's per-parameter text.

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 sentence 'Create a new note at a vault-relative path' names a specific verb, resource, and scope qualifier. This cleanly distinguishes it from sibling mutators like append_note, patch_note, replace_in_note, and move_note, which all act on existing notes, and from delete_note.

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

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

The fail-if-exists clause ('Fails if the note already exists unless overwrite is true') gives the agent a clear condition for choosing the overwrite path. However, it does not explicitly route to alternatives — e.g., checking existence with list_notes first or selecting patch_note/append_note for modifying an existing note — so cross-tool selection is left 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?

Beyond the destructiveHint annotation, the description reveals critical behavior: the default action is non-permanent (trash) and reversible, and only permanent deletion requires an explicit flag. It also discloses recoverability. This transparency is essential for an agent deciding whether to call this tool and mitigates risk, going well beyond what the annotation already provides.

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 at two sentences, with the action verb first and the most important behavioral nuance immediately following. Every word contributes value, and the sentence structure flows from the core action to the key conditional. No fluff 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?

For a tool with three parameters and one required field, the description covers the essential behavior (delete, default trash, permanent override) and confirms reversibility. It does not mention error handling for missing paths or concurrency, but given the schema and annotations, the definition is complete for an agent to call it correctly. Nothing critical 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?

The schema already documents all three parameters with 100% coverage, so the description needn't add parameter details. The description's mention of 'pass permanent: true' restates the schema without adding new meaning. This meets the baseline of 3 but does not elevate it further.

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 'Delete a note', which is a specific verb and resource, and immediately clarifies the default trash behavior and the permanent deletion option. This distinguishes it from siblings like move_note or patch_note, which are about modifying instead of removing. The tool's purpose is unambiguous and immediately scoped.

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

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

The description provides clear context on how deletion works by default (to trash) and how to override it, which implicitly tells the agent when this tool is appropriate. However, it does not explicitly mention alternatives like move_note or state when NOT to use it (e.g., for reorganization). This is a slight gap in otherwise clear 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 openWorldHint=false, so the safety profile is known. The description adds the performance characteristic ('fast, pure index lookup') and the sort order. It does not describe pagination behavior, ownership, or failure modes. With annotations covering the read-only nature, a 3 is fair – it adds a bit but not extensive behavioral depth.

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: purpose, performance characteristic, and sort order. Front-loaded with the core function. No filler.

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

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

For a simple read operation with fully documented parameters (schema coverage 100%) and a clear description, the agent has everything needed to invoke it. Missing an explicit output structure, but no output schema exists impossible to know exactly, but the description mentions source line and optional excerpt, which is adequate. Could mention pagination but not critical. Score 4 because it covers the essentials.

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 100%, with each parameter described. The description adds context on the 'excerpt' (optional, ~200 chars) and the sort order, which enriches understanding of 'limit' and 'includeExcerpt'. It goes slightly beyond pure schema repetition, earning a 4.

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 ('Return'), a precise resource ('every note that links to the target note'), and the result shape (source line, optional excerpt). It implicitly distinguishes itself from sibling tools like get_links (which likely returns outgoing links) and search, making the operation 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?

The description gives contextual signals for when to use this tool: it is a reverse-link lookup backed by a pre-built index, implying it is the fast, intended path for finding inbound references. It does not explicitly name alternatives or exclusions, but the 'pure index lookup' phrasing signals it is not for full-text search or outgoing links. Slight gap: no explicit 'use X instead' 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?

With readOnlyHint true)Skip, the description adds behavioral details: marks links as resolved/unresolved, de-duplicates targets, sorts by line number. This goes beyond the annotation's safety hint, providing useful output behavior. No contradiction.

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 concise, two sentences, with key behaviors front-loaded (outgoing links) and additional details succinctly stated. No fluff.

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 simple read-only tool with a single required parameter and no output schema, the description covers what it returns and its behavior. It lacks explicit error cases or whether the note must exist, but given simplicity and annotations, it is largely 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 single parameter 'path' is fully covered by the schema (100% coverage), so the description does not need to add much. It does not describe format or errors, but the schema requirement is clear. Baseline 3 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 states it returns outgoing wikilinks and embeds from a note, which is specific and distinct from get_backlinks (incoming links). It mentions resolution, de-duplication, and sorting, but does not explicitly contrast with 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 implies it is used to inspect outgoing links from a note, but provides no explicit when-to-use or when-not-to-use guidance. Given the sibling get_backlinks, a note on when each is appropriate would be helpful. The description does not mention the note must exist or prerequisites.

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 readOnlyHint=false and destructiveHint=false, so the description correctly adds that the tool may create a note when createIfMissing is true – a behavioral detail beyond the annotations. It also discloses the config file locations (.obsidian/daily-notes.json and plugin data.json). No contradictions. However, it does not describe the exact return shape or failure modes, which are minor gaps given the side‑effect 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?

Two sentences with no filler. The primary purpose ('Get the path and existence status') is front‑loaded, followed by config sources and the optional creation behavior. 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?

Since there is no output schema, the description conveys that the return includes 'path and existence status', and it explains the config‑reading logic and optional creation. This is sufficient for an agent to call correctly. It lacks explicit error cases or what happens after creation (e.g., returns path or just status), but the core information is present.

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

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

Parameter schema coverage is 100% – all three parameters (date, period, createIfMissing) already have descriptions in the schema, including defaults. The description adds no new semantic meaning beyond restating the defaults ('Defaults to today', 'Default: daily', 'Default false') which are already present. Baseline 3 applies because the schema carries the weight.

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: 'Get the path and existence status of a periodic note' and enumerates the period types (daily, weekly, monthly, quarterly, yearly). This clearly distinguishes it from sibling tools like create_note or append_periodic_note, even though it never names them. The purpose is 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 explains what the tool does and mentions the optional creation side‑effect, but never explicitly states when to use this tool versus a sibling like create_note or append_periodic_note. It gives context (reads config from specific files) but no when‑to‑use or when‑not‑to‑use guidance, leaving the agent to infer suitability.

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 openWorldHint=false, covering the safety profile. The description adds nothing beyond that – no ordering, return format, or pagination behavior – so it contributes no behavioral 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?

A single efficient sentence with the primary action front-loaded and no waste. It is appropriately sized, though its brevity leaves the gaps noted above unfilled.

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 list tool with no output schema and fully documented parameters, the description covers the essentials. It is adequate but should do more to distinguish this listing tool from its query/search siblings.

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 100%, so tag, limit (default 100, range 1–500), and folder are all documented in the schema. The description only gestures at folder/tag filtering and omits limit, adding no syntax or format detail. Baseline 3 applies.

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 ("List notes") plus its filter scope, so an agent knows what it does. However, it does not differentiate from overlapping siblings like search, query_notes, or read_notes, so it falls short of the top band.

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 phrase "optionally filtered by folder prefix or tag" hints at usage but gives no when-to-use, when-not, or named alternatives. An agent choosing between this and query_notes/search gets no routing guidance.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds useful behavioral details—that all tags are returned, filtering behaviors, and that nested tags include a parent field—which goes beyond the annotation's minimal information.

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 concise sentences deliver the purpose, options, and a notable output feature with zero redundancy. Front-loaded with the primary action and immediately informative.

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 list tool with no output schema, the description covers the return contents (usage counts, parent field for nested tags) and behavioral parameters fully. No gaps are apparent for an agent to invoke it correctly.

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

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

The schema covers all parameters with descriptions (100% coverage), so the description adds no significant new meaning about inputs. It merely reiterates what the schema already specifies, meeting the baseline but not exceeding it.

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?

Describes a specific action ('List all tags in the vault') with clear scope and distinguishes itself from siblings by focusing solely on tags. The mention of usage counts and nested tags further specifies the tool's unique function.

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?

While it doesn't explicitly contrast with alternatives, there is no other tag-listing tool among siblings, making the purpose self-evident. It provides clear context but omits explicit exclusions or when-to-use guidance beyond its self-description.

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, and the description reinforces that by promising metadata rows and explicitly stating 'never note content.' It adds value beyond the annotation by disclosing the exact fields returned (seq, timestamp, tool, paths, undoable) and explaining the pre-image journaling mechanism that makes undo_write 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?

Two tight sentences front-load the main purpose, then add the key behavioral constraint and output shape. Every sentence earns its place, and there is no redundant repetition of the tool name or 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?

Despite having no output schema, the description explicitly lists the returned fields and their nature, so an agent knows what response to expect. Combined with full schema coverage for optional parameters, this is complete enough for a low-complexity list tool.

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

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

Schema coverage is 100%, with both path and limit already described in the input schema. The tool description does not need to repeat parameter details; it adds context about the journal concept but no additional parameter-level semantics. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 action ('List recent writes') and the resource ('the journal'), making the tool's purpose immediately obvious. It also distinguishes this from content-focused tools by explicitly noting it returns metadata and never note content, which separates it from siblings like list_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 provides clear context: this tool is for reviewing write operations and identifying entries that can be reverted with undo_write. It does not explicitly say 'use this instead of list_notes' or list exclusions, but the connection to undo_write and the metadata-rows framing gives enough context for an agent to choose it appropriately.

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 concrete behavioral traits: it rewrites wikilinks and markdown links in other notes while leaving fenced code blocks untouched, auto-creates parent directories, and fails if the destination exists unless overwrite is true. This is rich, actionable context that goes well beyond the annotation and helps an agent anticipate side effects.

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 concise sentences, front-loaded with the primary purpose, followed by critical behaviors (link rewriting, directory creation, overwrite failure). No filler — 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?

For a mutation tool with 5 parameters and no output schema, the description covers the main side effects (link rewriting, directory creation, failure conditions) and explains the overwrite and rewriteLinks parameters behaviorally. The prevHash guard is documented in the schema but not in the description; however, the agent can infer it from the parameter description. Given the complexity, this is complete enough 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 100%, so each parameter already has a clear meaning. The description adds context around rewriteLinks (rewriting links in other notes) and overwrite (failure behavior) but does not add new information for from, to, or prevHash beyond the schema. It sits at the baseline of 3 because the schema carries the parameter explanation.

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 'Move or rename a note to a new vault-relative path' — a clear verb, resource, and target location. It explicitly describes the link-rewriting side effect, distinguishing it from destructive delete_note and heading-renaming rename_heading.

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 conveys when to use the tool (moving/renaming notes) and details the overwrite and link-rewriting behavior. It does not explicitly name alternative tools, but the purpose is unambiguous given the sibling list; this falls short of a perfect 5 that requires explicit when-not/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 the description adds meaningful behavioral context: it returns only structural data (headings, offsets, anchors, frontmatter keys) and explicitly excludes prose. It also signals a performance advantage ('fraction of the cost'), which is not in the annotations. No contradiction.

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 sentences with zero wasted words. The most critical information (what it returns and what it excludes) is front-loaded, and the usage guidance is packed efficiently into the second 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?

The description fully covers the return value (heading tree, offsets, anchors, frontmatter keys), the exclusions (no prose), and the usage context (before reads/patches). With only 3 well-documented parameters and read-only annotations, nothing essential is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description doesn't add extra semantics to the parameters beyond what the schema already states, but it does clarify the overall output context (e.g., 'frontmatter key list' implies what includeFrontmatter might do). No compensation needed.

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 ('Return') with a precise resource ('a note's structure') and enumerates the components (heading tree, offsets, block-reference anchors, frontmatter key list). It clearly distinguishes from siblings like read_note by explicitly saying 'without returning any prose,' so an agent knows exactly what it gets.

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 before section reads or patches to discover what sections exist at a fraction of the cost of reading the full note.' This tells the agent the ideal scenario and why it's preferable to full reads, effectively excluding alternatives like read_note.

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 discloses important behavioral traits: it preserves key ordering and quote style, and explicitly explains that null values delete keys. These details go beyond the annotations (readOnlyHint=false, destructiveHint=true), which only indicate mutation and destructiveness. It adds useful context without contradiction.

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 a single, front-loaded sentence that states the core action, key guarantees, and deletion semantics. No filler or repetition; every clause adds value.

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

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

The description covers the essential behavior, deletion semantics, and safety guarantees. It does not mention error cases like hash_conflict, but those are captured in the schema. It also omits prerequisites (e.g., note must exist), but given the simple tool and existing schema, the description is near-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 100%, so the schema already documents all three parameters. The description repeats the null-deletion behavior for the patch parameter, which is also stated in the schema, and adds no new semantic information beyond what is structured. Thus baseline 3 applies.

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: setting, updating, and deleting frontmatter keys. It specifies the resource (frontmatter keys) and includes a concrete behavioral guarantee (preserving key order and quote style), which distinguishes it from sibling tools like patch_note that modify note content.

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?

No guidance is provided on when to use this tool versus alternatives such as patch_note or replace_in_note. The description gives no context on selection criteria, exclusions, or comparative advantages beyond the formatting guarantee.

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

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

Annotations already declare destructiveHint=true, so the mutation nature is known. The description adds valuable behavioral context beyond annotations: edits are surgical and localized ('without rewriting the whole file'), and frontmatter is never touched. This meaningfully clarifies the blast radius of a destructive operation.

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 filler. It front-loads the core purpose and operation model, then adds a key safety guarantee. 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?

For a mutating tool with rich schema coverage and annotations, the description covers the essential behavior: targeted section editing, operation types, and frontmatter safety. It could mention failure behavior for missing targets, but the schema already covers createIfMissing and prevHash behavior.

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 100%, so the input schema already documents all six parameters thoroughly. The description restates operation semantics in prose but does not add meaning beyond the schema, so the baseline of 3 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 states a specific verb ('Surgically edit'), a resource ('a section of a note'), and a precise targeting mechanism ('targeted by heading or block reference'). It also distinguishes itself from sibling tools by noting 'without rewriting the whole file' and 'Frontmatter is never touched'.

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 this tool is appropriate: surgical section edits with append, prepend, or replace operations, and explicitly excludes frontmatter. It does not name sibling alternatives like patch_frontmatter or append_note, but the scope and exclusion are enough to guide selection.

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 readOnlyHint=true and openWorldHint=false, so safety is already covered. The description adds real context beyond them: the return shape (compact rows, path + title by default, more only via select) and the negative statement that note content is not returned. It does not discuss pagination or result-count limits beyond what the schema's limit already says.

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, zero padding, front-loaded with what it queries and immediately followed by what it returns and when to prefer it. Every clause 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?

No output schema exists, so the description must explain return values, and it does precisely: compact path+title rows by default, expanded via select, no note content. Combined with 100% schema coverage and read-only annotations, nothing needed to call this 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 description coverage is 100%, with per-parameter docs including operator semantics and tag nesting, so the schema carries the load and the baseline is 3. The description only restates the filter categories and hints at select, adding no format or syntax detail beyond 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?

States a specific verb and resource (structured metadata query over notes) and enumerates the filter axes: frontmatter predicates, tag, folder, modified time, size. It also names the sibling it is not (search) and the axis that separates them, so an agent can disambiguate without opening either schema.

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

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

Explicitly says "Use this instead of search when filtering by properties rather than text," naming both the alternative and the selecting condition. That is exactly the when-to-use/when-not guidance a routing decision needs.

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

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

Beyond the readOnlyHint annotation, the description discloses the exact JSON return shape (content, bytes returned, total note size, contentHash) and the hash's purpose for compare-and-swap with edit tools. This behavioral context is not captured in annotations and is valuable for the agent.

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: first states the operation and modes, second the return value, third the usage context. It is front-loaded with the core purpose and contains zero wasted words, making it efficiently structured.

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 5 parameters, a nested object, and no output schema, the description covers the return structure, the purpose of contentHash, and the prerequisite discovery steps. An agent has everything needed to call the tool correctly and understand its output without ambiguity.

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 fully describes all five parameters (100% coverage), so the description adds no extra parameter meaning. The mention of block reference and line range merely echoes schema descriptions; no new semantics are introduced, so the baseline of 3 applies.

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 (read) and resource (note or span), enumerates three selection modes (heading section, block reference, line range), and distinguishes it from siblings like outline_note and search by its read-only content-return focus. The purpose is unambiguous and the description clearly differentiates the 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?

Explicitly tells the agent to use search or outline_note first to find the path and section names, and explains the contentHash is to pass as prevHash to edit tools for compare-and-swap. This provides clear when-to-use guidance and ordering, effectively routing the agent to the correct prerequisite tools.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses budgetBytes truncation semantics (fair-share cut, truncated: true, noteBytes retained for continuation), per-item error isolation ('a failing item returns its own error without failing the batch'), and that contentHash is always the whole-file hash usable as prevHash. These are non-obvious behaviors an agent could not derive from the schema.

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

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

Front-loaded with purpose, then batching rationale, then budget/truncation behavior, then error isolation and contentHash. Four dense sentences with no filler; each one carries information an agent needs.

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?

No output schema exists, yet the description compensates by describing the return contract (same fields as read_note, in request order, truncated flag, noteBytes, contentHash). Combined with rich budget/error semantics, an agent has everything needed to call it correctly and handle partial results.

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 100%, so the baseline is 3, but the description adds real meaning: the default value and unit of budgetBytes, its truncation behavior, and the cross-item semantics ('each item takes the same options as read_note'). It does not restate the per-field span options, which the schema already handles well.

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

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

States a specific verb+resource with explicit batch scope: 'Read up to 20 notes (or spans of them) in one call instead of repeated read_note calls.' This immediately distinguishes it from the sibling read_note by cardinality and by naming the upstream tools whose output feeds it (search, query_notes, list_notes, get_backlinks).

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 names when to use it (bulk-fetching top hits from search/query_notes/list_notes/get_backlinks) and routes the agent to the alternative for follow-up ('read the rest with read_note'). Both the when and the fallback path are stated, not inferred.

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?

Despite having annotations, it adds valuable context about case-insensitivity, first-match-wins on duplicates, and skipping code blocks. It doesn't contradict 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 dense sentences pack a lot of precise information: what it does, how it works (warm backlink index), and key edge-case behaviors. No fluff.

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 rename operation, it covers the mutation, the link rewriting, the index source, and important resolution semantics. It could elaborate on return values, but the description is comprehensive for typical usage.

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 100% schema coverage, the schema already documents each parameter. The description adds value by explaining the exact behavior of heading matching and what happens with the prevHash guard.

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 renames a heading and rewrites links and embeds across the vault, which distinguishes it from simple rename or edit tools. It mentions specific behavioral nuances like alias preservation and ignoring fenced code blocks.

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 implies this tool is for renaming headings specifically, not for other edits, and mentions how it handles duplicate headings. It doesn't explicitly mention alternative tools, but the context is clear for when to use this over a generic edit tool.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the write nature is known. The description adds valuable behavioral context beyond that: it clarifies that frontmatter is never affected (scope of mutation) and recommends dryRun for previewing. It does not discuss failure modes like hash_conflict, but the schema documents that, and the bar is lower given the annotation coverage.

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 fluff. The core purpose is front-loaded, and the supporting details (feature list, frontmatter exclusion, dryRun tip) follow in a logical order. Every sentence earns its place, and nothing is redundant with the schema.

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 9 parameters and no output schema, the description could do more to explain return values or error conditions. It does not mention what the tool returns on success (e.g., count of replacements, updated content) or how it reports failures like hash_conflict or note-not-found. The schema and annotations cover some aspects, but the lack of output guidance leaves a gap for a mutation tool of this complexity.

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 100%, so all 9 parameters are individually documented. The description adds only a high-level summary of capabilities ('Supports literal and regex search, case sensitivity, whole-word matching, and a replacement limit') and a tip about dryRun, but this does not meaningfully augment the schema, which already explains each parameter's semantics. Thus, baseline 3 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 states the resource and action: 'Find and replace text within a note body.' It goes beyond a simple verb by listing supported features (literal/regex, case sensitivity, whole-word, limit) and explicitly excludes frontmatter, which distinguishes it from sibling tools like patch_frontmatter or append_note. An agent can immediately understand what it does without needing to inspect 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?

The description provides clear context: it is for body text replacement, and explicitly states 'Frontmatter is never touched,' which serves as a when-not-to-use boundary. It also advises using dryRun to preview before writing, which is a concrete usage tip. However, it does not name any alternative sibling tools, so it stops short of a full 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real behavioral context beyond them — excerpt size (~120 chars, tunable), fuzzy and prefix matching, and the environment-variable gate on semantic mode. It stops short of describing ranking behavior or whether results are paginated.

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, front-loaded with the core verb and result shape, then the matching capabilities, then the conditional semantic mode. No filler and nothing repeated from the schema.

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 no output schema, the description carries the return-value burden and does so well (ranked excerpts, approximate length, tunability), and it covers all six parameters indirectly. Minor gaps remain around result ordering/ranking guarantees, but an agent has enough to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: excerptLength is framed as the tunable knob that controls context cost, and semantic/hybrid mode is tied to a required environment flag. These are genuine additions rather than restatements.

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

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

States a specific verb and resource ('Full-text search across the vault') and immediately characterizes the result type ('ranked excerpts — not full notes'), which distinguishes it from content-returning siblings like read_notes, read_note and query_notes without opening their 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?

The 'not full notes — to minimise context usage' framing implies when to prefer this over read_notes, and the semantic/hybrid modes come with an explicit precondition (SEEKSTONE_SEMANTIC=1). However, no sibling tool is named directly and no explicit when-not guidance is given, so the agent must infer the routing.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds substantial behavioral detail beyond that: byte-identical restoration, whole-operation restoration for multi-file changes, handling of permanent deletes, the undo_conflict guard, the effect of force, and the fact that the undo is itself journaled and can be undone to redo. This is exemplary disclosure of side effects and edge cases.

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 carries necessary information, and key facts are front-loaded: what the tool does, how it handles tricky cases, then defaults and conflict behavior. Despite covering complex semantics, the description remains compact and well-ordered 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?

Given that there is no output schema, the description still tells the agent everything needed to invoke the tool correctly: default target, failure mode, force escape hatch, permanent-delete restoration, and redo possibility. The reference to list_writes in the schema completes the workflow 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?

Schema coverage is 100%, so the baseline is 3. The description reinforces the schema's default behavior for seq and explains the force semantics, but it does not add significantly new parameter-level information beyond what the input schema already provides. The description's added value is mostly behavioral, not parameter-specific.

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: 'Revert a journaled write' and precisely defines the effect ('restores every file it touched to its byte-identical pre-write state'). It also distinguishes the tool's scope by giving concrete examples like multi-file moves, heading renames, and permanent deletes, leaving no ambiguity 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?

The description gives clear operational guidance: it defaults to the most recent undoable write, explains the undo_conflict refusal condition, and clarifies how force:true changes the behavior. While it does not explicitly state 'use list_writes to find a seq,' the schema parameter references list_writes, and there is no competing sibling tool for undo operations, so the context is clear enough.

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