Engram Obsidian Memory Sync

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds real context beyond them: existing content is preserved, a missing note is created with a title line, and frontmatter is skipped when prepending. It does not discuss separator/newline handling or conflict behavior, though base_hash conflict semantics live in 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?

Five short sentences, front-loaded with the core action and immediately followed by the auto-create side effect, then positioning, then sibling routing. No filler or redundancy.

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

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

An output schema exists and the input schema is fully documented, so return values and parameter detail are covered. The description addresses the two things an agent could get wrong (auto-creation, prepend vs append). The small remaining gap is whether a separator is inserted between existing and new text.

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 restates position ("start to insert at the top, after any frontmatter"), which largely duplicates the schema enum description, and says nothing about vault_id or base_hash beyond what the schema already documents.

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 ("Add text to the end of a note") plus the key semantics (existing text kept, note auto-created with a `# <name>` title). It explicitly distinguishes itself from edit_note and write_note, so an agent can route correctly without opening the schema.

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

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

Gives positive guidance (logs, journals, running lists), an in-tool alternative (position=start for prepending), and names both competing siblings with the exact condition that selects them (edit_note to change existing text, write_note to replace the whole note). No inference required.

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 idempotentHint=true and destructiveHint=false, so the description's idempotency sentence mostly restates structured data; the added value is only the observable detail that an existing name 'succeeds without creating duplicates.' It says nothing about permissions, error behavior, or whether parent segments of a path are auto-created.

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 short sentences, each doing distinct work: purpose, usage, idempotency. The core purpose is front-loaded with zero 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?

An output schema exists and the vault_id parameter is fully specified in the schema, so the description need not cover returns or vault targeting. The one material gap is whether a nested path like 'Projects/Active' implicitly creates 'Projects', which matters for a path-based folder 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%, so both parameters are already documented, including the vault_id multi-vault rule, which the description does not touch. The description's phrase 'existing folder name' is slightly looser than the schema's 'Folder path, e.g. "Projects/Active"', adding no real semantics 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+resource ('Create an explicit empty folder') and scopes it to 'the personal knowledge base.' It implicitly distinguishes itself from create_note and suggest_folder via 'explicit empty folder,' but never names a sibling, so differentiation is left to inference.

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

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

'Use to scaffold folder structure before placing notes' gives a concrete when-to-use context. It does not, however, mention alternatives (e.g. suggest_folder for discovering names, list_folder for checking existence) or any when-not-to-use condition.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds genuinely new behavior: automatic path resolution and a hard fail-on-existing rule, which is the key information an agent needs before retrying a failed call. It stops short of saying what the failure looks like or how the resulting path is chosen.

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 short sentences, front-loaded with the core action, then the folder default, then the overwrite guarantee. No filler or restatement of the title.

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

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

An output schema exists and vault scoping is fully documented in the schema, so the description only needs to cover the non-obvious create semantics, which it does. Minor gap: it doesn't clarify whether the automatic folder choice can be influenced or what happens when no folder matches.

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 raises it slightly by explaining the consequence of omitting suggested_folder (automatic placement), which the schema does not state. The vault_id semantics are left entirely to a well-written schema entry, which is fine.

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 ('Create a new note') plus the non-obvious scope detail of automatic folder placement. It does not name the closest siblings (write_note, edit_note, append_to_note), so the agent must infer why create_note is preferred over write_note for a new file.

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 a usable condition ('If suggested_folder is omitted, the note is placed automatically') and a failure condition ('fails if a note already exists at the resulting path'), but never says when to choose this over write_note or edit_note, which is the most likely selection mistake given the sibling list.

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 destructiveHint=true and idempotentHint=true annotations: it discloses soft-delete-to-trash semantics, the 7-day Free / 30-day paid retention window, that downgrades shorten an existing window, that the response reports the expiry, and that the delete syncs to all connected Obsidian devices. This is exactly the extra context the annotations cannot convey.

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

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

Front-loaded with the action and resource, and every clause carries information (retention windows, sync behavior, no-op result, sibling routing). The single long sentence chain is dense but not padded; minor readability cost from cramming several behaviors into one paragraph.

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 (so return shape need not be explained) and annotations covering the safety profile, the description still supplies the retention, sync, and no-op semantics an agent needs to plan a follow-up restore or avoid a false failure. Nothing material is missing for a two-parameter destructive tool.

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

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

Schema description coverage is 100%, so both path and the vault_id targeting rule (required for multi-vault owners, no server-side active-vault state) are already fully documented. The description only reinforces that deletion is keyed by path and adds no syntax or format detail beyond the schema, so 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 (delete) and resource (a single attachment) plus the qualifying file types, and explicitly excludes notes and folders by naming the sibling tools. An agent can distinguish it from delete_note and delete_folder without reading 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 routes to delete_note for notes and delete_folder for whole folders, and covers the edge case of a nonexistent path (succeeds with deleted: false). The backup/restore window is stated with the exact plan-dependent durations, which tells the agent when restore_deleted remains viable.

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 destructive/idempotent annotations, the description discloses that non-empty folders are refused with counts, that recursive removes everything beneath, that deletions go to trash, and that restorability is 7 days on Free and 30 on paid plans, subject to the plan at deletion time. It also notes device syncing and that the result reports the expiry. This is rich, non-obvious behavioral context.

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

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

The description is front-loaded with the core action and default behavior, and every sentence carries operational information. The retention/plan detail is somewhat dense but relevant to an agent deciding whether deletion is recoverable.

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 annotations already mark the tool destructive and idempotent, and an output schema exists, the description covers everything an agent needs: default refusal behavior, recursive consequences, trash/restore semantics, plan-dependent retention, and sync effects. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline would be 3. The description adds real meaning to `recursive`: it explains the default empty-only refusal and the consequence of passing true. It doesn't add further detail about `vault_id` or folder path semantics beyond the schema, but the behavioral implication of the recursive flag is a meaningful addition.

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

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

The first sentence names a specific verb and resource ("Delete a folder"), and the rest precisely scopes the operation: empty-only by default, recursive optionally. This clearly distinguishes it from sibling tools like delete_note, delete_attachment, and rename_folder.

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 states the default empty-only behavior, the condition for using recursive: true, and the recovery path via restore_deleted. It doesn't compare against other deletion siblings or explain when to delete contents first instead, but the core usage decision is explicit.

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

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

Annotations declare destructive/idempotent but the description carries the real behavioral payload: deletion is reversible via restore_deleted, retention is 7 days on Free and 30 on paid, the window follows the plan at deletion time and can be shortened by a downgrade, the result reports the deadline, and the change syncs to all connected devices. It also discloses the non-obvious edge case that deleting a path with no note succeeds with deleted: false, which prevents an agent from retrying or treating it as an error.

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 operation and its restorable-trash semantics are front-loaded, followed by edge case and then a compact block of sibling routing. Every sentence supplies distinct information — retention, sync, no-op success, or an alternative tool — 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?

An output schema exists, yet the description still surfaces the two return facts an agent most needs (the recovery deadline and deleted: false). Combined with retention policy, cross-device sync, and sibling disambiguation, nothing needed to call this destructive tool safely is absent.

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% and vault_id already documents the multi-vault requirement in detail, so the baseline is 3. The description still adds meaning about the path parameter that the schema does not: a path holding no note is a valid, successful call that returns deleted: false, which tells the agent how to interpret path resolution failures.

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

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

States a specific verb and resource with scope ('Delete one note by path') and immediately clarifies that it is a soft delete to trash. Explicitly distinguishes itself from delete_folder, rename_note, and delete_attachment, so an agent can separate it from its closest siblings without opening a schema.

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

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

Names three alternatives with the exact condition that should route to each: 'To remove a whole folder use delete_folder', 'To move a note instead use rename_note', 'For an image, PDF, or other binary file use delete_attachment.' When/when-not guidance is fully explicit rather than 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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds genuinely new behavioral facts: the operation is atomic and "fails without writing" under three specific conditions, insert_section preserves existing content, and base_hash produces a version_conflict requiring a re-read. It does not discuss partial matches within a section or how replace_section treats subsections' content beyond 'everything under one heading'.

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

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

Front-loaded with the core action, then modes, then failure conditions, then sibling routing. Four sentences, each carrying distinct load, with no restatement of the title or schema boilerplate.

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

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

For a 12-parameter mutation tool with an output schema and full schema coverage, the description covers the risky parts an agent cannot infer: atomicity, the three failure conditions, version-conflict recovery, and mode selection. Return values are delegated to the output schema, which is appropriate.

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 baseline is 3, but the description adds cross-parameter semantics the schema states only per-property: it explains the mode-to-parameter coupling (which of find/replace/heading/content/position apply in each mode) and that replace_text targets the first occurrence by default. This meaningfully reduces the chance of passing parameters under the wrong mode.

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 ("Change part of an existing note") and immediately enumerates the three modes with the exact operation each performs. It explicitly distinguishes itself from append_to_note and write_note, so an agent can route between the three write-path siblings without opening any schema.

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

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

Gives explicit exclusions with named alternatives: append_to_note for top/bottom-of-note additions and write_note for whole-note rewrites. The mode sentences also imply the when-to-use split between exact-text edits and heading-scoped edits.

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 annotations: discloses file-type restriction (no executables), plan-dependent caps, credential reuse, two transfer protocols with the max_body_bytes switchover point, and that payload bytes bypass the tool. The one gap is that readOnlyHint=false implies a side effect, yet the description frames this purely as a 'get' with no mention of what the non-read-only aspect is.

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, front-loaded with what is returned and immediately followed by the 'no bytes pass through' clarification and the protocol choice. Every sentence carries information; the parenthetical about executables and the closing 'call before uploading' are both load-bearing.

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 pre-flight discovery tool with an output schema (so return shape needn't be restated) and one well-documented optional parameter, the description covers purpose, limits, protocol choice, and file-type constraints. Only the meaning of the non-read-only annotation is left unaddressed.

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% and the vault_id property already documents the name-or-UUID form, multi-vault requirement, and the list_vaults fallback. The description never mentions vault_id or vault scoping, so it adds nothing over the schema for the sole parameter; 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?

Specific verb+resource: it returns the endpoints and account limits needed to upload an attachment, and explicitly states 'The bytes do not pass through this tool.' That negative scoping cleanly separates it from the write-oriented siblings (write_note, append_to_note, move_attachment) that an agent might otherwise confuse it with.

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?

'Call before uploading to learn the size cap and which file types the plan allows' gives a clear trigger condition and decision context. It also tells the agent what to do with the result (send the file itself, raw request vs. resumable parts above max_body_bytes). No explicit 'when not to use' or named alternative exists, and none of the siblings competes for this job.

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 read-only, idempotent, non-destructive behavior, and the description adds useful operational context beyond them: missing paths are reported inline, outline returns headings only, section limits reading to one heading, and include_links adds backlinks/outgoing/unresolved links. No annotation contradiction is present.

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

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

The description is front-loaded with the core batch-read purpose, then adds single-note use, workflow context, and token-saving modes. Every sentence contributes useful selection or invocation guidance with no obvious filler.

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

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

Given an output schema, rich annotations, and full parameter coverage, the description is complete for correct tool selection and invocation. It covers batching limits, single-note behavior, missing paths, folder inventory flow, and optional return-shaping flags.

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 schema already documents paths, outline, section, vault_id, and include_links. The description reinforces and clarifies these parameters but adds little meaning beyond the structured schema, making the baseline 3 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 names a specific verb and resource: retrieving full note content, with clear batch scope (1-20 paths) and single-note behavior. It distinguishes the tool from siblings by positioning folder inventory as list_folder then get_notes and batch reads as consuming search results.

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 clear usage contexts: inventorying a folder, reading a batch of search results, and reading one note. It also presents outline and section modes as token-saving alternatives. It does not explicitly state when not to use this tool, so it falls short of fully 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?

Annotations already declare this a read-only, idempotent, non-destructive, closed-world operation, so the safety burden is carried structurally; the description adds useful behavioral context about what a scan yields (kinds, counts, ranges). It stops short of disclosing enumeration limits — e.g. whether the "most used values" list is capped or truncated for high-cardinality fields.

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, front-loaded with the purpose before the workflow guidance, with no filler. The first sentence is a long comma-delimited enumeration, which is dense but each clause maps to a distinct returned attribute, so little could be cut without losing 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?

An output schema exists, so return-shape explanation is not strictly required, yet the description still frames the result semantically and ties it to the downstream search_notes call. Missing only edge-case behavior such as truncation of value lists or empty-vault results for a tool whose complexity is low.

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?

Only one parameter, vault_id, and it is fully documented in the schema (100% coverage), including the multi-vault requirement and the list_vaults fallback. The description adds nothing about the parameter, so the 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 opens with a specific verb and resource ("List every frontmatter field used in the vault") and then enumerates the returned attributes — value kinds, note counts, list-ness, ranges, top values — which makes it unmistakable versus siblings like list_tags or get_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?

It explicitly prescribes when to call it ("Call this before filtering search_notes by frontmatter") and how to feed the result into that sibling's `fields` filter, including both exact-value and range-bound usage. No inference about the alternative workflow is left to the 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 cover safety (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description still adds real operational behavior: notes are paged and must be re-called with next_cursor until it is null, and recursive mode returns note counts. It stops short of saying whether attachments or folders are also paginated or what the non-recursive response looks like, which keeps this below a 5.

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

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

Front-loaded with the core action, then each subsequent sentence handles one concern: root convention, recursive mode, whole-vault pattern, pagination loop, and the search alternative. No sentence is redundant and none re-states the annotation boilerplate.

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 read tool with an output schema, the description covers the remaining risk areas: pagination termination, root addressing, recursive semantics, and cross-tool routing. Return-value detail is properly delegated to the output schema, so nothing an agent needs 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 coverage is 100%, so the schema already documents every parameter and a 3 is the floor. The description adds meaning beyond it by giving the folder root convention and, notably, the composed behavior of combining recursive:true with the root to enumerate all folders with counts — a usage pattern no single parameter description conveys.

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?

Specific verb ("List") plus clearly scoped resource: notes, attachments, and subfolders directly inside one folder. It distinguishes itself from siblings by naming search_notes for content lookup and by defining what recursive mode returns, so an agent can place it against list_tags, get_notes, and search_notes without opening 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?

Explicit when-to-use rules: empty string for root, recursive:true for descendants or a whole-vault folder tree, follow next_cursor until null, and use search_notes for content-based lookup. It names the alternative tool and the condition that selects it rather than leaving the choice implicit.

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 establish the safe-read profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description's burden is low. It adds only that document counts are returned, and says nothing about vault scoping nuance or ordering – the per-call vault requirement is conveyed in the schema, not here.

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 that are front-loaded with the operational statement, followed by the use case. Minor redundancy in pairing 'personal knowledge base' with 'vault', but there is no padding.

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

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

An output schema exists, so return values (counts, tag names) need not be described, and annotations already cover safety. What remains thin is routing between this and the many sibling list/search tools, which the description leaves to inference.

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

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

There is a single parameter with 100% schema description coverage, so the schema fully documents vault_id, including the multi-vault requirement and the list_vaults fallback. The description adds no parameter-level detail, making the baseline 3 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?

States a specific verb and resource ('List all tags') and notes the inclusion of document counts, so an agent knows the operation precisely. However, it does not differentiate itself from siblings like get_notes, search_notes, or list_folder, which an agent must disambiguate among.

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 second sentence gives an implied purpose ('Use to explore what topics exist in the vault'), which is enough to suggest the exploration use case. It stops short of explicit when-not conditions or naming alternatives such as search_notes or get_notes for tag-driven filtering.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful orchestration context — that the result feeds vault_id into other tools — but says nothing about pagination, ordering, or what an empty result means; minor for a zero-param list tool.

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 short sentences, each doing distinct work: what it returns, when to call it, and what happens if you skip it. The sequencing instruction is front-loaded in sentence two.

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

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

An output schema exists, so return values needn't be fully enumerated, and the annotations cover safety. For a zero-param read tool, the description supplies exactly the missing piece — when to call it and the downstream dependency — and nothing else.

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 tool takes zero parameters, so the baseline is 4. The description doesn't invent parameter meaning where none exists, and correctly frames the output values as the inputs other tools require.

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 your vaults') and names the returned fields (IDs, names, slugs), which no sibling tool does. An agent can immediately distinguish this from list_folder, list_tags, or list_fields.

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?

Explicit trigger: 'Call this first when you own more than one vault,' plus the cross-tool dependency that every vault-scoped tool needs a vault_id. It also names the alternative behavior ('search_notes without one searches all vaults'), leaving nothing to inference.

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 non-read-only, non-destructive, non-idempotent behavior. The description adds value beyond them by clarifying that content is unchanged and only the path moves, plus that the change syncs to all connected Obsidian devices — meaningful for a mutation. It still omits what happens if new_path already 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?

Three short sentences, front-loaded with the action and immediately followed by the sync-side effect and the content-invariance guarantee. 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 and full annotations present, the description only needs to fill residual gaps. It covers scope, sync behavior, and content preservation, but omits collision/overwrite behavior for the destination path, which matters for a non-idempotent move.

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% and the vault_id description already explains the multi-vault requirement in detail. The description adds no path format, relative-vs-absolute, or extension-handling guidance beyond what the schema provides, so the 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 ('move or rename') on a specific resource ('a single attachment'), scoped to binary files like images and PDFs. This clearly separates it from siblings such as rename_note, rename_folder, and write_note without needing to open a schema.

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

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

The description implies usage (renaming/moving attachments) but never states when to prefer this over rename_note or rename_folder, nor any preconditions such as the target path needing to exist or collisions being handled. Usage is inferable from the resource type alone, which is the minimum viable level.

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=false and destructiveHint=false, so the mutation/safety profile is covered; the description adds value beyond that by disclosing the cascade scope (all contained notes, attachments, subfolders) and the reindex/sync side effect. It stops short of mentioning irreversibility or collision behavior.

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 tight sentences with the primary action and its scope front-loaded, followed by the sync consequence and the sibling alternative. 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?

For a mutating tool with full schema coverage, annotations, and a separate output schema, the description conveys the cascade and reindex behavior needed to call it correctly. It omits edge cases such as name collisions or failure modes, which leaves a small 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%, so old_folder, new_folder and vault_id are all fully documented in the schema. The description adds no parameter-level detail beyond what the schema already provides, making the baseline 3 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?

States a specific verb and resource ('Rename or move a folder') and immediately scopes it to the whole subtree ('every note, attachment and subfolder inside it'). It also distinguishes itself from the analogous sibling by naming rename_note for the single-note case.

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

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

Gives explicit routing guidance by naming rename_note for moving a single note, so the agent knows which tool handles the narrower case. However it offers no guidance against create_folder/delete_folder or other folder siblings, nor when-not conditions for this tool itself.

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 cover the safety profile (not read-only, not destructive, not idempotent), and the description adds genuinely non-obvious behavior: the change syncs across Obsidian devices, referring links are rewritten in the background, and it fails if the target path is occupied. That failure mode and the background link-rewrite side effect are the kind of context annotations cannot express.

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 tight sentences, front-loaded with the core action and side effects before the sibling routing hints. Every clause 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?

With full schema coverage, existing annotations, and an output schema, the remaining ambiguity (failure conditions, device sync, link rewriting) is precisely what the description resolves. Nothing needed to call this tool 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%, so the schema already documents old_path, new_path, and the vault_id resolution rule. The description adds no syntax or format detail about paths beyond what the schema supplies, so the 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 pair (rename/move) and a precisely scoped resource (one note), and explicitly distinguishes itself from rename_folder and move_attachment. An agent can route correctly without opening 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?

Names two alternatives with the exact condition that selects each: a whole folder goes to rename_folder, an image or PDF goes to move_attachment. Nothing is left to inference.

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

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

The description adds substantial behavioral detail beyond the annotations: restored items return to their old paths, remain in trash, skipped items are listed, repeats are safe, and plan limits can cause refusal. These details are consistent with the declared idempotent, non-destructive mutation behavior.

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

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

The description is front-loaded with the core action and then proceeds through important edge cases in a compact sequence. Every sentence contributes operational meaning, with no wasted text.

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 annotations, 100% parameter description coverage, and the presence of an output schema, the description gives an agent everything needed to decide when and how to call it. It covers the important failure and safety behaviors without needing to explain return values.

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 useful meaning by clarifying that op_id refers to an entire delete call and restores everything that call removed. It does not add much for vault_id beyond the schema, but the op_id clarification is valuable.

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: undo delete_note, delete_folder, or delete_attachment by passing the returned delete_op_id. It clearly distinguishes the tool from its sibling delete operations and explains that all removed items are restored to their old paths while remaining in trash.

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 says to use this after a supported delete call and to pass the delete_op_id that call returned. It also describes conditions where items are skipped or the operation is refused, though it does not explicitly compare against any alternative restore path.

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, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds the meaningful default that all vaults are searched unless vault_id is set and that 'filters still apply' when using similar_to, but it does not discuss result ordering/scoring or what the response contains — though an output schema exists, which lowers that burden.

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 front-loaded sentences that each carry decision-relevant information (scope default, query-omission, similar_to, use-when), with no filler. Minor redundancy with the schema on vault_id scope keeps it from being maximally tight.

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 14-parameter tool the description covers the highest-risk decisions — mode selection via the schema, query vs. omitted query vs. similar_to, and vault scoping — and an output schema plus rich annotations handle the rest. It leaves the get_notes relationship and result ordering to the agent's inference, a small residual 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 coverage is 100%, so the baseline is 3; every parameter, including mode, folder, diversity and the date bounds, is already documented in the schema. The description restates the query-omission and vault_id default behaviors rather than adding new syntax or interaction rules beyond what the schema says.

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

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

States a specific verb and resource ('Search your personal knowledge base... Finds relevant notes using semantic search') plus the default scope ('ALL your vaults by default; pass vault_id to limit'). It also disambiguates the three call shapes — query, omitted query (recency listing), and similar_to — so an agent knows which mode it is invoking.

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

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

Gives an explicit trigger: 'Use when the user asks about their notes, vault, knowledge, or memory,' and explains the alternative paths (similar_to instead of query; omit query to list recent notes). It does not contrast with the sibling get_notes, which is the most likely confusion point for a read-a-note-list request, so the routing guidance is clear but not complete.

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

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

Annotations only cover the mutation/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuinely non-derivable behavior: the data-privacy constraint on what may be transmitted and the two modes of initiation. It does not disclose submission consequences (who sees it, whether it is queued or irreversible), which keeps it from a 5.

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, front-loaded with purpose, then usage triggers, then the critical privacy rule. Nothing is redundant with the title or schema and every sentence carries a distinct instruction.

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

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

An output schema exists so return values need no explanation, and the description covers purpose, both invocation paths, and the privacy constraint that an agent must honor before calling. Nothing required for a correct call 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% and the enums for category and initiated_by are fully self-documenting, so the baseline is 3. The description reinforces the message parameter's constraint by restating 'no note content' in the privacy sentence, but adds no syntax or format 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 (send feedback to the Engram team) and enumerates the accepted content types (bug, idea, confusing, works well, missing capability). This clearly distinguishes it from every sibling, which are all note/folder/attachment vault 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?

Gives explicit trigger conditions for both actors: when the user asks to send feedback, and when the model should self-initiate (a tool failed, gave a poor result, or could not do what was needed). It also states an exclusion — never include note content, titles, paths, or personal data — which is the only real usage mistake an agent could make here.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds workflow context (a pre-create_note step) but says nothing about how many suggestions, ranking behavior, or what happens on a miss, so it adds only modest value beyond 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 short sentences, zero filler, with the tool's action front-loaded and the sequencing guidance second. 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?

An output schema exists, so return-format explanation is unnecessary, and the vault_id nuance is already fully documented in the schema. The description covers purpose and usage; only a hint about how suggestions are ranked or what a weak/no-match result means 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%, including detailed guidance for vault_id (multi-vault requirement, list_vaults fallback) and limit. The description mentions only the content description concept, adding nothing beyond the schema, 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+resource ('Find the best existing folder for a new note') and adds the input basis ('based on a description of its content'). This clearly distinguishes it from sibling list_folder (which enumerates) and create_folder (which makes new ones).

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 sequences the tool: 'Call before create_note when the right folder is unclear.' This gives a clear triggering condition relative to a named alternative. It stops short of saying when NOT to use it (e.g., when the target folder is already known, or when list_folder/search_notes might suffice).

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, the description discloses the destructive overwrite behavior, the save/index/sync side effects, the base_hash requirement, and the version_conflict outcome that prevents erasing another client's edit. These are exactly the behavioral details an agent needs before invoking a destructive write tool.

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 overwrite behavior and base_hash requirement are front-loaded, followed by clear sibling-routing sentences. Despite its length, every sentence provides decision-relevant information for a destructive tool.

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 write tool with an output schema and full schema coverage, the description covers the essential risks, alternatives, preconditions, and failure mode. No important invocation context is missing.

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

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

Schema coverage is already 100%, so the schema itself documents path, content, vault_id, and base_hash. The description reinforces the importance and consequence of base_hash, but it adds little parameter meaning beyond what the schema already provides.

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: replace a note's entire content or create it if missing. It immediately distinguishes this from append_to_note, edit_note, and create_note by naming each sibling and its differing behavior.

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 guidance: use append_to_note to add text, edit_note to change one passage or heading, and create_note when overwriting must be avoided. It also states the critical precondition for replacing an existing note, including how to obtain base_hash and what happens on a conflict.

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