Server Quality Checklist

Tool Scores

• update_todoC
  2.7/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 'update' implies mutation but doesn't cover permissions, side effects, error handling, or response format. This leaves significant gaps 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. It's appropriately sized and front-loaded, making it easy to parse quickly without unnecessary elaboration.

  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 explain what happens on success or failure, how partial updates work, or any constraints beyond the basic purpose, leaving the agent with insufficient 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 100%, so the schema already documents all three parameters (id, text, completed) with clear descriptions. The description adds no additional meaning beyond what the schema provides, resulting in a baseline score of 3.

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

  Purpose3/5

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

  The description 'Update an existing todo item' clearly states the verb ('update') and resource ('todo item'), but it's vague about what specifically gets updated and doesn't differentiate from sibling tools like 'add_todo' or 'delete_todo'. It meets the basic requirement but lacks specificity.

  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 'add_todo' for creation or 'delete_todo' for removal. There's no mention of prerequisites, such as needing an existing todo ID, or context for when updates are appropriate.

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

• add_todoC
  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. 'Add a new todo item' implies a write operation, but it doesn't specify whether this requires authentication, what happens on success (e.g., returns an ID), error conditions, or side effects like notifications. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior and safety profile.

  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 without any unnecessary words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place, and there's no redundancy or fluff, which is ideal for conciseness in a tool definition.

  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 (adding data) with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what the tool returns upon success, error handling, or how it integrates with sibling tools like 'list_todos'. For a tool that likely modifies state, more context on behavior and outcomes is needed to be fully actionable 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?

  The input schema has 100% description coverage, with the 'text' parameter clearly documented as 'The todo item text'. The description doesn't add any additional meaning beyond what the schema provides, such as examples or constraints on text length. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description neither compensates for gaps nor enhances the existing 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 action ('Add') and resource ('a new todo item'), making the purpose immediately understandable. It distinguishes this from sibling tools like 'delete_todo' or 'update_todo' by focusing on creation rather than modification or deletion. However, it doesn't specify what system or context the todo is being added to, 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 like 'update_todo' for modifying existing todos. It doesn't mention prerequisites, such as whether a user must be authenticated or if there are limits on how many todos can be added. The presence of sibling tools like 'clear_completed' suggests a broader todo management context, but the description fails to clarify relationships or usage scenarios.

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

• delete_todoC
  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 for behavioral disclosure. While 'Delete' implies a destructive operation, it doesn't specify whether deletion is permanent, reversible, requires specific permissions, or what happens on success/failure. 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 wasted words. It's appropriately sized for a simple tool and front-loads the essential information immediately.

  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 operation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after deletion, whether there's confirmation, what the return value might be, or how this differs from similar sibling tools. The context demands more completeness.

  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 100%, with the single parameter 'id' clearly documented in the schema. The description adds no additional parameter information beyond what the schema already provides, which meets the baseline expectation when schema coverage is complete.

  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 ('Delete') and resource ('a todo item'), making the purpose immediately understandable. However, it doesn't distinguish this tool from sibling tools like 'clear_completed' which also removes todo items, missing an opportunity for differentiation.

  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 'clear_completed' (which removes multiple items) or 'update_todo' (which might mark as deleted). There's no mention of prerequisites, error conditions, or appropriate contexts for deletion.

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

• clear_completedB
  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 full burden for behavioral disclosure. It states the tool removes items, implying a destructive mutation, but lacks critical details: whether the removal is permanent or reversible, if it requires confirmation, what happens on success/failure, or if there are rate limits. The description adds minimal value beyond the basic action.

  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's front-loaded with the core action ('Remove all completed todo items'), making it immediately scannable. Every word earns its place by specifying the scope ('all completed') and target ('todo items').

  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 destructive nature (removing items) and lack of annotations or output schema, the description is incomplete. It doesn't address behavioral risks (e.g., irreversibility), success indicators, or error conditions. For a mutation tool with zero structured metadata, 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.

  Parameters4/5

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

  The tool has zero parameters, and schema description coverage is 100% (since there are no parameters to describe). The description doesn't need to compensate for any parameter gaps, and it correctly implies no inputs are required. This meets the baseline for a parameterless tool, though it doesn't add extra semantic context (e.g., explaining why no parameters are needed).

  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 ('Remove') and target resource ('all completed todo items'), making the purpose immediately understandable. It doesn't explicitly distinguish from sibling tools like 'delete_todo' (which likely deletes specific items), but the scope 'all completed' provides some differentiation. The description avoids tautology by specifying what gets removed rather than just restating the name.

  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 'delete_todo' or 'update_todo' (which might mark items as completed). There's no mention of prerequisites (e.g., whether items must be marked as completed first) or exclusions (e.g., if it affects only certain types of todos). The agent must 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.

• list_todosB
  3.2/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 it 'List all todos' but doesn't specify if this is a safe read operation, how it handles errors (e.g., if the file is missing), or what the output format might be (e.g., structured list vs. raw text). This leaves significant gaps for an agent to understand 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.

  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 function with zero waste. It's front-loaded and appropriately sized for a simple tool, earning full marks for conciseness and structure.

  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 simplicity (0 parameters, no output schema, no annotations), the description is adequate but has clear gaps. It covers the basic purpose but lacks behavioral details (e.g., error handling, output format) and usage context, which are important for completeness even in simple cases.

  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 tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, making it efficient and focused on the tool's purpose without unnecessary details.

  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 ('List') and resource ('all todos from the markdown file'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'clear_completed' or 'update_todo', which would require mentioning it's a read-only operation versus those mutation tools.

  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., if a markdown file must exist), exclusions, or comparisons to siblings like 'add_todo' for creating todos or 'delete_todo' for removal, leaving usage context implied at best.

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