Server Quality Checklist

Tool Scores

• get_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 tool retrieves a note by ID but doesn't cover critical aspects like error handling (e.g., what happens if the note doesn't exist), authentication requirements, rate limits, or whether it's read-only (implied but not confirmed). This leaves significant gaps for safe and effective 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 concise, using clear sections for 'Args' and 'Returns.' It avoids unnecessary details, though the 'Returns' section could be more specific (e.g., mentioning fields like title or content). Overall, it's efficient but not perfectly front-loaded, as the core purpose is stated upfront.

  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 (single parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic operation and parameter but lacks details on behavior, error handling, and output structure. Without annotations or an output schema, users must infer return values from the vague 'Dictionary containing the note data,' which is insufficient for reliable 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 minimal semantics beyond the input schema. It explains that 'note_id' is the 'ID of the note to retrieve,' which clarifies the parameter's purpose but doesn't provide format details (e.g., UUID, numeric) or constraints. With 0% schema description coverage, this is a baseline score—it compensates slightly but not fully for the lack of schema documentation.

  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: 'Get a specific note by ID.' It uses a specific verb ('Get') and resource ('note'), making it easy to understand. However, it doesn't explicitly differentiate from siblings like 'search_notes' (which likely retrieves multiple notes based on criteria), 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. It doesn't mention siblings like 'search_notes' for retrieving multiple notes or 'create_note'/'update_note' for write operations. Without this context, users might struggle to choose the right tool in scenarios requiring note retrieval.

  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?

  No annotations are provided, so 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 permissions, error handling, or side effects. It mentions a return value ('Dictionary containing the created note data') but lacks details on structure or potential failures.

  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's efficient with minimal waste, though the 'args' section could be more directly integrated. Overall, it's appropriately sized for the tool's complexity.

  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 no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It covers the basic operation and parameter but lacks details on behavioral traits, error cases, and return value structure. For a write tool with undocumented parameters, this leaves significant gaps for an AI 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?

  Schema description coverage is 0%, so the description must compensate. It documents one parameter ('file_path: Path to the markdown file'), which matches the single parameter in the schema. However, it doesn't explain format expectations (e.g., absolute vs. relative paths, file extensions) or validation rules, 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: 'Import a markdown file as a new note.' This specifies the verb ('import'), resource ('markdown file'), and outcome ('new note'). However, it doesn't explicitly differentiate from sibling tools like 'create_note', which might create notes from other sources.

  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 sibling tools like 'create_note' for non-markdown creation or 'search_notes' for finding existing notes. There's no context about prerequisites, such as file accessibility or format requirements.

  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?

  With no annotations provided, the description carries full burden but provides minimal behavioral context. It mentions that it 'returns a dictionary containing search results' but doesn't describe what that dictionary contains, whether results are paginated, how sorting works, or any performance characteristics. For a search tool with zero annotation coverage, this leaves significant gaps in understanding how the tool 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 with a clear purpose statement followed by parameter documentation. The Args/Returns structure is helpful, though the 'args' wrapper adds some redundancy. Every sentence serves a purpose, though the 'Dictionary containing search results' could be more informative.

  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 no annotations, no output schema, and a single parameter with 0% schema coverage, the description provides basic functionality but lacks important context. It explains what the tool does and documents parameters, but doesn't cover return format details, error conditions, or how this search differs from other retrieval methods. For a search tool, more behavioral context would be expected.

  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 parameter information beyond the schema, explaining that 'args' contains 'query: Search query string' and 'limit: Maximum number of results (default: 100)'. Since schema description coverage is 0%, this compensates somewhat. However, it doesn't explain query syntax, what fields are searched, or how the limit parameter interacts with pagination.

  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 'Search for notes in Joplin' - a specific verb ('search') and resource ('notes in Joplin'). It distinguishes from siblings like create_note or delete_note by focusing on retrieval rather than mutation. However, it doesn't explicitly differentiate from get_note which might also retrieve notes.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives like get_note or other search tools. There's no mention of prerequisites, context for searching versus direct retrieval, or any exclusions. The only implied usage is for finding notes based on a query.

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

• delete_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 mentions the 'permanent' parameter hinting at deletion behavior, but doesn't clarify critical aspects like whether deletion is reversible by default, what permissions are required, or what the 'operation status' dictionary contains. This is insufficient for a destructive operation.

  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 efficiently structured with a clear purpose statement followed by parameter and return sections. Every sentence adds value, though the return statement could be slightly more informative. It's appropriately sized without 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 this is a destructive tool with no annotations and no output schema, the description should provide more complete context. While it covers parameters adequately, it lacks details on behavioral implications, error conditions, and the structure of the return value. This leaves gaps in understanding the tool's full impact.

  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 meaningful context for both parameters beyond the schema's 0% coverage. It explains that 'note_id' identifies which note to delete and that 'permanent' controls whether deletion is permanent. This compensates well for the schema's lack of descriptions, though it could elaborate on format expectations for 'note_id'.

  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 immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'update_note' or 'create_note' beyond the obvious action difference, which keeps it from 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. For example, it doesn't mention if this should be used instead of 'update_note' for removal scenarios or if there are prerequisites like confirming note existence first. This leaves the agent without contextual usage direction.

  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 this is an update operation, implying mutation, but doesn't cover permissions needed, whether changes are reversible, error handling (e.g., invalid note_id), or rate limits. The return statement mentions 'updated note data' but lacks detail on format or potential side effects.

  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 (Args, Returns) and uses bullet points for parameters, making it easy to scan. It's appropriately sized for a tool with multiple parameters, though the 'args' wrapper in the description adds minor redundancy with the schema.

  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 no annotations and no output schema, the description provides basic purpose and parameter info but lacks behavioral details (e.g., mutation effects, error cases) and return value specifics. For a mutation tool with 1 parameter (though nested with 5 sub-parameters), this is minimally adequate but has clear gaps in completeness.

  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 provides a clear list of parameters (note_id, title, body, parent_id, is_todo) with brief explanations (e.g., 'ID of note to update', 'New title (optional)'), adding meaningful context beyond the bare schema. However, it doesn't explain parameter interactions or constraints (e.g., what happens if parent_id is invalid).

  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.' This specifies the verb ('update') and resource ('note'), and it's distinct from siblings like create_note, delete_note, and get_note. However, it doesn't explicitly differentiate from import_markdown or search_notes, which might also modify notes indirectly.

  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 the note_id), compare to create_note for new notes, or specify scenarios where update is appropriate over other operations. 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.

• create_noteA
  3.5/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 doesn't mention authentication requirements, rate limits, error conditions, or what happens if parent_id is invalid. 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.

  Conciseness4/5

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

  The description is well-structured with clear sections (Args, Returns) and uses bullet points for parameters. It's appropriately sized, though the 'Args: args:' phrasing is slightly redundant. Every sentence adds value, with no wasted words.

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

  Completeness3/5

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

  For a creation tool with no annotations and no output schema, the description adequately covers the basic purpose and parameters. However, it lacks details about return values (only mentions 'dictionary containing the created note data' without specifics), error handling, or behavioral constraints, leaving room for improvement given the mutation nature of the tool.

  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?

  The description provides comprehensive parameter details beyond the schema, which has 0% description coverage. It explains each parameter's purpose (title, body, parent_id, is_todo), marks optionality, and clarifies that body is in Markdown format, fully compensating for the schema's lack of descriptions.

  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. The verb 'create' is precise and unambiguous.

  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 update_note or import_markdown. The description lacks context about prerequisites (e.g., needing a valid parent_id) or scenarios where this tool is appropriate, offering only basic functional information.

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