Engram Obsidian Memory Sync

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

Annotations already declare the mutation/idempotency/destructiveness profile, so the bar is lower. The description adds genuinely non-obvious context beyond them: it creates the note with a title line if missing, preserves existing text, and inserts position=start after any frontmatter rather than at the very top.

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

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

Front-loads the core action and keeps each sentence purposeful, but the position guidance and the alternatives are spread across several short sentences with mild overlap between the opening line and the position=start 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?

For a 4-param mutation tool with an output schema, the description covers creation semantics, insertion position, and sibling routing. It leaves return-value detail to the output schema, which is acceptable, though the vault_id multi-vault requirement is only implied.

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 like path, text, position and vault_id are already fully documented. The description's position=start note ('after any frontmatter') roughly restates the enum description; it adds little 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 (add/append) and resource (note end), plus the non-obvious auto-create behavior. Explicitly distinguishes itself from edit_note and write_note, so an agent can route correctly without opening sibling schemas.

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

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

Gives concrete use cases (logs, journals, running lists), names both alternatives (edit_note for changing text, write_note for replacing the whole note), and explains the position=start variant. 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?

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?

Adds real behavior beyond the annotations: the note is auto-placed when no folder is given, and creation is non-overwriting (fails if a path already exists). This refines the annotation profile (idempotentHint=false, destructiveHint=false) with concrete failure semantics. It does not mention required permissions or vault-state caveats.

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, followed by the placement rule and the failure mode. Every sentence carries distinct information and none is 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 need no explanation, and the description covers the key non-obvious behaviors (auto-placement, non-overwrite failure). Minor gap: no explicit routing versus write_note/edit_note for an agent choosing among 17 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 coverage is 100%, so the baseline is 3, but the description contributes conditional meaning the schema lacks: what happens when suggested_folder is omitted. It reinforces rather than duplicates the vault_id guidance already in the schema.

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

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

States a specific verb and resource ('Create a new note') plus a distinguishing scope detail ('automatic folder placement'), which separates it from plain write_note. It stops short of explicitly naming sibling alternatives, so an agent must infer the boundary from the sibling list.

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 one clear conditional: omit suggested_folder to let the server choose a location. However it never states when to prefer create_note over write_note, edit_note, or append_to_note, leaving the main routing decision 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 declare destructiveHint=true and idempotentHint=true, but the description adds information annotations cannot convey: the file "cannot be restored", the delete propagates to all connected Obsidian devices, and a missing attachment returns deleted: false rather than failing. These are exactly the side-effect and reversibility details an agent needs before a destructive call.

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 destructive nature and irreversibility are front-loaded, followed by sync behavior, the no-op edge case, and alternative-tool routing in one short trailing sentence. No sentence is filler.

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

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

With an output schema present, the description needn't document return fields, yet it still surfaces the meaningful one (deleted: false). Combined with irreversibility, device sync, and sibling routing, nothing needed to invoke this destructive 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 coverage is 100%, with both path and the multi-vault vault_id requirement fully documented in the schema itself. The description only restates "by path" and adds no syntax, format, or resolution 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 and resource ("Permanently delete a single attachment") and further narrows scope to binary files rather than notes or folders. It explicitly names the sibling tools delete_note and delete_folder that handle the adjacent cases, so an agent can differentiate 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 routing: notes go to delete_note, folders go to delete_folder, and this tool is for individual attachments. It also covers the edge case of a path with no attachment, so the agent knows a no-op call is not an error.

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=true, but the description adds what those hints cannot: the call is refused rather than partially applied when the folder is non-empty, the refusal reports item counts, and the effect propagates to all connected devices. That is exactly the operational context an agent needs before invoking a destructive 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, front-loaded with the verb and the default safety behavior, then the override, then the side effect. No filler and no repetition of the schema.

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

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

Output schema exists, so return-value detail is not required. For a destructive, vault-scoped tool the description covers the refusal semantics, the destructive opt-in, and cross-device propagation, which is everything needed to call it safely.

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 folder, vault_id and recursive; the baseline is 3. The description adds real meaning beyond the schema by tying recursive:true to 'everything under it' and to the default refusal path, clarifying the parameter's consequence rather than just its type.

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 ('Delete a folder') and immediately qualifies the scope with the empty-only default and the recursive override. It is clearly distinguishable from delete_note or rename_folder by resource, though it does not name any sibling explicitly.

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

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

Gives concrete when-to-use conditions: the default refuses non-empty folders, and recursive: true is the documented path for deleting contents. It does not state when an agent should prefer an alternative tool (e.g. deleting contents via delete_note first), so it stops short of full routing guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, and the description adds genuinely new behavioral detail: atomic failure with no write on missing text/heading or an expected_replacements mismatch. It does not mention permission or auth requirements, but the safety-critical transaction semantics are 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?

Front-loads the core action, then mode semantics, then failure behavior, then sibling routing. Four sentences, no filler, and every clause carries either behavior or a routing decision.

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

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

For an 11-parameter mutation tool, the description covers mode semantics, failure/atomicity, and alternatives, and an output schema exists so return values need not be explained. Vault scoping and level/position defaults are left to the schema, which is acceptable but means the description is not fully self-contained.

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, and the description goes beyond it by explaining mode-level semantics: replace_text takes the first occurrence by default, replace_section wipes everything under a heading, and insert_section preserves existing content while placing content at section start or end.

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 scope ('Change part of an existing note') and then enumerates the three modes with what each targets. It explicitly names the siblings append_to_note and write_note and the conditions that select them, so an agent can separate this tool from nearby note-writers 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?

Gives explicit when-to-use routing: append_to_note for top/bottom insertion, write_note for full rewrites, and the three modes here for targeted edits. Preconditions are also stated ('Fails without writing if the text or heading is not found').

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 (readOnly, idempotent, non-destructive), and the description adds the crucial mechanics: it returns a URL to POST to yourself using the existing credential, and the bytes never pass through this tool. That auth/flow disclosure is exactly the kind of context annotations cannot provide.

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

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

Three tight sentences: what it returns first, then how to use it, then when to call it. Zero redundancy and no filler.

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

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

For a no-required-param read tool with a full output schema, the description supplies the upload workflow context an agent needs and defers return-value detail to the schema. 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 description coverage is 100% and the single vault_id parameter is fully documented in the schema, including the multi-vault rule and list_vaults fallback. The description adds nothing about parameters, 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+resource ('Get the endpoint and this account's limits for uploading an attachment') and names the supported file kinds. No sibling tool competes with this operation, so an agent can route to it unambiguously.

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 'Call before uploading to learn the size cap and which file types the plan allows,' giving clear timing and intent. It does not name a when-not condition or an alternative path, which keeps it just short of a 5.

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

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

Annotations already establish readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description contributes extra context beyond the annotations, notably that recursive results include note counts and that only direct children are returned by default. It does not add return-format or pagination detail, but the output schema exists and covers that.

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?

Short and front-loaded, leading with what is listed before covering the recursive option and the search_notes alternative. Every sentence carries routing or scoping information, though the two recursive sentences partially overlap in intent.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Between the description, full schema coverage, and output schema, an agent has everything needed to call this correctly whether scoping to root, a subfolder, or a recursive walk.

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 folder, vault_id, and recursive are already documented in the schema, including the empty-string-for-root convention. The description largely restates those semantics and only marginally extends them by noting the note counts returned under recursive. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (list) and resource (notes, attachments, subfolders directly inside one folder), and distinguishes itself from siblings by naming search_notes for content-based lookup. An agent can tell it apart from get_notes, list_tags, or list_vaults 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 explicit when-to-use routing: empty string for root, recursive=true for all descendants, root+recursive for every folder with counts, and search_notes for content search. Alternatives and the conditions selecting them are spelled out rather than implied.

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

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

Annotations already 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 readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds non-obvious context: that the returned vault_id is a prerequisite for every other vault-scoped tool and that omitting it in search_notes broadens scope. It does not mention pagination or size limits, so it stops just short of full disclosure.

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

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

Three tight sentences: the output is front-loaded, then the ordering advice, then the fallback behavior. Nothing is redundant or padded.

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 zero parameters, an output schema present, and full annotation coverage, the description supplies exactly the missing piece: the dependency relationship that makes this a prerequisite call. Nothing an agent needs in order to call it correctly 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?

Zero parameters, so the baseline is 4. The description goes slightly further by clarifying what the tool emits (name or ID) that other tools consume, which is the only parameter-relevant information this tool has.

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 (List) and resource (vaults) and even enumerates the returned fields (IDs, names, slugs), which distinguishes it from the other list_* siblings such as list_folder and list_tags.

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 when to call it ('Call this first when you own more than one vault') and why, plus the alternative behavior ('search_notes without one searches all vaults'), giving the agent a clear decision rule.

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?

Annotations already declare readOnly/idempotent/non-destructive. The description adds real behavioral context beyond them: default scope is ALL vaults unless vault_id is passed, filters are ignored in list mode, and similar_to excludes the source note. It omits ranking/pagination detail, but that is minor for a read-only search.

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 tight sentences, front-loaded with purpose then scoping then the two alternate invocation modes then the trigger. Every sentence carries information; no filler.

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

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

Given a rich 13-param schema with full coverage, an output schema, and safety annotations, the description covers the distinctions an agent actually needs (mode choice, listing fallback, similar_to path, vault scope) without redundantly restating schema 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter relationships the per-field schema text does not state at a glance (query vs similar_to mutual exclusion, all-vaults default scope, filter suppression when query is omitted).

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 (semantic search over a personal knowledge base) and enumerates the three distinct invocation shapes: query, no-query listing of recent notes, and similar_to lookup. It also distinguishes itself from list_vaults by pointing there for vault discovery.

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

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

Explicitly names the trigger condition ('when the user asks about their notes, vault, knowledge, or memory'), the alternative to query (omit it to list recent notes), and the substitute path (similar_to instead of query). 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?

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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds concrete consequence detail: 'Overwrites whatever the note held' and the side effects (saves, indexes for search, syncs to Obsidian). It does not mention permission requirements, but the overwrite/sync disclosure adds real value beyond the hints.

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

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

Front-loads the core behavior, then spends three sentences on sibling routing, all of which earn their place. Slightly dense but no filler; the routing detail is arguably load-bearing rather than redundant.

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

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

With an output schema present, return values need not be explained. The description covers the destructive overwrite risk, side effects, and sibling selection, leaving only auth/permission nuances unaddressed for a mutation 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 the schema already documents path, content, and vault_id (including the multi-vault requirement). The description offers no parameter syntax or format detail beyond the sibling note that create_note takes a title rather than a path, 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 and resource ('Replace a note's entire content, or create the note if it does not exist') and explicitly differentiates from append_to_note, edit_note, and create_note by naming each alternative and its distinct 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?

Gives explicit when-to-use routing for all three alternatives: append_to_note for adding text, edit_note for a single passage/section, create_note for overwrite-safe creation. An agent can choose correctly without opening any schema.

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