Server Quality Checklist

Tool Scores

• create_categoryC
  2.9/5.0
  Behavior2/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 states the tool creates categories but doesn't mention potential side effects (e.g., if creating duplicates is allowed, what permissions are required, or how errors are handled). This is insufficient for a mutation tool, as it leaves critical behavioral traits unspecified.

  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, clear sentence that directly states the tool's purpose without any unnecessary words. It is front-loaded and efficiently conveys the core functionality, making it easy for an agent to parse and understand quickly.

  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?

  Given the complexity of a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects like error conditions, return values, or interaction with sibling tools. For a tool that modifies data, more context is needed to ensure safe and correct usage by an agent.

  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 description adds no parameter-specific information beyond what the input schema already provides. Since schema description coverage is 100%, the baseline score is 3. The description doesn't elaborate on parameter usage, such as examples for 'category_path' beyond what's in the schema, so it doesn't add extra value.

  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 ('Create') and resource ('new category or subcategory in the knowledge base'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'move_category' or 'rename_category', which also involve category modifications, so it doesn't reach the highest score.

  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. For example, it doesn't mention whether to use 'create_category' for new categories versus 'move_category' for reorganizing existing ones, or if there are prerequisites like parent categories needing to exist first. This lack of context leaves the agent without usage direction.

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

• delete_categoryC
  2.9/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. It hints at destructive behavior ('delete') and optional recursion, but lacks details on permissions, irreversibility, error conditions, or response format. This is inadequate for a mutation tool with significant impact.

  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, efficient sentence with zero waste. It front-loads the core action and includes a key optional behavior, making it appropriately sized and structured.

  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?

  For a destructive mutation tool with no annotations and no output schema, the description is incomplete. It fails to address critical aspects like safety warnings, confirmation requirements beyond the 'confirm' parameter, or what happens upon success/failure, leaving significant gaps for agent usage.

  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 fully documents all parameters. The description adds no additional meaning beyond implying recursion affects 'contents', but this is already covered in the schema's 'recursive' description. Baseline 3 is appropriate as the schema 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 clearly states the verb ('Delete') and resource ('a category'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'move_category' or 'rename_category' in terms of destructive nature, though the action is distinct.

  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?

  No guidance is provided on when to use this tool versus alternatives (e.g., 'move_category' or 'rename_category' for reorganization instead of deletion). The description mentions optional content deletion but doesn't specify scenarios or prerequisites for use.

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

• delete_noteC
  2.9/5.0
  Behavior2/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 states the action ('Delete') but doesn't describe consequences (e.g., irreversible deletion, no confirmation prompt), permissions required, error conditions (e.g., if note doesn't exist), or response format. For a destructive tool with zero annotation coverage, this is a significant gap.

  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, efficient sentence with zero wasted words. It is appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration. Every word earns its place.

  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?

  Given the complexity (a destructive deletion tool), lack of annotations, and no output schema, the description is incomplete. It doesn't address behavioral aspects like irreversibility, permissions, or error handling, which are critical for safe tool invocation. The description should do more to compensate for missing structured data.

  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%, with both parameters ('category_path' and 'title') clearly documented in the schema. The description adds no parameter-specific information beyond what the schema provides. According to rules, when coverage is high (>80%), the baseline is 3 even with no param info in the 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 clearly states the verb ('Delete') and resource ('a note from the knowledge base'), making the purpose unambiguous. It distinguishes this from siblings like 'add_note', 'update_note', or 'get_note' by specifying deletion. However, it doesn't explicitly differentiate from 'delete_category', which targets a different resource type.

  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. It doesn't mention prerequisites (e.g., the note must exist), exclusions (e.g., cannot delete notes in read-only categories), or comparisons to siblings like 'delete_category' or 'update_note'. Usage is implied but not explicitly stated.

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

• get_noteC
  2.9/5.0
  Behavior2/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 states the tool retrieves content but does not mention potential errors (e.g., if the note doesn't exist), permissions required, rate limits, or the format of the returned content. This leaves significant gaps in understanding how the tool behaves beyond its basic function.

  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, direct sentence that efficiently conveys the core purpose without any unnecessary words. It is front-loaded with the key action and resource, making it highly concise and well-structured for quick understanding.

  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?

  Given the lack of annotations and output schema, the description is incomplete for a tool that retrieves data. It does not explain what is returned (e.g., note content, metadata, error handling), which is critical for an agent to use the tool effectively. The high schema coverage helps with inputs, but the overall context is insufficient.

  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, clearly documenting both required parameters ('category_path' and 'title') with examples. The description does not add any additional meaning beyond what the schema provides, such as explaining how these parameters uniquely identify a note or detailing edge cases, so it meets the baseline for high schema coverage.

  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 ('retrieve') and resource ('full content of a specific note'), making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like 'list_notes' or 'search_notes', which might retrieve multiple notes or partial content, so it falls short of a perfect score.

  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 such as 'list_notes' for browsing or 'search_notes' for filtering. It lacks context on prerequisites or exclusions, leaving the agent to infer usage from the purpose alone.

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

• move_categoryC
  2.9/5.0
  Behavior2/5

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

  With no annotations, the description carries full burden but only states the basic operation. It doesn't disclose behavioral traits such as whether the move is atomic, what happens to child categories/notes, permission requirements, error conditions (e.g., invalid paths), or if it's destructive (though 'move' implies mutation). This leaves significant gaps for a mutation tool.

  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, efficient sentence that directly states the tool's purpose with zero wasted words. It is appropriately sized and front-loaded, making it easy to parse quickly.

  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?

  Given this is a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavior (e.g., effects on hierarchy), error handling, or return values, which are critical for safe and effective use in a context with sibling tools like list_categories and delete_category.

  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%, with clear parameter descriptions in the schema (e.g., 'Current category path'). The tool description adds no additional parameter semantics beyond implying relocation context, so it meets the baseline of 3 where the schema 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 clearly states the action ('Move') and resource ('a category') with the specific operation 'to a different parent location'. It distinguishes from siblings like rename_category (which changes name but not location) and delete_category (which removes rather than relocates), though it doesn't explicitly name these alternatives.

  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?

  No guidance is provided on when to use this tool versus alternatives like rename_category or create_category. The description implies usage for relocation but doesn't mention prerequisites (e.g., existing categories), exclusions (e.g., moving to non-existent paths), or sibling tool relationships.

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

• update_noteC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full burden but offers minimal behavioral insight. It indicates a mutation ('Update') but doesn't disclose permissions needed, whether changes are reversible, error handling, or rate limits. This is inadequate for a mutation tool with zero annotation coverage.

  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, efficient sentence with zero waste, front-loading the core action ('Update an existing note') and key modifiable attributes. Every word earns its place, making it highly concise and well-structured.

  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?

  Given the tool's complexity as a mutation with 5 parameters and no output schema or annotations, the description is incomplete. It lacks details on behavioral traits (e.g., side effects, error cases), usage context, and return values, which are crucial for safe and effective agent 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 schema fully documents all 5 parameters. The description adds no additional meaning beyond implying that 'content' and 'tags' are updatable fields, which is already clear from the schema. Baseline 3 is appropriate as the schema handles parameter semantics effectively.

  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 verb ('Update') and resource ('an existing note'), specifying what fields can be modified ('content or tags'). It distinguishes from siblings like 'add_note' (create new) and 'delete_note' (remove), though it doesn't explicitly contrast with 'get_note' (read) or 'search_otes' (query).

  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?

  No guidance on when to use this tool versus alternatives is provided. It doesn't mention prerequisites (e.g., note must exist), exclusions (e.g., cannot update non-existent notes), or comparisons to siblings like 'add_note' for creation or 'delete_note' for removal, leaving usage context implied.

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

• add_noteB
  3.1/5.0
  Behavior2/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 states the tool creates a note and supports hierarchical categories, but doesn't mention permissions required, whether the operation is idempotent, error handling, or what happens on success/failure. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its 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, efficient sentence that front-loads the core purpose ('Create a new note in the knowledge base') and adds a useful detail ('supports hierarchical categories') without unnecessary elaboration. Every word earns its place, 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?

  Given the tool's moderate complexity (a mutation with 4 parameters) and no annotations or output schema, the description is minimally adequate. It covers the basic purpose and hints at category behavior, but lacks details on behavioral traits, error cases, or output format. For a creation tool in a knowledge base context, more completeness would be helpful, but it meets the minimum viable threshold.

  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 input schema fully documents all parameters. The description adds no additional parameter semantics beyond what's in the schema—it doesn't explain parameter interactions, constraints, or examples. With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

  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 ('Create a new note') and resource ('in the knowledge base'), which is specific and unambiguous. It also mentions support for hierarchical categories, which adds useful context. However, it doesn't explicitly differentiate from sibling tools like 'create_category' or 'update_note', which would be needed for a perfect score.

  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 'create_category' (for categories only) or 'update_note' (for modifying existing notes). It mentions hierarchical categories but doesn't clarify if this is the only way to add notes or if there are prerequisites. Without explicit when/when-not instructions, the agent must infer usage from context.

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

• list_categoriesB
  3.1/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. It states the output format ('hierarchical tree structure'), which adds value beyond the input schema, but doesn't disclose critical behavioral traits like whether it's read-only, paginated, rate-limited, or requires authentication. For a tool with zero annotation coverage, this is a significant gap.

  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, efficient sentence that front-loads the core purpose ('List all categories') and adds essential context ('in a hierarchical tree structure'). There is zero waste or redundancy, making it highly concise and well-structured.

  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?

  Given the tool's low complexity (one optional parameter, no output schema, no annotations), the description is minimally adequate. It covers the purpose and output format but lacks behavioral details and usage guidelines. For a simple read operation, this is borderline viable but leaves gaps an agent might need to infer.

  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 'parent_path' parameter fully. The description doesn't add any parameter-specific information beyond what's in the schema, such as examples of path formats or hierarchical implications. 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.

  Purpose4/5

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

  The description clearly states the verb ('List') and resource ('all categories'), specifying they are returned in a 'hierarchical tree structure'. It distinguishes from siblings like 'create_category' or 'move_category' by focusing on retrieval, but doesn't explicitly differentiate from other list operations like 'list_notes' beyond resource type.

  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?

  No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites, when to use 'parent_path' filtering, or how it compares to other category-related tools like 'create_category' or 'move_category'. The agent must infer usage from the tool name alone.

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

• search_notesB
  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 carries the full burden of behavioral disclosure. It mentions search functionality but lacks details on permissions, rate limits, pagination, or error handling. For a search tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves in practice.

  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, efficient sentence that directly states the tool's function without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse quickly, with no wasted 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?

  Given the tool's moderate complexity (search with multiple filters) and lack of annotations or output schema, the description is adequate but incomplete. It covers what the tool does but misses behavioral aspects like result format or limitations. For a search tool, this leaves room for improvement in guiding the agent effectively.

  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 fully documents all four parameters. The description adds minimal value by listing the search criteria ('query, category path, or tags') but doesn't provide additional syntax, examples, or constraints beyond what's in the schema, meeting the baseline for high coverage.

  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 ('Search through') and resource ('all notes') with specific search criteria ('by query, category path, or tags'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'list_notes' or 'get_note', which could also retrieve notes, so it doesn't reach the highest score.

  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 'list_notes' or 'get_note'. It mentions search capabilities but doesn't specify scenarios where searching is preferable to listing or retrieving specific notes, leaving the agent to infer usage from context alone.

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

• rename_categoryB
  3.2/5.0
  Behavior2/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. It mentions the tool renames a category but doesn't disclose behavioral traits like whether it requires specific permissions, if the rename is reversible, what happens to child elements, or error handling for invalid paths. This is a significant gap for a mutation tool with zero annotation coverage.

  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, efficient sentence that front-loads the core action ('Rename a category') and adds a clarifying constraint ('while keeping it in the same parent location'). There is zero wasted text, making it highly concise and well-structured.

  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?

  Given the tool is a mutation operation with no annotations and no output schema, the description is incomplete. It lacks details on behavioral aspects like permissions, reversibility, effects on related data, and error scenarios. For a tool that modifies data, this leaves significant gaps in understanding how to use it 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 100%, so the schema already documents both parameters ('old_path' and 'new_name') with clear descriptions. The description adds no additional meaning beyond what the schema provides, such as format examples or constraints, resulting in the baseline score of 3.

  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 ('Rename a category') and specifies the scope ('while keeping it in the same parent location'), which distinguishes it from 'move_category' that likely changes parent location. However, it doesn't explicitly differentiate from 'update_note' or other update operations, keeping it at 4 rather than 5.

  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 by specifying 'keeping it in the same parent location,' which suggests when to use this vs. 'move_category.' However, it doesn't provide explicit guidance on when to use this tool vs. alternatives like 'create_category' or 'delete_category,' or mention prerequisites such as existing category paths.

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

• list_notesB
  3.3/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden for behavioral disclosure. It mentions filtering and recursive behavior, but lacks details on permissions, rate limits, pagination, return format, or whether it's read-only. For a list operation with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves beyond basic functionality.

  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, efficient sentence that front-loads the core action ('List all notes') and includes key optional features. There is zero waste, and every word earns its place by conveying essential information without redundancy or unnecessary elaboration.

  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?

  Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose and filtering options, but lacks details on behavioral aspects like permissions, output format, or error handling. Without annotations or output schema, more context would be helpful for safe and effective use.

  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 input schema already documents all three parameters thoroughly. The description adds minimal value by mentioning 'optionally filtered by category path or tag,' which aligns with schema details but doesn't provide additional semantics beyond what's in the schema. With high schema coverage, the baseline score of 3 is appropriate.

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

  Purpose4/5

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

  The description clearly states the verb ('List') and resource ('notes') with optional filtering capabilities. It distinguishes from 'get_note' (singular retrieval) and 'search_notes' (likely broader search), but doesn't explicitly differentiate from 'list_categories' which handles different resources. The purpose is specific but sibling differentiation could be more explicit.

  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 context through 'optionally filtered by category path or tag,' suggesting when to use filtering parameters. However, it doesn't provide explicit guidance on when to choose this tool versus alternatives like 'search_notes' or 'list_categories,' nor does it mention prerequisites or exclusions. Usage is implied rather than clearly defined.

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