Server Quality Checklist

Tool Scores

• verify_phoneA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries full responsibility and does well: it discloses that line type is not reported (a common expectation), that Premium mode is not assumed, and warns against using output for SMS deliverability. This goes beyond the basic 'validates' claim and informs the agent of significant behavioral limitations.

  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, front-loaded with the primary purpose, followed by critical limitations. Every sentence adds value, and it is compact without any filler.

  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 one-parameter verification tool with no output schema or annotations, the description covers validity checks, standardization, and critical exclusions. It stops short of specifying the exact return structure or error behavior, but given the simplicity, it is adequately complete for an agent to call it correctly.

  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 single parameter phoneNumber is fully covered by the schema description ('any common format'). The tool description adds no additional parameter constraints or format details beyond the schema, 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 clearly states the tool verifies phone number validity and returns a standardized version, with a specific verb and resource. It also distinguishes itself from siblings (verify_email, verify_postal_address) by focusing on phone, and explicitly notes a limitation (no line type detection). This allows an agent to select it correctly among siblings.

  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 gives a clear context of use: validating and standardizing phone numbers. It includes an explicit exclusion: 'Do not use this tool's output to infer SMS deliverability,' which prevents misuse. However, it does not directly reference alternative tools for other data types, so it leaves a small gap in routing to siblings.

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

• verify_batchA
  4.3/5.0
  Behavior4/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 reveals that the tool checks a local cache before calling Melissa and is subject to the same per-session call budget as the single-record tools. This adds meaningful context beyond a simple 'verify' action, though it does not mention return format or error 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 two sentences, tightly packed with actionable guidance. The primary usage directive is front-loaded, and the constraints (cache, budget, mutual exclusivity) follow logically. No filler or redundancy; every sentence earns its place.

  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 (batch verification, three mutually exclusive parameters, no annotations, no output schema), the description covers the essential context: when to use it, the mutual exclusivity rule, and key behavioral constraints. However, it omits the return structure, any batch size limits beyond the budget, and error semantics, so it is not fully complete.

  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 for parameter documentation. It clarifies that exactly one of the three arrays must be provided, which is a crucial semantic not encoded in the schema. However, it does not describe the structure of address objects or the format of email/phone strings, leaving much to the schema. This partially compensates for the coverage gap.

  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 verifies addresses, emails, or phone numbers in batch, and explicitly contrasts it with the single-record siblings by saying 'Use this instead of calling verify_postal_address, verify_email, or verify_phone in a loop.' This distinguishes it from related tools and conveys a specific verb-resource pair.

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

  Usage Guidelines5/5

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

  It gives an explicit directive: 'Use this instead of calling ... in a loop,' which tells the agent exactly when to choose this tool over the single-record ones. It also states the cardinality constraint, 'Provide exactly one of addresses, emails, or phoneNumbers,' covering a key usage rule that the schema does not enforce.

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

• verify_postal_addressA
  4.4/5.0
  Behavior5/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 return values (verification level, corrected address, persistent identifier), discloses a limitation (cannot confirm newly built addresses), and interprets results ('not confirmed' means unknown, not fabricated). It also warns against misinterpreting verification as evidence of person association. This is thorough transparency.

  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 comprehensive yet efficient. It opens with the core function, then covers return values, usage guidance, and important limitations without redundancy. Every sentence contributes to the agent's understanding, making it well-structured and 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.

  Completeness4/5

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

  The tool has no output schema, and the description compensates by naming the three return components (verification level, corrected address, persistent identifier). It also covers usage, limitations, and interpretation. However, it doesn't describe the specific response structure or possible verification levels, which would be useful for full completeness. Overall, it provides sufficient context for correct invocation.

  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 80%, so the schema already documents most parameters. The description does not add parameter-specific semantics beyond the schema's descriptions; it only mentions 'using maintained postal reference data,' which pertains to data source rather than parameter meaning. This aligns with the baseline of 3 for high schema coverage.

  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 tool's function with a specific verb and resource: 'Checks whether a postal address exists and is deliverable.' It is unambiguous about the resource type, which inherently differentiates it from siblings like verify_email and verify_phone. However, it does not explicitly name or contrast itself against sibling tools, so it falls short of full explicit differentiation.

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

  Usage Guidelines5/5

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

  The description provides explicit when-to-use guidance ('Call this before any action that depends on an address being real: shipping, billing, account creation, or writing an address to a system of record') and explicit when-not-to-use guidance ('Do NOT use this to look up who lives at an address, and do not treat a verified address as evidence that a particular person is associated with it'). It covers both positive and negative use cases clearly, even though it doesn't name alternative tools.

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

• verify_emailA
  4.6/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the return values (confidence score 0-100 and result codes) and clarifies a key limitation (deliverable does not confirm control). It does not mention error handling, rate limits, or side effects, but for a read-only verification tool, these are minor. This is solid transparency for the core 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 three sentences, front-loading the core purpose, then covering return values, recommended usage, and a critical caveat. There is no fluff or repetition; each sentence earns its place. The structure is well organized and easy to scan.

  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 single-parameter tool with no output schema, the description covers the what, the return type, when to use, and a limitation. The only gap is not detailing the specific result codes or their meanings, but this may be acceptable given the lack of an output schema and the tool's simplicity. It is largely complete for an agent to call correctly.

  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 coverage is 100% and the parameter is well-described ('Email address to verify'). The description adds semantic nuance by clarifying that the email is checked for deliverability, not just format, which goes beyond the schema's literal definition. This adds value without redundancy.

  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 states a specific action ('Checks whether an email address is deliverable, not merely well-formed') with a clear resource (email). It distinguishes from siblings by focusing on deliverability, not format validation, and the sibling names (verify_phone, verify_postal_address) clearly differ. It is unambiguous and specific.

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

  Usage Guidelines5/5

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

  The description provides explicit when-to-use guidance ('Call this before sending anything time-sensitive or before treating an email address as a verified contact channel') and an explicit exclusion ('Do NOT use this as an identity check'). It also explains why the exclusion matters, which helps an agent choose correctly among alternatives.

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