Server Quality Checklist

Tool Scores

• list_foldersB
  3.1/5.0
  Behavior2/5

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

  With no annotations provided, the description must carry the behavioral disclosure burden. It states the tool lists folders and note counts but does not mention whether it is read-only, whether the structure is recursive, or how results are ordered or paginated. This is minimal behavioral transparency for a directory-listing operation.

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

  Conciseness5/5

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

  The description is a single concise sentence that states the action and key output detail (note counts). It is front-loaded with the main purpose and contains no wasted words, making it appropriately sized for a simple listing tool.

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

  Completeness3/5

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

  For a tool with one optional parameter, no annotations, and no output schema, the description is minimal. It tells the agent what it does but does not specify the return format, whether the parentFolder filter is absolute or relative, or any behavioral details. While adequate for a basic list operation, gaps remain in output expectations and filter semantics.

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

  Parameters3/5

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

  The schema provides 100% description coverage for the single parameter parentFolder, including an example. The tool description itself adds no extra meaning beyond what the schema already specifies. Per the rubric, high schema coverage sets a baseline of 3, and the description does not enhance parameter understanding.

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

  Purpose4/5

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

  The description clearly states the tool lists folders and directory structure with note counts. It specifies a verb and resource, making the primary purpose obvious. However, it does not explicitly differentiate from the sibling get_vault_tree, which likely also exposes directory structure, so it lacks clear sibling differentiation.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives like get_vault_tree or search_vault. It does not mention exclusions, prerequisites, or typical use cases. An agent cannot infer when to choose this tool over a sibling without additional context.

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

• sync_vault_obB
  3.1/5.0
  Behavior2/5

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

  With no annotations, the description carries the full burden of disclosing behavior. It does say the tool triggers an immediate sync cycle, implying side effects, but it does not explain consequences, synchronization semantics, or the behavior of the `configure` action. The read-only `status` path is vaguely referenced as 'inspect synchronization state' but no return or failure behavior is disclosed.

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

  Conciseness4/5

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

  The description is a single efficient sentence with no filler. It front-loads the primary action (trigger sync) and then mentions the inspection capability, though it could be improved by also covering the `configure` action.

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

  Completeness2/5

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

  The tool has no annotations, no output schema, and a description that covers only two of the three available actions. The `configure` action and its mode/conflict strategy parameters are missing from the narrative, leaving a meaningful gap for an agent deciding how to invoke this tool correctly.

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

  Parameters3/5

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

  The input schema provides 100% description coverage for all three parameters, including enum values and per-action descriptions. The tool description itself adds no parameter-level meaning, so the baseline of 3 is appropriate because the schema already does the heavy lifting.

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

  Purpose4/5

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

  The description states a specific purpose: triggering an Obsidian Sync cycle or inspecting synchronization state via obsidian-headless. It is clearly distinct from the sibling file/folder tools, though it omits the `configure` action that appears in the schema, so the purpose is not fully exhaustive.

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

  Usage Guidelines3/5

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

  The description implies the tool should be used when the agent needs an immediate sync or wants to check sync state. It provides no explicit when-not-to-use guidance, no alternatives, and no indication of how to choose among `status`, `sync`, and `configure` actions.

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

• create_folderB
  3.3/5.0
  Behavior2/5

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

  There are no annotations, so the description carries full responsibility for behavioral disclosure. It only says 'create' and gives no information about whether existing folders cause errors, whether intermediate directories are created automatically, or any side effects. The phrase 'directory hierarchy' hints at recursive creation but does not confirm behavior.

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

  Conciseness5/5

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

  The description is a single sentence that is front-loaded with the core action and resource. There is no filler or redundant information.

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

  Completeness3/5

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

  The tool is relatively simple with one well-documented parameter, so the description covers the basic call. However, it omits behavioral details like what happens if the folder already exists or whether nested directories are created, which an agent would benefit from knowing.

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

  Parameters3/5

  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 the 'path' parameter clearly with examples. The tool description adds no additional meaning about how the path is interpreted beyond the phrase 'directory hierarchy', which is already implied by the schema example.

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

  Purpose5/5

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

  The description states a specific verb, 'Create', a clear resource, 'a new folder or directory hierarchy', and the location, 'inside the Obsidian vault'. This clearly distinguishes it from sibling tools like read_note, write_note, or delete_item.

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

  Usage Guidelines2/5

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

  The description gives no guidance about when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The intended use is implied but never made explicit.

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

• patch_noteA
  3.5/5.0
  Behavior2/5

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

  With no annotations, the description carries the full burden, yet it only lists operation types and says 'existing note'. It does not disclose how multiple operations interact, whether they are applied atomically or in order, failure behavior when the note/heading is missing, frontmatter merge semantics, or any side effects. Some schema descriptions hint at behavior (e.g., replaceSection 'Replace or add'), but the tool description itself remains shallow.

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

  Conciseness5/5

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

  A single sentence with the core action front-loaded, followed by a complete parenthetical list of supported operations. No filler or redundant information; every word earns its place.

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

  Completeness3/5

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

  For a tool with 6 parameters, nested objects, and no output schema, the description plus schema covers parameter meaning well but leaves out critical behavioral context: whether operations can be combined, execution order, edge-case handling for missing headings or notes, and what the tool returns. It is adequate for a simple single-operation call but incomplete for complex patch scenarios.

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

  Parameters3/5

  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 a lightweight semantic grouping by naming the operations, which helps map natural language to parameters, but it does not explain parameter syntax or nuances beyond what the schema already provides.

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

  Purpose5/5

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

  The description clearly states the verb ('Perform'), resource ('existing Obsidian note'), and distinguishes this as 'fine-grained updates' rather than full writes. The parenthetical enumerates specific operation types (append, prepend, replace under heading, regex patch, update frontmatter), which makes the tool's purpose unmistakable and differentiates it from sibling tools like write_note.

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

  Usage Guidelines3/5

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

  The description implies usage for partial modifications to an existing note through 'fine-grained updates' and the operation list, but it never explicitly states when to prefer this over write_note or read_note, nor does it mention any exclusions. The context is inferable but not explicitly guided.

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

• write_noteA
  3.6/5.0
  Behavior3/5

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

  With no annotations, the description carries the full behavioral burden. It is transparent about being a mutating operation by saying 'Create or overwrite,' but it does not disclose that overwrite defaults to true, whether the operation is destructive to existing content, or what side effects may occur. The schema covers the overwrite parameter, but the description itself adds only partial behavioral context.

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

  Conciseness5/5

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

  The description is a single sentence with no filler. It front-loads the core action ('Create or overwrite') and includes the two most important content aspects, frontmatter and body, making it efficient and easy to parse.

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

  Completeness4/5

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

  For a 4-parameter tool with full schema coverage, the description is largely sufficient: it states the core purpose and the content structure. It does not describe the return value or the default overwrite behavior, but the schema documents the overwrite parameter, and the absence of an output schema makes return-value documentation less critical for correct invocation.

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

  Parameters3/5

  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 documented in the schema. The description adds some context by mentioning 'structured YAML frontmatter and body,' which maps to the frontmatter and body properties, but it does not provide extra meaning beyond the schema.

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

  Purpose4/5

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

  The description uses a specific verb ('Create or overwrite') and resource ('note in the Obsidian vault'), and it clarifies that both frontmatter and body are handled. It is clear enough to distinguish the tool from read_note and patch_note, though it does not explicitly name sibling alternatives.

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

  Usage Guidelines3/5

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

  The intended use case is implied by 'Create or overwrite a note,' so an agent can infer when to choose it. However, there is no explicit guidance about when to prefer patch_note for a non-destructive update or when overwrite should be avoided, leaving some routing decisions to inference.

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

• list_tasksA
  3.7/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral transparency burden. It usefully discloses that the tool scans the entire vault rather than a single note. It does not mention return format, sorting, or performance characteristics, but the aggregation framing makes unintentional mutation unlikely.

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

  Conciseness5/5

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

  The description is a single front-loaded sentence with no filler. Every word contributes meaning, and the checkbox syntax is concrete and useful.

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

  Completeness3/5

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

  The tool is simple and the schema covers parameters, but there is no output schema and the description does not clarify whether the result is a detailed list or a summary count. It also does not explain how list_tasks relates to search_vault, which would help an agent choose correctly.

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

  Parameters3/5

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

  All three parameters are fully documented in the input schema, so the baseline is 3. The description adds no further detail about tag, folder, or completed semantics beyond what the schema already provides.

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

  Purpose5/5

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

  The description names a specific operation—aggregating markdown task checkboxes—across a clear resource, the Obsidian vault. It also specifies the relevant syntax (- [ ] / - [x]), making the tool's purpose unambiguous and distinct from siblings like search_vault.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool: to collect task checkboxes across the vault. However, it does not explicitly contrast it with alternatives like search_vault or state when not to use it, leaving some routing to inference.

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

• search_vaultA
  3.7/5.0
  Behavior3/5

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

  There are no annotations, so the description carries the burden of behavioral disclosure. It conveys a read-only search operation and lists the searchable facets, but it does not disclose result ordering, default pagination behavior, or how filters combine. Search inherently implies non-destructive behavior, so this is acceptable but not rich.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no filler. Every phrase contributes a distinct search dimension, making it 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.

  Completeness3/5

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

  The schema fully documents all 6 parameters, and the description names the main search modes, so the tool is callable as-is. However, there is no output schema and no mention of return shape or matching behavior, which leaves a moderate gap for an agent predicting results.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description restates the main filter dimensions (keyword, tags, frontmatter, folder) but does not add meaning beyond the schema, especially for limit/offset or the exact frontmatter filter syntax.

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

  Purpose5/5

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

  The description uses a specific verb and resource ('Search vault notes') and enumerates the search dimensions: keyword, tags, frontmatter filters, and directory subpath. This clearly distinguishes it from sibling tools like read_note, get_vault_tree, or list_tasks.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool—when finding notes by keyword, tags, frontmatter, or folder—but it does not explicitly contrast it with alternatives or state when not to use it. Since no other search-specific sibling exists, the usage context is adequate but not fully explicit.

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

• analyze_workspace_graphA
  3.9/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the behavioral transparency burden. The verb 'Analyze' implies a read-only operation, and the listed analysis categories add useful context. Still, it does not explicitly state that the tool makes no changes, nor does it describe side effects or the nature of the returned result.

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

  Conciseness5/5

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

  The description is a single focused sentence that front-loads the primary action and then uses a colon to list the exact analysis outputs. Every word adds information and there is no filler or redundancy.

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

  Completeness3/5

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

  For a zero-parameter tool, invocation requirements are minimal and the description clearly states what will be analyzed. However, there is no output schema and no explicit description of the return format, so it is unclear whether results are counts, lists, or a report. Some usage and side-effect context is also missing.

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

  Parameters4/5

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

  The tool has zero parameters and the schema is an empty object with 100% coverage, so there are no parameter semantics to clarify. The baseline for zero-parameter tools is 4, and the description appropriately aligns with a no-argument invocation.

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

  Purpose5/5

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

  The description uses a specific verb ('Analyze') with a clear resource ('knowledge graph topology') and enumerates concrete outputs: nodes, wikilink edges, orphan notes, and dangling links. This distinguishes it from sibling tools like get_vault_tree or search_vault, which are about tree structure or content search rather than graph-level topology analysis.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool: whenever an agent needs graph topology information such as links, orphans, or broken links. However, it does not explicitly state when not to use it or name any sibling alternatives, leaving the usage context to inference.

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

• get_vault_treeA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the behavioral transparency burden. It clearly marks the operation as read-only ('Retrieve') and states what is returned, but it does not disclose traversal defaults, pagination, size limits, or any side-effect caveats.

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

  Conciseness5/5

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

  A single front-loaded sentence delivers the verb, object, scope, and purpose with no filler. Every word earns its place.

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

  Completeness4/5

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

  For a simple two-parameter getter with no output schema, the description adequately conveys core intent and the return concept. It could go slightly further by describing the shape of tree nodes, but the schema already covers parameter behavior, so nothing essential is missing.

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

  Parameters3/5

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

  Schema description coverage is 100%, so maxDepth and subfolder are already documented in the schema. The description adds only the conceptual context of a tree/overview and does not meaningfully enrich the parameter semantics beyond the baseline.

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

  Purpose5/5

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

  The description opens with a specific verb ('Retrieve') and a precise resource ('hierarchical directory tree of folders and notes in the vault'). The phrase 'for workspace overview' signals an aggregate, structural view, which distinguishes it from flat list_folders and query-based search_vault even without naming them.

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

  Usage Guidelines4/5

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

  It explicitly states the intended context ('for workspace overview'), so an agent can infer when this tool is appropriate. However, it provides no explicit exclusions or alternative routing guidance relative to sibling tools.

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

• read_noteA
  4/5.0
  Behavior4/5

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

  No annotations are provided, so the description must carry behavioral disclosure. It explicitly communicates a non-mutating read operation and lists exactly what will be returned, which is strong for a read-only tool. It does not describe ambiguity/error behavior, but that is a minor gap for this simple read operation.

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

  Conciseness5/5

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

  The description is a single front-loaded sentence with no filler. Every element—the read operation and the returned note components—adds useful information for an agent.

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

  Completeness4/5

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

  The tool is simple, has one fully documented parameter, and no output schema. The description compensates for the missing output schema by enumerating the return scope. It is complete for a straightforward read operation, even though it lacks explicit sibling-routing guidance.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already fully documents pathOrTitle with examples and meaning. The description adds no parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  Description states a specific verb ('Read') and resource ('an Obsidian note'), then details the returned components: frontmatter, body, metadata, wikilinks, and backlinks. This clearly distinguishes it from write_note, patch_note, delete_item, and search_vault.

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

  Usage Guidelines3/5

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

  The read verb implies the tool is for retrieving a full note, but there is no explicit guidance on when to use it instead of search_vault or other siblings. No 'use this when...' or 'use X instead...' guidance is provided; context is only implied.

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

• delete_itemA
  4.2/5.0
  Behavior4/5

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

  The description explicitly discloses that deletion is soft by default ('moves to .trash by default'), which is meaningful behavioral context beyond the schema. It does not restate the irreversibility of permanent deletion, but the schema's 'permanent' parameter description already conveys that. No annotation contradiction exists.

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

  Conciseness5/5

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

  A single sentence front-loads the action, target, and safety behavior with no filler. Every part of the description earns its place.

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

  Completeness4/5

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

  For a simple two-parameter delete tool, the description covers the affected resource and the default trash behavior, while the schema covers parameter semantics. It does not mention return or error behavior, but no output schema exists and the core deletion semantics are clear enough for correct invocation.

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

  Parameters3/5

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

  The input schema already describes both parameters thoroughly, so the description does not need to repeat them. The phrase 'moves to .trash by default' reinforces the permanent parameter's default behavior but does not add new semantic detail beyond what the schema provides.

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

  Purpose5/5

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

  The description names the exact verb ('delete') and resource ('note or folder'), and immediately states the key default behavior: moving to .trash. No sibling tool is a delete operation, so an agent can distinguish this tool without needing extra disambiguation.

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

  Usage Guidelines4/5

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

  The description clearly establishes what the tool operates on and what its safe default is, so invocation context is clear. It does not list alternatives, but none of the sibling tools compete for this action, so an explicit when-not-to-use clause is not necessary.

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