Server Quality Checklist

Tool Scores

• delete_noteA
  4.2/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses the non-destructive behavior (trash not permanent deletion), preservation of directory structure, recoverability, and the WRITE_VAULT guard. This goes beyond basic expectations and would alert an agent to the safety and requirements of the 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?

  Three sentences with no redundancy; the critical behavior and error condition are front-loaded. Every sentence adds meaningful 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 description covers behavior and error conditions, and an output schema exists. However, it fails to define what the 'source' parameter actually is (note path/ID), leaving the primary input ambiguous. It's adequate for a one-parameter tool but not fully complete.

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

  Parameters2/5

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

  The 'source' parameter is undocumented in the schema (0% coverage) and the description never mentions it directly. While 'note' and 'vault' imply what it refers to, no format, path semantics, or validation constraints are provided, leaving the primary input ambiguous.

  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 tool's function: moving a note to the .trash folder rather than deleting it permanently. This specific verb+resource pairing distinguishes it from siblings like move_note by specifying the trash destination and recoverability.

  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 provides clear context that this is a soft-delete operation and mentions the WRITE_VAULT requirement. However, it does not explicitly state when to choose this over move_note or other alternatives, nor does it provide exclusion criteria, so it lacks explicit when/when-not guidance.

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

• update_noteA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and does disclose key behavioral details: the 'overwrite' mode replaces entire content, 'append' adds to the end, and it refuses with a structured error if the target vault is not WRITE_VAULT. This goes beyond a simple 'updates a note' statement. However, it does not explain what happens if the note does not exist or other error scenarios, which prevents a perfect score.

  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 two sentences, front-loaded with the core purpose, and every phrase adds value. It covers the key modes and a critical constraint without any fluff or redundancy.

  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?

  Given an output schema exists, return values need not be described. The description covers the main operation and a key error condition. However, completeness is slightly reduced because it does not mention errors for non-existent notes or invalid mode values, which are relevant for a simple update tool. Still, the description is largely sufficient for an agent to use the 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?

  Schema description coverage is 0%, so the description must compensate. It thoroughly explains the 'mode' parameter with its allowed values and effects, which is very helpful. However, it does not elaborate on 'source' or 'content'—these are left to inference. 'Content' is self-explanatory, but 'source' could be ambiguous (path vs. ID), so the description only partially compensates for the missing schema documentation.

  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 starts with 'Update an existing note,' which clearly identifies the action and resource. The sibling list includes create_note, delete_note, move_note, etc., making this tool's purpose distinct as the update operation. The mention of modes further clarifies the behavior.

  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 implies this tool is for modifying existing notes, as opposed to creating or deleting them. It also explains the two allowed modes ('overwrite' and 'append'), giving the user context for when each is appropriate. However, it does not explicitly mention when not to use this tool or compare it to alternatives beyond the implicit distinction.

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

• lint_noteA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the key behavioral trait of no disk write and specifies the return structure (valid/errors/warnings). This adds meaningful context about what the tool does and does not do, though it omits details like validation strictness or potential side effects beyond the basic read-only nature.

  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 concise and front-loaded: it states the purpose in the first sentence, the return format in the second, and usage guidance at the end. No wasted words; every sentence adds value.

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

  Completeness5/5

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

  For a simple tool with a single parameter and an output schema, the description covers the essential aspects: what it does, side effects, return format, and when to use it. The output schema fills in the return structure, so the description is sufficiently complete for an agent 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 schema only provides 'content' as a string with no further description. The description adds that it is 'markdown content', which provides some semantic context. However, it does not explain validation rules or what constitutes valid content, and with 0% schema description coverage, the description only partially compensates for the lack of parameter detail.

  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 tool's purpose with a specific verb ('pre-validate') and resource ('markdown content'), and explicitly notes it does not write to disk. This distinguishes it from sibling write tools like create_note and update_note, as well as read/list/move/delete operations.

  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 gives explicit usage guidance: 'Use this to check content before calling create_note or update_note.' This clearly indicates when to use the tool, though it does not provide explicit when-not-to-use scenarios beyond the context of writing. The 'without writing it to disk' statement further clarifies the distinction.

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

• read_noteA
  4.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 carries the full burden of behavioral disclosure. It discloses the return value (full markdown content), the source path format (vault/relative/path.md), and the filesystem path resolution (HOST_VAULT_PATH / source). This provides useful behavioral context beyond a simple 'read note' and implies a read-only 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 three concise sentences with no redundant words. Each sentence contributes: what it does, the source format, and the path resolution. It is front-loaded with the primary purpose and efficiently conveys all necessary information.

  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?

  Given the tool's simplicity (one parameter, read-only) and the presence of an output schema, the description is largely complete. It specifies input format and output content. It does not explicitly address error cases (e.g., missing note), but the output schema likely covers the return shape. This is adequate for the complexity level.

  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?

  Schema coverage is 0% for the single 'source' parameter, so the description must compensate. It does so by explaining the expected format ('vault/relative/path.md') and its origin ('as returned by search_notes'), plus how the full path is resolved. This adds meaningful semantics beyond the bare schema definition.

  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 tool's purpose: 'Return the full markdown content of a note.' This is a specific verb+resource pair and distinguishes from siblings like delete_note, update_note, and list_notes. The mention of 'full markdown content' clarifies the output scope.

  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 implies usage context by indicating the source format is 'as returned by search_notes', which guides the agent to first use search_notes. It does not explicitly name alternatives or exclusions, but the sibling names (delete_note, move_note, etc.) are self-explanatory. This is clear context though not an explicit when/when-not.

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

• list_notesA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the return format (vault/relative/path.md), compatibility with search_notes and read_note, and the recursive behavior with a clear flag explanation. This gives the agent an accurate mental model of the tool's output and scoping 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?

  Three sentences, each earning its place: purpose, output format/interoperability, and recursion control. Very efficient and well-structured, front-loading the primary purpose.

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

  Completeness5/5

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

  Given the moderate complexity (3 params, return format) and presence of an output schema, the description adequately covers purpose, output format, chaining, and a specific parameter behavior. No significant gaps remain.

  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?

  Schema coverage is 0%, so the description must compensate. It explains folder scoping ('optionally scoped to a subfolder') and the recursive parameter ('Set recursive=False to list only the immediate folder'). The vault parameter is not explicitly described but is self-evident from the tool name and schema.

  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 tool lists note paths within a vault, with an optional subfolder scope. This specific verb+resource combination distinguishes it from sibling tools like read_note (which reads content) and delete_note (which deletes).

  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 provides clear context by explaining the output format matches search_notes and can be passed to read_note, which implies when to use it (enumeration) and how to chain it. It does not explicitly state when not to use it (e.g., for file content), but the purpose is unambiguous.

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

• create_noteA
  4.7/5.0
  Behavior5/5

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

  With no annotations provided, the description carries full responsibility for disclosing behavioral traits. It clearly states error behavior (refuses with structured error for non-WRITE_VAULT), overwrite protection (refuses unless overwrite=True), and side effects (creates intermediate directories). This goes beyond basic functionality to cover permission constraints and destructive actions, which are critical for an agent to use safely.

  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 three sentences long, each sentence delivering distinct and necessary information: the core action, safety/error conditions, and side effects. It is front-loaded with the primary purpose and contains zero filler. Every word earns its place, making it both concise and highly structured.

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

  Completeness5/5

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

  The tool has a straightforward creation task, yet the description covers all critical aspects: path format, permission restrictions, overwrite behavior, and directory creation. Since an output schema is present, the description appropriately skips return value details. For a 3-parameter tool with no annotations, it provides a complete operational picture without over-engineering.

  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?

  Schema description coverage is 0%, so the description must compensate for the bare schema. It adds meaning to 'source' by defining the format (vault/relative/path.md) and to 'overwrite' by explaining the refusal behavior unless it is True. 'content' is not explicitly described, but it is self-evident as the note body. It adds significant value for two of the three parameters, with the remaining one being intuitive.

  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 starts with 'Create a new note at source (vault/relative/path.md format),' which clearly states the verb ('Create'), resource ('note'), and a specific path format. This precisely distinguishes it from sibling tools like update_note, delete_note, and read_note. It unambiguously identifies the tool's core function.

  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 gives operational context: it can create notes only in WRITE_VAULT, it won't overwrite without overwrite=True, and it auto-creates intermediate directories. While it doesn't explicitly say 'use this instead of update_note when the note does not exist yet,' the term 'new note' and refusal to overwrite imply this. No alternative tools are named, so it's clear context without explicit exclusions.

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

• move_noteA
  4.8/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden and does so thoroughly. It discloses the no-overwrite failure condition, create_dirs default behavior, and the wikilink rewriting side effect. It also specifies the exact return object shape, providing exceptional transparency for a mutating 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 five focused sentences, front-loaded with the core action and followed by important conditions and return info. No filler or redundant content; each sentence contributes essential semantics. The line breaks aid readability without adding bulk.

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

  Completeness5/5

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

  Given the moderate complexity, the description covers all critical aspects: path constraints, overwrite prevention, directory creation, link rewriting side effect, and return values. Even though an output schema exists, the description redundantly but helpfully states the return shape. Sibling tools are distinct, and no major context is missing.

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

  Parameters5/5

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

  Schema coverage is 0%, but the description fully compensates by explaining the path format for source_path/dest_path, the boolean default for create_dirs, and the constraint that both paths must be in WRITE_VAULT. It adds meaning beyond the bare schema by specifying behavior like failing on existing dest_path and directory creation.

  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 the specific verb 'Move' with source_path and dest_path, clearly identifying the tool's operation. It also distinguishes this from sibling tools like create_note and update_note by describing a file relocation with path requirements. The vault/relative/path.md format further clarifies the domain.

  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 provides strong contextual guidance: both paths must be within WRITE_VAULT, no overwrite is allowed, and create_dirs defaults to true. It does not explicitly mention alternatives or when-not-to-use, but the constraints and behavior make appropriate usage clear. A slight deduction for not naming alternative sibling tools or exclusion cases.

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