Server Quality Checklist

Tool Scores

• create_clientB
  3.1/5.0
  Behavior2/5

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

  The description adds no behavioral context beyond the annotations (readOnlyHint=false, destructiveHint=false). It does not disclose potential side effects, validation, uniqueness constraints, or permission requirements, so transparency is limited.

  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, 'Create a new client/customer,' which is extremely concise and front-loaded. It contains no filler and every word contributes to the purpose.

  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?

  The description, combined with the comprehensive input schema and output schema, is adequate for a basic create operation. However, it lacks usage timing and behavioral caveats, which are not covered elsewhere, leaving some gaps in the complete picture.

  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 already describes all 10 parameters with full coverage, so the description's lack of parameter details is acceptable. The baseline of 3 applies because the schema carries the semantic load.

  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 identifies the action (create) and the resource (client/customer), which distinguishes it from sibling tools like list_clients and create_invoice. However, it does not explicitly contrast with alternatives, so it misses the highest rating.

  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 offers no guidance on when to use this tool versus alternatives, nor does it state any prerequisites or exclusions. It simply states the action, leaving usage decisions entirely to the agent.

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

• log_time_entryA
  3.6/5.0
  Behavior2/5

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

  Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a write operation. The description adds no further behavioral context: no permissions, side effects, or reversibility, and it doesn't explain what happens after logging. It merely restates the action, adding nothing beyond the annotations.

  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 with no wasted words, directly stating the action and target. It is appropriately concise and front-loaded.

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

  Completeness4/5

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

  For a simple tool with fully described schema parameters, safety annotations, and an output schema, the description is adequate. It captures the core purpose, though it omits any mention of prerequisites (e.g., project must exist) or when to choose this over alternatives. These gaps are minor given the tool's simplicity.

  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?

  All four parameters have full descriptions in the schema (100% coverage). The description text provides no additional parameter meaning beyond what the schema already documents, so the baseline of 3 applies.

  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 uses the specific verb 'log' with the resource 'time entry' and target 'project/case', clearly differentiating it from sibling tools like create_client or create_invoice. It is immediately obvious what this tool does.

  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 (log hours to a project/case) but provides no explicit when-to-use instructions, prerequisites, or exclusions. There are no alternative tools mentioned, though the sibling list makes it unlikely to be confused. Guidance is minimal.

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

• list_clientsA
  3.8/5.0
  Behavior3/5

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

  The description adds user-scoping beyond the readOnlyHint annotation, indicating results are limited to the current user. It does not describe pagination or return format, but output schema covers these. Annotations already provide safety, and the added context is minimal.

  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 short sentence with a clear verb and resource, front-loaded and without any unnecessary words. It earns every character.

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

  Completeness4/5

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

  For a simple read-only list tool with one optional parameter and an output schema, the description provides essential scope. It doesn't mention status filtering, but the schema compensates. The combination of description, annotations, and schema is sufficient.

  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 fully describes the 'status' parameter with 100% coverage. The description adds no additional parameter semantics, leaving the schema to carry this dimension. Baseline of 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 uses the specific verb 'List' and identifies the resource 'clients/customers', clearly distinguishing it from sibling tools like create_client. It also adds the scope 'user's' to clarify ownership, making the purpose unambiguous.

  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?

  No explicit guidance on when to use vs alternatives. The read-only list nature is evident from the description and sibling context, so usage is implied rather than stated. It lacks direct 'when not to use' or alternative recommendations.

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

• list_projectsA
  4.1/5.0
  Behavior4/5

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

  The readOnlyHint annotation already indicates a safe read operation. The description adds useful behavioral context by disclosing that the label adapts to businessMode (e.g., cases or work orders), which is not inferable from annotations alone.

  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 concise sentence that immediately states the tool's purpose and adds a relevant caveat. There is no wasted content, and the key information is front-loaded.

  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?

  For a simple read-only list operation, the description fully covers the tool's behavior, especially with an output schema present and the businessMode adaptation noted. No significant missing context remains.

  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 already fully describes the single 'status' parameter with 100% coverage, so the description does not need to repeat it. It adds no additional parameter semantics, hence a baseline score of 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 starts with the verb 'List' and clearly identifies the resource as 'the user's projects', with a helpful note that labels adapt to businessMode (cases/work orders). This effectively distinguishes it from sibling tools like list_clients.

  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 states that it lists projects, which implies usage for project-related queries, but it does not explicitly provide when-to-use guidance, mention alternatives, or state when not to use it. The sibling tool list_clients exists, but the description itself does not differentiate.

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

• create_invoiceA
  4.4/5.0
  Behavior4/5

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

  Annotations indicate a non-read-only, non-destructive operation, which aligns with creating a draft. The description adds specific behavioral context: the invoice is created as a draft, and currency/language/VAT are auto-filled from the EZ@Work profile. This goes beyond the annotations.

  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 two sentences long, with the primary action in the first sentence and supplementary detail in the second. No wasted words.

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

  Completeness4/5

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

  Given the output schema exists and annotations cover safety, the description adequately covers the tool's core behavior. It doesn't repeat schema details, but it adds the essential auto-detection information. Minor gaps like payment terms are already in schema, so no further description needed.

  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?

  While the schema fully describes the three parameters, the description adds crucial context by explaining that currency, language, and VAT/tax rate are auto-detected and should not be specified. This prevents the agent from attempting to pass these as parameters and clarifies why they are absent from the schema.

  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 opens with 'Create a draft invoice,' which clearly states the action and resource. It also distinguishes from sibling tools by focusing on invoice creation, while siblings handle clients, projects, and time entries. The auto-detection note further clarifies scope.

  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 implicitly signals when to use the tool (when creating a draft invoice) and clarifies that no currency/language/VAT specification is needed. However, it doesn't explicitly mention alternative tools or when not to use it, so it falls just short of a 5.

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