Server Quality Checklist

Tool Scores

• delete_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 mentions the 'permanent' parameter and return format, but lacks critical details: it doesn't specify if deletion is reversible, what permissions are required, whether it affects linked resources, or error conditions. For a destructive operation, this leaves significant gaps.

  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 well-structured with clear sections for Args and Returns, and each sentence is purposeful. It could be slightly more concise by integrating the purpose into the Args section, but overall it avoids redundancy and is easy to parse.

  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 deletion tool with no annotations and no output schema, the description is insufficient. It doesn't cover behavioral aspects like side effects, error handling, or return value specifics, which are crucial for safe invocation. The tool's destructive nature demands more comprehensive 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 0%, so the description must compensate. It explains both parameters ('note_id' and 'permanent'), adding meaning beyond the bare schema. However, it doesn't detail format constraints for 'note_id' or clarify the implications of 'permanent' beyond the basic boolean choice, leaving room for improvement.

  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 Joplin'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'update_note' or 'create_note' beyond the obvious action difference, which prevents 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?

  No guidance is provided on when to use this tool versus alternatives. For example, it doesn't mention if this should be used instead of 'update_note' for removal scenarios, or if there are prerequisites like checking note existence first. The description only states what it does, not when to apply it.

  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 a note, implying a read-only operation, but doesn't mention permissions, error handling (e.g., if ID is invalid), or performance aspects. It adds minimal context beyond the basic action, leaving gaps in understanding how it behaves.

  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 appropriately sized and front-loaded, with the main purpose stated first. The 'Args' and 'Returns' sections add structure but are concise. Every sentence contributes, though the 'Returns' section could be more informative, keeping it efficient overall.

  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 (1 parameter, no output schema, no annotations), the description is minimally complete. It covers the basic operation and parameter, but lacks details on usage, behavior, and output specifics. It's adequate for a simple retrieval tool but has clear gaps in providing full 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?

  The schema description coverage is 0%, so the description must compensate. It adds meaning by explaining that 'note_id' is the 'ID of the note to retrieve', which clarifies the parameter's purpose. However, it doesn't provide details like format, constraints, or examples, only basic semantics, resulting in a baseline score.

  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's purpose with a specific verb ('Get') and resource ('note'), specifying it retrieves a note by ID. It distinguishes from siblings like 'create_note' or 'search_notes' by focusing on retrieval of a specific item, though it doesn't explicitly contrast with 'update_note' or 'delete_note' in terms of operation 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 mentions retrieving by ID but doesn't specify contexts like needing a known ID, or when to prefer 'search_notes' for unknown IDs. No exclusions or prerequisites are stated, leaving usage unclear relative to siblings.

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

• import_markdownC
  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 a new note, implying a write operation, but doesn't cover critical aspects like permissions required, whether it overwrites existing notes, error handling for invalid files, or rate limits. This leaves significant gaps in understanding the tool's behavior.

  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 front-loaded with the core purpose in the first sentence, followed by structured sections for args and returns. It avoids unnecessary fluff, but the 'Args' and 'Returns' sections could be more integrated into the flow rather than bullet-like, and some redundancy exists (e.g., 'args: Import parameters' is somewhat tautological).

  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 (a write operation with no annotations and no output schema), the description is insufficient. It lacks details on the return value (only mentions 'Dictionary containing the created note data' without structure), error cases, and how it interacts with sibling tools. For a mutation tool, this leaves the agent under-informed.

  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 adds value by explaining that 'file_path' is the 'Path to the markdown file', which clarifies the parameter's purpose beyond the schema's bare 'string' type. However, it doesn't detail format constraints (e.g., absolute vs. relative paths, file extensions), so it only partially addresses the coverage gap.

  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 ('Import a markdown file') and the outcome ('as a new note'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'create_note' or 'update_note', which might also create or modify 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 'create_note' or 'update_note'. It mentions the action but doesn't specify prerequisites (e.g., file must exist), exclusions, or contextual usage, leaving the agent with minimal direction.

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

• search_notesC
  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. While it mentions the tool returns a 'Dictionary containing search results', it doesn't specify what that dictionary contains (e.g., note IDs, titles, content snippets), whether results are paginated, or any performance considerations like rate limits. For a search tool with zero annotation coverage, this leaves critical behavioral traits unclear.

  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 appropriately sized and front-loaded, starting with the core purpose. The Args and Returns sections are structured clearly, though the 'args' parameter could be more directly explained. There's minimal waste, but the nested parameter explanation could be slightly more concise.

  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 (search functionality with parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't explain the return value structure, error handling, or how results are ordered/filtered. For a tool that likely returns multiple results, this leaves too much ambiguity for 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?

  The description adds some parameter semantics beyond the input schema, which has 0% description coverage. It explains that 'args' contains 'Search parameters' and details 'query' as a 'Search query string' and 'limit' with a default of 100. However, it doesn't clarify the query syntax (e.g., wildcards, operators) or what 'limit' applies to (e.g., per page, total results), leaving gaps in 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's purpose: 'Search for notes in Joplin.' This specifies the verb ('Search') and resource ('notes in Joplin'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_note' or 'import_markdown', which prevents 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. It doesn't mention scenarios where search is preferable over 'get_note' for retrieving specific notes or how it complements other tools like 'create_note' or 'update_note'. This lack of contextual usage advice is a significant gap.

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

• update_noteB
  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 states the tool updates a note and returns updated data, but lacks critical details: it doesn't mention authentication needs, rate limits, whether updates are partial or full (optional params suggest partial), error handling (e.g., invalid note_id), or side effects (e.g., timestamp changes). The description covers basic intent but misses operational context essential for safe use.

  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 well-structured and appropriately sized. It front-loads the purpose in the first sentence, followed by organized sections for Args and Returns. Each sentence earns its place by providing essential information without redundancy. Minor improvements could include integrating parameter details more seamlessly, but overall it's efficient and clear.

  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 complexity (mutation with 5 parameters), lack of annotations, and no output schema, the description is moderately complete. It covers the basic operation and parameters but lacks behavioral context (e.g., permissions, errors) and output details (only mentions 'dictionary containing the updated note data' without structure). For a mutation tool, this leaves gaps that could hinder effective use by an agent.

  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. It adds significant value by listing all parameters (note_id, title, body, parent_id, is_todo) with brief semantics (e.g., 'ID of note to update,' 'New title (optional)'), clarifying their roles beyond schema titles. However, it doesn't explain parameter interactions (e.g., if parent_id changes folder location) or constraints (e.g., format of note_id), leaving some gaps.

  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's purpose: 'Update an existing note in Joplin.' It specifies the verb ('Update') and resource ('note'), and distinguishes it from siblings like create_note, delete_note, and get_note by focusing on modification rather than creation, deletion, or retrieval. However, it doesn't explicitly differentiate from other update-like operations (if any exist beyond these siblings).

  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., needing an existing note_id), compare it to create_note for new notes or get_note for viewing, or specify scenarios where updating is appropriate (e.g., editing content vs. moving folders). Usage is implied by the action 'update,' but no explicit context or exclusions are given.

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

• create_noteB
  3.4/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 a note but does not mention permissions required, whether the operation is idempotent, error handling, or rate limits. For a mutation tool, this lack of behavioral context is a significant gap, though it doesn't contradict annotations.

  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 appropriately sized and front-loaded, starting with the core purpose. The structured 'Args' and 'Returns' sections are efficient, though 'args: Note creation parameters' is slightly redundant. Every sentence adds value, making it concise with minimal waste.

  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 complexity (a mutation with 1 parameter but nested properties), no annotations, and no output schema, the description is moderately complete. It covers parameter semantics well but lacks behavioral details and return value specifics. For a creation tool, it should ideally mention what 'created note data' includes or error cases, leaving room for improvement.

  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 description adds substantial meaning beyond the input schema, which has 0% schema description coverage. It explains each parameter's purpose (e.g., 'Note title', 'Note content in Markdown'), clarifies optionality, and provides context like 'ID of parent folder'. This compensates well for the schema's lack of descriptions, though it could detail format constraints (e.g., Markdown specifics).

  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 specific action ('Create a new note') and resource ('in Joplin'), distinguishing it from sibling tools like delete_note, get_note, update_note, search_notes, and import_markdown. It precisely identifies the tool's function without being vague or tautological.

  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 update_note or import_markdown. It lacks context about prerequisites, such as whether a parent folder must exist, or exclusions, such as when not to create a note. This absence 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.