Server Quality Checklist

Tool Scores

• claim_sponsor_cardA
  3.7/5.0
  Behavior3/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. It discloses the mutation ('credit...balance') and validation constraint ('ISSUED' status), but omits idempotency guarantees, error scenarios, and whether claiming changes the card's state (e.g., consumes it).

  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 with zero waste: the first states purpose and effect, the second states the validation constraint. Information is front-loaded and 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 this is a financial mutation tool with no annotations or output schema, the description adequately covers the core operation and validation rule. However, gaps remain regarding error handling, return values, and post-claim card state.

  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%, establishing a baseline of 3. The description adds value by linking 'claimer' to 'player_publickey' and specifying the 'ISSUED' status constraint for 'cardInfo', though the schema already adequately documents both parameters.

  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 specific verbs ('Claim', 'credit') and identifies the exact resource ('sponsor card') and effect ('credit the claimer's DAH balance'). It clearly distinguishes from sibling tool 'claim_gift_card' by specifying 'sponsor card'.

  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?

  It provides a clear precondition constraint ('Only cards with status ISSUED can be claimed'), which implies when the tool will fail. However, it lacks explicit guidance on when to use this tool versus 'claim_gift_card' or other alternatives.

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

• claim_gift_cardA
  3.9/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses the mutation effect (crediting DAH) and the state precondition (ISSUED status). However, it omits critical behavioral details: whether the operation is idempotent, what error occurs if already claimed, and what final state the card transitions to.

  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 consists of two efficient sentences with zero redundancy. It front-loads the primary action and effect, followed by the constraint, making optimal use of limited space.

  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 2-parameter mutation tool with no output schema, the description covers the core action, side effects, and primary constraint. However, it lacks completeness regarding error scenarios, authorization requirements, and the post-claim card state transition, which are important for a destructive/claim-type operation.

  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?

  With 100% schema coverage, the baseline is 3. The description adds semantic value by explicitly linking 'player_publickey' to the 'claimer' role ('credit the claimer's DAH balance'), clarifying the relationship between the parameter and the action beyond the schema's mechanical description.

  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 ('Claim a gift card'), the resource type, and the side effect ('credit the claimer's DAH balance'). It distinguishes from siblings like claim_sponsor_card by explicitly referencing 'gift card' vs the sibling's 'sponsor card' naming.

  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 provides a prerequisite constraint ('Only cards with status ISSUED can be claimed'), which helps determine when the tool is applicable. However, it lacks explicit guidance on when to use this versus claim_sponsor_card, or what to do if the card status is not ISSUED.

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

• create_gift_cardA
  3.9/5.0
  Behavior4/5

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

  With no annotations provided, description carries full burden and successfully discloses financial impact (DAH debit), authorization requirements (dual signatures), and state management (escrow until claimed). Minor gap on error conditions or reversibility.

  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?

  Three well-structured sentences: action (debit), authorization (dual-sig), and lifecycle (escrow). Every sentence conveys critical behavioral information with zero 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?

  Adequate for the core transaction flow but missing output description (no output schema exists) and lacks guidance on cardInfo content (schema shows additionalProperties: {} with no constraints).

  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 has 100% description coverage, establishing baseline 3. Description adds value by linking 'dual signatures' to the signature/distributionSignature parameters and explaining the customer funding context, but does not elaborate on the nested cardInfo structure.

  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?

  Description provides specific verb ('Create') + resource ('gift card') and distinguishes from siblings by specifying 'debiting the customer's DAH balance' (contrasting with create_sponsor_card) and 'escrowed until recipient claims' (contrasting with immediate transfers like purchase_product).

  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?

  Provides implied usage context through 'Requires dual signatures' and escrow mechanism, but lacks explicit when-to-use guidance or direct comparison to alternatives like create_sponsor_card or purchase_product.

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

• purchase_productA
  3.9/5.0
  Behavior3/5

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

  No annotations provided, so description carries full burden. Discloses critical auth requirement (dual signatures) and economic mechanism (balance transfer), but omits reversibility, error conditions (insufficient funds), return value structure, and idempotency expectations for this financial mutation.

  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 efficient sentences with zero waste. Front-loaded with action verb, mechanism explanation follows immediately. No redundant filler despite covering complex financial operation.

  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?

  Minimum viable for a 6-parameter financial transaction tool. With no output schema and no annotations, the description covers core functionality but should ideally address success indicators, failure modes (insufficient balance), or transaction finality given the monetary stakes.

  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%, establishing baseline 3. Description adds semantic value by mapping sender→buyer and receiver→merchant, and explicitly connecting the 'dual signatures' requirement to the sender_signature and receiver_signature parameters, clarifying their relational purpose.

  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?

  Specific verb ('Purchase') + resource ('product') + mechanism ('debiting sender's DAH balance and crediting receiver'). Clearly distinguishes from siblings like check_balance (read-only lookup) and create/claim_gift_card (card management vs direct purchase).

  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?

  Implies usage through mechanism description (debit/credit flow) and prerequisite ('Requires dual signatures'), but lacks explicit when-to-use guidance versus alternatives like claim_gift_card or when purchasing is preferable to other payment methods in the sibling set.

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

• check_balanceA
  4.1/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. It extensively discloses return structure including total balance, per-token breakdown, maturity info, merchant breakdown, and specific W3SH loyalty tiers (Seed/Twig/Kindling/Log/Joist) with cashback details. However, it omits operational aspects like rate limits, caching, or authentication requirements.

  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 with zero waste: first establishes the action and scope, second details return values. Information is front-loaded with the primary action ('Check') first, and every clause earns its place—particularly the return value details which compensate for the missing output schema.

  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 single-parameter query tool, the description is complete. It explains the input (public key), the action (check balances), and comprehensively describes the return structure (total, breakdowns, maturity, loyalty tiers) despite the absence of an output schema or annotations.

  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 the parameter 'player_publickey' fully documented as 'The public key (hex) to check balances for.' The description mentions 'for a public key' but adds no additional semantic context, examples, or format details beyond what the schema already provides.

  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 specific verb 'Check' with explicit resource 'token balances' and lists specific tokens (DAH, DAHYM, DAHLOR, W3SH). It clearly distinguishes from transactional siblings (claim_gift_card, purchase_product, etc.) by being a query operation focused on 'public key' lookup.

  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?

  While the 'Check' verb implies read-only usage versus the transactional siblings (claim/create/purchase), there is no explicit guidance on when to use this tool versus alternatives, prerequisites, or exclusion criteria.

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

• create_sponsor_cardA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden and effectively discloses critical behavioral traits: dual signature requirement (security), DAH balance debit (financial impact), and location-proximity claiming mechanism. Minor gap in not describing failure modes or validation errors.

  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?

  Three tightly constructed sentences with zero waste. Front-loaded with action and cost (DAH debit), followed by critical requirement (dual signatures), then outcome (claiming mechanics). Every sentence earns its place.

  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 6-parameter financial/crypto tool with nested objects and no output schema, the description adequately covers the core transaction model, security requirements, and claiming behavior. Could be improved by noting validation requirements or error conditions, but the essential complexity is addressed.

  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 schema has 100% coverage, the description adds valuable semantic context not present in structured data: explicitly linking 'signature' and 'distributionSignature' as 'dual signatures' (workflow context), and explaining the DAH economic model that justifies the 'sponsor_public_key' parameter.

  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?

  Description uses specific verb 'Create' with clear resource 'location-based sponsor card'. It distinguishes from sibling 'create_gift_card' by specifying sponsor-specific mechanics: DAH balance debit, dual signatures, and location-based claiming.

  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?

  Provides clear context for when to use (sponsor funding location-based cards requiring dual signatures and DAH debit). While it doesn't explicitly name 'create_gift_card' as an alternative, the sponsor/DAH/location specificity makes the appropriate use case distinct.

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