Engram Obsidian Memory Sync

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

The description discloses auto-creation when the note is missing and makes it clear this is a mutating append, supplementing the annotations (readOnlyHint=false, idempotentHint=false). It does not go into side effects like parent-folder handling, but for a simple append the key behavior is covered.

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 entire description is one sentence with no filler, front-loading the core operation and then the conditional creation. Every word contributes.

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 three-parameter mutating tool, the description plus schema plus annotations cover the main call semantics, and the output can be inferred from the output schema. Minor gaps remain around edge cases such as whether missing parent folders are created, but nothing essential to a normal 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%, so the description is not required to elaborate on parameters. It adds no additional meaning beyond the schema's descriptions of path, text, and vault_id, except the contextual create-if-missing behavior. 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 names a precise verb ('append') and resource ('text to an existing note') and adds the create-if-missing behavior, making it distinguishable from siblings like write_note and create_note. It is not a tautology and clearly states the operation's scope.

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 the appropriate context—use when text should be added to a note and created if absent—but it never explicitly contrasts with sibling tools such as write_note (overwrite) or patch_note (targeted update). No exclusions or when-not-to-use guidance is provided.

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

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

The description restates idempotency in a slightly more detailed way ('succeeds without creating duplicates'), which adds a nuance beyond the idempotentHint annotation. However, it does not disclose other behavioral aspects like failure modes (e.g., invalid path) or whether parent folders are auto-created. Given that annotations cover safety (non-destructive, not read-only), the description fits within expectations.

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 first sentence states the core purpose, the second gives usage and idempotency. It is front-loaded and each 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?

For a simple creation tool, the description covers purpose, usage, and idempotency. Parameters are fully documented in the schema, and the output schema (not shown) likely describes the return. It does not mention error handling or permissions, but those are not critical for a straightforward folder creation action when annotations indicate non-destructive 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?

The input schema already provides 100% coverage, including clear examples for 'folder' and a detailed explanation for 'vault_id'. The description adds no parameter-specific information, so it relies on the schema as the baseline. The description's mention of scaffolding does not elaborate on parameter usage.

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 ('Create') and resource ('explicit empty folder in the personal knowledge base'), clearly distinguishing it from siblings like create_note or delete_folder. It also implies a scoping restriction ('explicit') that sets it apart from tools that might auto-create parents.

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

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

It explicitly says 'Use to scaffold folder structure before placing notes,' giving a clear when-to-use context. It does not explicitly name alternatives, but the phrase 'before placing notes' implies it is for folder creation prior to note writing, which is sufficient guidance in a small toolset.

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 provide generic flags (non-read-only, non-idempotent), so the description carries the behavioral burden and does so well. It discloses two important traits beyond the flags: automatic folder placement when suggested_folder is omitted, and hard failure on path collisions. This gives the agent actionable expectations about side effects and failure modes.

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 carrying unique information: the core action, the optional parameter branch, and the failure constraint. No filler, no restatement of parameter names 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?

With an output schema present and parameter descriptions covering vault_id, the description covers the essential call-time decisions: whether to pass suggested_folder and what happens on a collision. The only minor gap is not detailing how automatic folder placement selects a folder, but this is not necessary for invoking the tool correctly.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds extra meaning by tying suggested_folder to the automatic placement behavior and explaining the collision failure mode, while vault_id's multi-vault requirement is captured in the schema itself. This exceeds the baseline without repeating schema 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?

States a specific verb ('Create') and resource ('note') and immediately adds distinguishing behavior: automatic folder placement and never-overwrite semantics. This clearly separates it from siblings like write_note, append_to_note, and patch_note, which imply modification or replacement.

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

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

The description gives clear context for when to use the tool: when creating a new note, and it explicitly states the conditional for suggested_folder. The 'Never overwrites: fails if a note already exists at the resulting path' clause also serves as a when-not indicator, though it does not name an alternative tool for overwriting.

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' destructiveHint, the description adds valuable behavior: empty-only refusal with counts, recursive deletion semantics, and syncing across devices. This tells the agent about safety guardrails and side effects, which is exactly the kind of context annotations alone do not provide.

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

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

Three short sentences, front-loaded with the core actionlorraine, then the critical default behavior, the override, and the side effect. Every sentence earns its place; there is no repetition of schema fields or annotation data.

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, nested-content operation, the description covers the essential decision points: default refusal, how to opt into recursive deletion, and the syncing side effect. The vault_id nuance is covered in the schema, and the output schema handles return values, so nothing needed for correct invocation 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 baseline is 3. The description adds meaning beyond the schema by explaining the empty-only guardrail tied to recursive, and it makes the folder path semantic concrete with the example. This pushes it above 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 states a specific verb and resource ('Delete a folder') and immediately distinguishes destructive scope: empty-only by default vs recursive deletion. This separates it from siblings like delete_note, rename_folder, and create_folder without ambiguity.

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: the default empty-only behavior, when to pass recursive: true, and that non-empty folders are refused with counts. It doesn't explicitly name sibling alternatives ('use delete_note for a single note'), but the deletion scope is sufficiently clear to guide tool 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 already indicate destructive and non-read-only behavior, so the description's addition that 'deletion will sync to all connected Obsidian devices' adds useful behavioral context beyond the structured data. It does not 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?

The description is two concise sentences with no filler. The core action is front-loaded, and the additional sync behavior is stated in a single efficient clause.

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 low-complexity delete operation with a full parameter schema, an output schema, and destructive/idempotent annotations, the description covers the essential behavior. The sync side effect is the only notable behavioral disclosure needed, and it is present.

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

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

Schema description coverage is 100%, with both path and vault_id already documented in detail. The description itself adds no parameter-specific meaning, so it relies on the schema, which is adequate and earns the baseline score.

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

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

The description states a specific action ('Delete a note') and a clear resource ('from the knowledge base'), distinguishing it from sibling tools like delete_folder. The verb and object are unambiguous, leaving no doubt about the tool's 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?

The description makes the tool's purpose clear but provides no explicit guidance on when to prefer it over alternatives or when not to use it. There is no mention of delete_folder for directories or any exclusions, so usage 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 mark this as read-only, idempotent, and non-destructive. The description adds genuinely useful behavioral context beyond that: the file bytes never pass through the tool, the returned URL is used to POST to yourself, and the existing connection credential is reused. It also clarifies the server keeps no active-vault state, which is important for correct invocation.

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 three focused sentences with no filler. The core purpose is front-loaded, followed by the key behavioral nuance (bytes do not pass through the tool), and ends with concrete usage timing. 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?

Given the presence of an output schema, full parameter coverage, and annotations describing safety, the description is complete for an agent to decide when to call and what to expect. It covers the endpoint/limits, credential behavior, file types, and the correct call-before-upload workflow.

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 only one optional parameter, and the schema description already covers it thoroughly, including when to include vault_id, what values are accepted, and how to resolve an unresolvable name. With 100% schema description coverage, the tool description does not need to add parameter details; 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?

The description states a specific verb ('Get') and resource ('attachment upload target') and explains exactly what is returned: the endpoint and account limits. It also clarifies scope by listing supported file types, which differentiates it from the sibling tools like move_attachment and the note/folder operations.

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

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

The description gives explicit temporal guidance: 'Call before uploading to learn the size cap and which file types the plan allows.' It does not explicitly name alternatives or exclusion conditions, but the instruction clearly identifies when this tool is relevant among the sibling set.

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, and destructiveHint, so the safety profile is fully covered. The description adds that it returns 'full content' and targets a 'specific note,' but offers no further behavioral context (e.g., auth, rate limits), which is acceptable given the strong 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 with no filler, but there is slight redundancy: 'full content' and 'complete note' repeat the same idea, as do 'retrieve' and 'read.' It is still highly readable and front-loaded with the core purpose.

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 complete schema, rich annotations, and an output schema, the description covers everything necessary. It adds the workflow hint 'Use after searching' and clarifies the full-content return, making it 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?

Input schema coverage is 100%, with detailed descriptions for both vault_id and source_path. The description adds no parameter-specific meaning beyond reinforcing the singular note target, so it stays at the baseline for fully documented schemas.

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 clear action and resource: 'Retrieve the full content of a specific note.' It distinguishes from sibling get_notes/search_notes by emphasizing 'specific note' and 'full content,' though it does not explicitly name any alternative.

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 after searching to read a complete note' gives explicit workflow context, telling the agent when in the process this tool fits. It does not mention when not to use it or name alternatives, but the guidance is clear enough for a simple read operation.

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, and destructiveHint, so the safety profile is covered. The description adds useful behavior beyond annotations by disclosing that missing paths are reported inline, which helps the agent anticipate partial-failure responses.

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 earning its place: one for function and scope, one for use cases, and one for missing-path behavior. The most important information is front-loaded in the first sentence.

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

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

Given that the annotations cover read-only idempotent behavior, the schema fully documents parameters, and an output schema exists, the description supplies the remaining decision-relevant context: batch scope, common workflows, and inline missing-path reporting. Nothing vital 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 both paths and vault_id are already documented with descriptions, examples, and conditions. The description adds little beyond reinforcing the 1-20 path limit, so the baseline score 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 uses a specific verb ('Retrieve') against a specific resource ('multiple notes') and adds the key distinction of batch access via '1-20 paths'. It clearly separates this from the singular get_note sibling.

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

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

The description names concrete use cases: inventorying a folder via list_folder then get_notes, and reading batch search results without N round-trips. It gives clear context but does not explicitly state 'use get_note for a single note' or list when not to use this 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the root-folder behavior with an empty string, which is useful, but it does not disclose whether subfolders are included recursively or other behavioral details beyond what annotations provide.

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

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

Two short sentences, front-loaded with the core purpose and immediately followed by the key edge case. Every word earns its place; there is no repetition or filler.

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

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

For a simple read-only list operation, the description plus rich annotations and a fully documented schema cover what an agent needs. The output schema exists, so return-value details are not the description's responsibility, and the vault_id nuance is already fully explained in the input 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 description coverage is 100%, so the schema already documents both parameters thoroughly, including the vault_id requirement and the empty-string root convention. The description reinforces the root behavior but adds no new semantic meaning 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?

The description clearly states the action ('List all notes') and the resource ('in a specific folder'), with a useful special case for the vault root. It does not explicitly differentiate from siblings like get_notes or list_folders, but the folder-scoped focus is evident.

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 intended use is implied: call this when you need notes contained in a folder, or all vault-root notes when passing an empty string. However, there is no explicit guidance about when to prefer this over get_notes, search_notes, or list_folders, and no exclusions are 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds mild behavioral context by saying it returns note counts across all folders, but it does not disclose ordering, recursion, or any selection criteria beyond all folders. This is comparable to the calibration case where minimal extra context earns a 3.

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 with no filler. The key behavior is front-loaded, and the usage guidance follows immediately. Every word contributes.

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 list tool, the description, annotations, complete parameter schema, and output schema together supply everything an agent needs: what it returns, why to use it, safety guarantees, and parameter handling. 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?

Schema description coverage is 100%, and the vault_id parameter is already thoroughly documented in the input schema, including when to pass it and how name resolution works. The description adds no parameter-level meaning, 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?

The description states a specific verb (list), resource (all folders), and scope (personal knowledge base), and adds that results include note counts. This clearly distinguishes it from the sibling list_folder tool by explicitly saying 'all folders' and by focusing on organizational structure.

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 sentence 'Use to understand the vault's organization' provides a clear, purpose-driven context for when to call this tool. However, it does not explicitly contrast with alternatives such as list_folder or list_vaults, so it stops short of offering when-not-to-use 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, idempotentHint, and non-destructive behavior. The description adds the 'document counts' detail but does not disclose much beyond that; this is acceptable because the safety profile is fully covered by 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 concise sentences with no filler. The core behavior is front-loaded and the intended use case follows immediately.

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

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

The tool is simple, has an output schema, one well-documented optional parameter, and annotations that cover safety. The description plus schema fully equip 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%, and vault_id's semantics are already richly documented there, including multi-vault behavior and fallback to list_vaults. The tool description adds no extra parameter-level meaning, 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?

States a specific verb, resource, and result: list all tags with document counts. It clearly distinguishes what the tool does and has no sibling tag-listing tool that could create confusion.

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 to use it to explore topics in the vault, giving a clear context. It does not mention when not to use it, but no sibling tool directly competes with this listing operation.

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

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

Annotations already mark the operation as read-only, idempotent, and non-destructive. The description adds meaningful context beyond those annotations by limiting results to the current user's vaults and indicating the output shape, which helps the agent set expectations.

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, front-loaded sentence states the action, scope, and returned fields with no filler. Every phrase adds information, making it efficient and easy for an agent to parse quickly.

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 parameterless list operation with a rich output schema and strong annotations, the description is complete. It covers what is listed, whose vaults are included, and what fields will be returned; no additional operational details are needed.

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 has zero parameters, so the description has no parameter burden to carry. The baseline of 4 applies, and the description appropriately focuses on scope and output without introducing any parameter confusion.

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

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

The description uses a specific verb ('List') and resource ('vaults') and explicitly scopes to 'vaults owned by the current user,' which differentiates it from sibling tools like set_vault. Naming the returned fields (IDs, names, descriptions) further clarifies exactly what the tool produces.

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 the tool is for discovering available vaults, especially given the sibling set_vault, but it does not explicitly state when to use this tool versus alternatives or mention any prerequisites. For a simple, zero-parameter listing tool this is adequate but not explicit.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds useful behavioral context: it syncs to all connected Obsidian devices, and the file's content is unchanged. It doesn't mention whether the operation can overwrite an existing file at the destination, which would be valuable for a move 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?

Two sentences with no fluff. The core action is front-loaded, and the sync/behavioral note is concise. 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 simple move operation with a full output schema and 100% parameter coverage, the description is nearly complete. It could mention overwrite behavior or whether the old path must exist, but the essential information for calling the tool correctly is present.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds the semantic point that only the path changes, not the content, which reinforces the meaning of old_path/new_path. However, it doesn't add details beyond the schema, so 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 states a specific verb ('Move or rename') and resource ('a single attachment (image, PDF, or other binary file) to a new path'), and distinguishes it from note/folder operations. It also clarifies that content is unchanged, which helps differentiate from write/update tools.

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 when to use this tool (when moving/renaming an attachment) and the vault_id parameter description gives explicit guidance on when it is required and when to omit it. It doesn't explicitly name alternatives, but the sibling list makes the distinction clear enough.

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 aligns with the destructiveHint=true annotation by saying it modifies an existing note, and it adds useful behavior details: first occurrence by default and -1 replaces all. It does not describe no-match behavior or reversibility, but the annotation and output schema reduce the 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?

Two sentences with no filler. The core action is front-loaded, and the key default behavior is stated immediately afterward.

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 five-parameter tool with full schema coverage and an output schema, the description plus schema is sufficient for correct invocation. The vault_id requirement is thoroughly documented in the schema, and the destructive behavior is covered by annotations.

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 five parameters are already documented. The description reinforces occurrence semantics but does not add meaning beyond what the schema already provides, so the 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 states the specific action 'Find and replace text in an existing note,' which clearly identifies both the verb and the resource. This distinguishes it from siblings like append_to_note, write_note, and update_section without needing to open 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?

There is no guidance on when to prefer this tool over related alternatives such as update_section or write_note, and no when-not-to-use conditions. The phrase 'existing note' implies it does not create notes, but that is the only contextual signal.

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

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

The description goes beyond annotations by disclosing that all notes within the folder (including subfolders) are affected and that they 'will be reindexed and synced'. This is consequential behavioral context that annotations do not provide, even though they hint the operation is a write and not idempotent. It does not mention potential link breakage, but the disclosed effects are meaningful.

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 clear sentence with no filler. It front-loads the action and scope, then adds the most important behavioral effect (reindex/sync) without redundancy. Every word 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?

Given that an output schema exists and the annotations cover read/write behavior, the description provides sufficient context for correct invocation: it names the scope, the side effect, and implies the folder path semantics. It does not cover all edge cases (e.g., missing folder, conflicts), but these are not necessary for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, and the schema already thoroughly documents vault_id, old_folder, and new_folder. The description adds no parameter-specific meaning beyond what the schema provides, 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 uses the specific verb 'rename' with the resource 'folder' and adds critical scope details: 'all notes within it (including subfolders)'. This makes it unmistakably distinct from sibling tools like rename_note and delete_folder, and the reindex/sync side effect clarifies exactly what the operation accomplishes.

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 when to use the tool (renaming a folder) and clearly differentiates from note-level operations by its title and verb, but it does not explicitly state alternatives, exclusions, or prerequisites (e.g., 'use rename_note for individual notes'). The usage context is clear but 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?

Annotations already indicate this is a mutation (readOnlyHint=false) and not idempotent. The description adds the useful behavioral detail that the operation syncs to all connected Obsidian devices, but it does not disclose potential side effects like broken links or the need for vault selection (though vault_id is covered 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?

Two sentences with no wasted words. The core action is front-loaded, and the sync behavior is stated as a secondary but relevant detail. 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 a full input schema and an output schema, the description is largely sufficient. It covers the primary action and a key behavioral trait (sync). It lacks explicit usage guidance and side-effect disclosure, but those are partially covered by other dimensions and 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 description coverage is 100%, so the baseline is 3. The description adds minimal semantic value beyond the schema—it clarifies that old_path and new_path are paths and that the operation is a rename/move, but does not elaborate on formats, constraints, or interactions between parameters.

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

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

The description states a specific verb ('rename or move') and resource ('a note to a new path'), making the tool's function immediately clear. It distinguishes itself from siblings like rename_folder and move_attachment by explicitly targeting 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 implies usage for renaming/moving notes but provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives such as rename_folder for folders or patch_note for content changes, leaving the agent to infer the appropriate context.

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

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

Annotations already cover the safety profile: readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the useful behavioral detail that search is semantic and that all vaults are included by default. It does not go further into aspects like result ordering, cost, or rate limits, which is acceptable given the annotations but not exceptional.

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 earning its place: core purpose, default scope, and when to use. The description is front-loaded and has no filler or redundant technical detail.

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?

Even with 12 parameters, all parameters are thoroughly described in the schema, and the description supplies the key selection context and default behavior. The output schema covers return values, so nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including mode differences, filters, and vault_id behavior. The description only restates the vault-wide default without adding meaning 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?

The description clearly states that the tool searches the user's personal knowledge base and finds relevant notes via semantic search. It also specifies the important default scope (all vaults), which distinguishes it from sibling note retrieval tools like get_note 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?

The description provides a clear trigger: 'Use when the user asks about their notes, vault, knowledge, or memory.' It also explains when to pass vault_id versus omitting it. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of full 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 provide readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds valuable behavioral context beyond annotations by explaining that MCP keeps no state between calls and that no active vault is persisted, which is essential for agents to understand the tool's actual 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?

The description is compact and front-loaded with the core purpose, then adds only essential usage caveats and an alternative. Every sentence earns its place, and the critical 'does NOT persist' warning is highlighted early.

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 simple single-parameter schema, comprehensive annotations, and presence of an output schema, this description fully covers what an agent needs to know: what it does, what it doesn't do, how to use it, and how it relates to list_vaults.

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 already explains that vault_id can be a name or UUID. The description repeats this concept but does not add new parameter-level meaning beyond what the schema provides, 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 opens with a specific verb and resource: 'Validate and echo a vault by name or ID.' It clearly differentiates itself from siblings by explicitly stating it does NOT persist an active vault and that it need not be called before read/write operations, unlike what the name 'set_vault' might imply.

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 when-not guidance: 'this does NOT persist an active vault' and 'this need not be called first' for read/write tools. It also names the alternative: 'Use list_vaults to see them.' This leaves no ambiguity about when to invoke this tool versus its siblings.

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 the behavioral context that the tool selects an existing folder rather than creating one, which aligns with the annotations. It does not add deeper behavioral details like ranking behavior or no-match handling, but the annotations lower the bar for this dimension.

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 first states the tool's purpose and the second gives the key usage directive. The important scoping phrase 'existing folder' is front-loaded, and 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?

Given the rich annotations, complete input schema, and presence of an output schema, the description is mostly self-sufficient. It tells the agent when to call the tool and why. A minor gap is that it does not describe what happens when no suitable folder is found, but this could be covered by the output schema and is not essential for the caller's decision.

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 parameters are already well documented in the schema. The description loosely maps to the 'description' parameter by saying 'based on a description of its content,' but it adds little beyond the schema. The vault_id parameter is richly documented in the schema itself, so no compensation is 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 and resource: 'Find the best existing folder for a new note based on a description of its content.' It clearly distinguishes this tool from sibling folder tools like list_folders (which lists all folders) and create_folder (which creates a new one), so an agent can tell them apart.

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

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

The description explicitly says when to call it: 'Call before create_note when the right folder is unclear.' This gives clear contextual guidance and a direct workflow connection to create_note. It does not explicitly name alternatives or exclusions, but the condition 'when the right folder is unclear' is a sufficient usage signal.

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 mark this as destructive and non-read-only, and the description adds important behavioral detail: exactly what range of content gets replaced. This goes beyond the raw annotations by explaining the replacement boundary, which is essential for using the tool safely.

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 jargon or filler. It front-loads the main action, then immediately provides the critical scoping detail. 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?

Given the full parameter schema and output schema, the description is nearly complete. It covers the core behavior and boundary logic, though it does not address edge cases such as what happens when the heading is not found or whether the heading itself remains intact.

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 adds extra meaning to the heading and level parameters by explaining that replacement extends to the next heading of the same or higher level—information not present in the parameter schema.

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

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

The description uses a specific verb ('Replace') and resource ('content under a specific heading in an existing note'), and precisely defines the replacement boundary as 'from the matched heading to the next heading of same/higher level.' This clearly distinguishes it from sibling tools like write_note or append_to_note, which operate on entire 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 use case is clearly implied: use this tool when you need to replace a specific section of an existing note without rewriting the whole note. It does not explicitly name alternatives or state when not to use it, but the targeting behavior is unmistakable.

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

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

Annotations already indicate destructive and idempotent behavior, so the description correctly adds context beyond them by disclosing that the tool indexes for search and syncs to Obsidian. This gives the agent useful side-effect information. No contradiction exists between the description and annotations.

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

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

The description is two short sentences with no filler. It front-loads the core action and then adds relevant behavioral context. Every sentence contributes 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?

The schema and output schema cover the parameters and return shape, and the description plus annotations cover side effects. However, the description does not clarify whether 'update' means full content replacement or partial merging, which is important given the destructive hint and the existence of patch_note and update_section 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%, and the schema already explains path, content, and vault_id in detail, including the important multi-vault requirement. The tool description itself does not add parameter-level meaning, 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 action ('Write or update a note') and identifies the resource. It also adds meaningful scope by mentioning storage, search indexing, and Obsidian sync. However, it doesn't explicitly distinguish itself from siblings like create_note, patch_note, or append_to_note, so it is clear but not fully differentiated.

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 no explicit guidance on when to use this tool versus alternatives such as patch_note or append_to_note. The phrase 'Write or update' implies full-note writes, but there is no stated exclusion, prerequisite, or comparison with sibling tools. This leaves the agent to infer the appropriate use case.

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