Server Quality Checklist

Tool Scores

• list_notesB
  3.4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly conveys a read-only enumeration action and the two scope choices, but it does not mention path format, sorting, recursion, or how project inference from the working directory behaves at runtime. This is adequate but not rich 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 front-loaded sentence with no filler: 'List note paths' appears immediately, and the scope alternatives are stated compactly. 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 list tool with two optional parameters and no output schema, the description plus the fully-documented schema is nearly sufficient for correct invocation. It lacks an explicit contrast with search_notes but otherwise covers the essential action and scoping context.

  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 coverage for parameters is 100%, so the baseline is 3. The description reinforces the 'project' vs 'vault' scope semantic and the project-folder notion, but it adds no parameter details beyond what the schema already documents. It does not explain path formats or inference fallbacks beyond the schema description.

  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 names a specific verb ('List') and resource ('note paths'), and introduces a meaningful scope distinction between the project folder and the whole vault. It is clear and unambiguous, though it does not explicitly differentiate itself from the sibling search_notes, which could also return note paths when filtering by content.

  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 on when to prefer this tool over alternatives such as search_notes, and does not mention any prerequisites or exclusions. While the scoping options are clear, the agent is left to infer when listing is the appropriate operation.

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

• read_noteA
  3.6/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 correctly indicates a read operation scoped to the vault, implying no modification, but it does not describe return format, error behavior for missing notes, or path resolution details.

  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?

  One clear, front-loaded sentence with no filler. It states the action, target, and scope succinctly, 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.

  Completeness4/5

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

  Given the low complexity and full schema coverage, the description is sufficiently complete for a simple read operation. The absence of an output schema is partially mitigated by 'full contents,' though explicit return/error details would be even stronger.

  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 well documented. The description adds no parameter-specific information beyond 'full contents,' which is adequate but does not raise the score above the baseline.

  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 action 'Read' the resource 'a note's full contents' and scopes it to the project's vault folder. It is distinct enough from the sibling list/search tools, though it does not explicitly name them.

  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 phrase 'full contents' implicitly conveys use when the full note body is needed rather than metadata or search results, but there is no explicit guidance on when to use this tool versus siblings like list_notes or search_notes.

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

• search_notesA
  3.8/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 disclosure burden. It does disclose meaningful behavior: case-insensitive matching and the result format. However, it does not mention result ordering, whether the query is plain text or regex, or how limit interacts with matching — leaving some behavior opaque.

  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 that starts with the core action and immediately gives the result format. Every word earns its place, with no redundant filler.

  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 search tool, the description plus schema covers the invocation needs: query behavior, return shape, default scope, and limit constraints. It is slightly incomplete only in not comparing with list_notes or explaining result ordering, but this is a minor gap given the tool's simplicity.

  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 has 100% description coverage, so the baseline is 3. The description adds the case-insensitive detail but does not otherwise clarify parameter semantics beyond what the schema already provides for query, limit, scope, and project.

  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 a specific verb and resource: 'Case-insensitive text search over note contents'. It also defines the return shape ('matching lines with their note path and line number'), which makes the tool's function precise and distinguishable from the sibling tools like list_notes or read_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: use this when you need to find text within note contents rather than listing or reading notes. However, it does not explicitly mention alternatives or when not to use this tool, leaving the agent to infer routing from sibling names and context.

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

• write_noteA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden and does well by disclosing the non-clobbering default, the overwrite escape hatch, and automatic project folder creation. These are meaningful behavioral details beyond a simple 'create a note' statement.

  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 short sentences with no filler. The primary action is front-loaded, and the overwrite and folder-creation behaviors are stated economically without 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?

  For a write tool with no output schema and no annotations, the description covers the main action, the clobbering edge case, and the folder-creation side effect. It could mention return behavior or explicitly route to append_note for existing notes, but the core usage is adequately covered.

  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 schema already describes all four parameters, so the baseline is 3. The description adds value by explaining the overwrite behavior and the automatic folder creation tied to the project parameter, which enriches understanding beyond the raw 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 opens with a specific verb and resource: 'Create a note in the project's vault folder.' It clearly differentiates the tool from siblings like append_note, read_note, and search_notes because it focuses on creation behavior.

  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 clearly implies that this tool is for creating notes, but it does not explicitly state when to prefer append_note or another sibling. It gives behavioral context such as refusing to overwrite, but no direct when-to-use vs. alternatives guidance.

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

• resolve_projectA
  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 behavioral disclosure burden. The phrase 'Report' and 'before writing' clearly indicate a non-mutating, read-only operation that does not create or modify notes, and it promises an explanation of the decision rather than just a result. This usefully communicates the tool's side of the contract.

  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?

  Two short sentences deliver the core behavior and the intended usage moment with no filler. The most important information is front-loaded, and every word contributes to agent understanding.

  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 one-parameter, read-only tool with no output schema, the description is complete: it states what is reported, how the decision is surfaced, and when to use it. The schema covers the parameter, and the sibling tools provide enough surrounding context to place this operation in the workflow.

  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 only parameter, 'project', is fully described in the schema (including the omit-to-infer behavior), so schema coverage is 100%. The description adds conceptual context by mentioning 'inference,' but it does not need to add parameter-level details since the schema already handles them.

  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 a specific verb ('Report'), a concrete resource ('which project folder notes will go to'), and the method ('how that was decided'). It distinguishes itself from sibling note-manipulation tools by framing this as a pre-write decision check rather than a note operation.

  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 explicitly says 'Use this to check the inference before writing,' giving a clear usage context tied to the write workflow. It does not explicitly name alternatives or exclusion cases, but the context is unambiguous enough for an agent to know when to invoke it.

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

• append_noteA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It explicitly reveals the create-if-absent behavior and implies mutation through 'Append'. It could add details about permissions or side effects, but the key behavioral trait is communicated.

  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?

  Two sentences with no wasted words. The primary action is front-loaded, followed immediately by the most important behavioral nuance and a usage directive.

  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 3-parameter tool with no output schema, the description covers purpose, behavior, and usage context. It does not explicitly mention return values or error cases, but the tool is simple enough that these are not critical gaps.

  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 100%, so baseline is 3. The description adds meaning beyond the schema by clarifying that the note parameter results in creation if absent, and by framing content as suitable for running logs. This enriches parameter understanding.

  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 ('Append') and resource ('to the end of a note'), and clearly states the create-if-absent behavior. It also distinguishes itself from the alternative of rewriting the whole note, aligning with sibling tool 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 Guidelines4/5

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

  'Use this for running logs instead of rewriting the whole note' provides explicit context for when to use this tool and an exclusion against a rewrite approach. It does not name the exact sibling tool, but the intent is clear enough for an agent to route correctly.

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