Server Quality Checklist

Tool Scores

• list_projectsB
  3.4/5.0
  Behavior2/5

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

  No annotations are provided, so the description must carry the full burden. It only mentions the HTTP method (GET) and access scope. It does not disclose pagination, rate limits, error handling, or output format, which are important for a list 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 a single sentence that efficiently conveys the core action. It is not verbose, though could include more context without significant bloat.

  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 simple list tool with no output schema, the description provides the essential purpose but omits details about the response structure, ordering, or any limitations. It is minimally adequate.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

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

  Schema coverage is 100% with a single parameter 'token' already described in the schema. The description adds no further semantics, but the baseline of 3 is appropriate since the schema does the work.

  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 identifies the verb 'list', resource 'Worksnaps projects', and scope 'the current user can access'. It also provides the underlying API endpoint. This distinguishes it from sibling tools like list_tasks and log_time.

  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 usage is implied by the description but no explicit guidance is given on when to use this tool over alternatives, nor any prerequisites or exclusions. The agent must infer context 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.

• list_tasksB
  3.4/5.0
  Behavior2/5

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

  No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the basic operation (listing tasks) without mentioning side effects, permissions, rate limits, or error states. This is insufficient for a tool with no annotation support.

  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 a single concise sentence with no wasted words. It includes the API endpoint for clarity, though it could be slightly more front-loaded. Overall efficient.

  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 (2 params, no output schema, no annotations), the description provides the basic purpose but lacks details on usage context, error handling, or return format. It is adequate but leaves gaps.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

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

  Schema coverage is 100%, so both parameters are documented in the schema. The description adds no extra meaning beyond referencing the projectId in the endpoint. Baseline 3 is appropriate as the description does not enhance parameter understanding.

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

  Purpose5/5

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

  The description clearly states the action ('List tasks'), the resource ('in a Worksnaps project'), and provides the API endpoint. It distinguishes itself from sibling tools like 'list_projects' (lists projects) and 'log_time' (logs time).

  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 does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. Usage is implied by the action, but no direct comparison with siblings is given.

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

• log_timeA
  3.9/5.0
  Behavior3/5

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

  No annotations are provided, so the description bears full responsibility for behavioral disclosure. It indicates the tool creates a time entry (POST), which implies mutation. It mentions that date defaults to today and startHour defaults to 9, but does not disclose side effects, error handling, rate limits, or what happens on duplicate entries. This is minimal but acceptable for a simple logging 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 sentence of 20 words, front-loading the purpose and then specifying requirements. Every word is meaningful, with no redundancy.

  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 tool with 7 parameters, 1 required, and no output schema, the description provides the core purpose and required fields. However, it does not explain the return value (e.g., success status or entry ID), error cases, or constraints like maximum minutes. The context is somewhat complete but lacks details that would help the agent handle edge cases.

  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 baseline is 3. The description adds the context of 'offline time' and the HTTP method, but restates that projectId, taskId, and minutes are required, while the schema shows projectId and taskId as optional (with defaults). This slight inconsistency reduces clarity. The added value is marginal, so a 3 is appropriate.

  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 tool's purpose: logging offline time to Worksnaps. It specifies the HTTP method and resource (POST /projects/{projectId}/time_entries.xml) and lists required parameters. It is distinct from the sibling tools, which are all read/list operations.

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

  Usage Guidelines4/5

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

  The description provides explicit prerequisites (requires projectId, taskId, and minutes), which guides the agent on what must be supplied. However, it does not discuss when to use this tool versus alternatives, nor does it mention conditions where it should not be used. It is adequate but could be more comprehensive.

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

• whoamiA
  4.1/5.0
  Behavior4/5

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

  Without annotations, the description discloses the GET method, endpoint, and return values (user id, login, name, email). It does not mention potential errors or side effects, but the behavior is largely clear.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

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

  Two sentences efficiently convey purpose, method, and return fields with no wasted words.

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

  Completeness5/5

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

  The tool is simple with one optional parameter and no output schema; the description adequately covers the return fields and operation.

  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 parameter token is fully documented. The description adds no extra semantics beyond confirming the token is used for authentication.

  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 tool resolves the current user from the API token, specifies the HTTP method and endpoint, and lists the return fields. This distinguishes it from sibling tools like list_projects, which focus on different resources.

  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 when the user identity is needed, but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites.

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