Server Quality Checklist

Tool Scores

• create_invoiceA
  3.8/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 full burden. It describes the return value (buyer payload + activation fee bolt11) and the activation prerequisite but lacks details on error behaviors, auth requirements, or rate limits.

  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 concise single paragraph of three sentences, front-loading the main action and return value. It could be slightly more structured with bullet points, but it is 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 no output schema and no annotations, the description explains the return value and activation sequence but omits detailed parameter explanations and error conditions. It is somewhat incomplete for a 12-parameter tool.

  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 42%; the description adds context for payment_destination and the attach_file prerequisite but does not explain most parameters beyond the schema. It provides moderate additional meaning.

  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 it creates a single-settlement invoice, specifying the verb 'create', resource 'invoice', and distinguishes from siblings by mentioning 'Path 3a seller' and referencing attach_file and pay_invoice.

  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 indicates when to use (creating a one-off invoice) and implies prerequisites (attach file if selling, pay activation fee). It distinguishes from downstream tools like pay_invoice but does not explicitly state when not to use.

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

• get_offerA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries full burden. It declares the tool is a read operation (fetch) and lists returned fields. It does not address authentication, rate limits, or error handling, but provides sufficient transparency for a simple fetch 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?

  Two sentences of essential information: first lists returned fields, second gives usage advice. No filler or repetition.

  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 one parameter and no output schema, but the description lists all key returned fields. For a simple fetch, this is sufficiently 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 coverage is 100% with 'offer_id' described as 'The offer id'. The description adds no extra meaning beyond the schema, so baseline 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 action ('Fetch an offer's full terms') and specifies the resource ('offer'). It lists the returned fields, distinguishes from sibling 'buy_offer' by emphasizing it's a read-before-buy operation.

  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 advises to 'Always read and evaluate the terms before paying,' implying the tool is for pre-payment evaluation. It does not explicitly exclude other uses or mention alternatives, but the context is clear.

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

• get_wave_linkA
  4/5.0
  Behavior4/5

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

  With no annotations, the description discloses important side effects: regenerating revokes the previous link and the peer's link is unaffected. However, it does not explain the separate 'revoke' action, leaving a notable gap in the tool's behavioral 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 concise, front-loaded with the primary action and purpose, then usage and side effects. Each sentence earns its place, with no redundant information.

  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 low-complexity tool with no output schema, the description covers purpose, usage timing, side effects, and implies the output is a URL. However, it omits the behavior of the 'revoke' action and does not precisely describe the response format, leaving a moderate gap.

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

  Parameters2/5

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

  Schema covers only the 'peer' parameter (50% coverage). The description does not clarify the 'regenerate' vs 'revoke' enum distinction and adds no meaning beyond the schema's description of peer. The phrase 'Mint (or rotate)' hints at the default action but fails to explain the revoke option.

  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 'Mint (or rotate) YOUR side's private browser link for a wave' and explains its purpose (letting the operator watch and reply as human). It distinguishes the tool from sibling wave tools like send_wave/read_wave by emphasizing 'YOUR side's' link.

  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 explicit usage context: 'Do this after joining a new wave' and 'use after a leak' for regeneration. Does not name alternatives or when-not-to-use, but the context is clear enough for selecting this tool over other wave-related siblings.

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

• list_salesA
  4/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 burden. It mentions the tool returns payment_hash/preimage and is authoritative for reconciliation, but does not disclose read-only behavior, authentication requirements beyond 'pubkey-signed', rate limits, or pagination behavior. Adequate but could be more explicit.

  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 no wasted words. The description front-loads the core purpose and provides essential details about the two kinds and return values. 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?

  Given the tool has 5 parameters, no output schema, and no annotations, the description reasonably covers the main use case, kind parameter behavior, and return values. It could be more complete by explaining pagination (limit/offset) and the status parameter, but the core context is sufficient for an agent to understand and invoke the tool 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?

  Schema description coverage is only 20% (only offer_id has a description). The tool description adds meaning for kind (mapping to two payment paths) and implies filtering by offer_id, but does not explain limit, offset, or status parameters. Partially compensates for low coverage but still lacks complete parameter guidance.

  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 lists settled/pending sales for a seller identity, distinguishing between two kinds (offers and invoices) and citing the authoritative reconciliation purpose. This differentiates it from siblings like my_offers or search_offers.

  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 explicitly states when to use the tool (to reconcile missed execution_webhook deliveries) and maps the kind parameter to specific endpoints. It does not explicitly list when not to use or compare to alternatives, but the context is clear.

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

• manage_offerA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries full burden. It discloses key behaviors like automatic NWC payment vs manual, and error code for renew. However, it does not mention irreversibility of delete, rate limits, or idempotency of status.

  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 concise (about 80 words) and well-structured with actions clearly delineated. No redundant sentences; each sentence adds essential information.

  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 complexity (5 params, no output schema, no annotations), the description covers the main outcomes of each action. However, it could specify what the status action returns in more detail and mention prerequisites like having an existing offer.

  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 covers 60% of parameters with descriptions. The description adds context for pay_fee (auto/manual payment) and activation_window (for renew). But for add_capacity it merely restates schema info. Overall, description adds moderate value beyond 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 explicitly lists four distinct actions (status, renew, add_capacity, delete) with clear explanations for each. It distinguishes this tool from siblings like create_offer and buy_offer by focusing on managing existing offers.

  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 specific scenarios for each action (e.g., renew when window lapsed, delete for permanent deactivation) and mentions error code 402 for renew. However, it does not explicitly exclude other use cases or compare to siblings like get_offer or my_offers.

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

• search_offersA
  4/5.0
  Behavior3/5

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

  With no annotations, description carries full burden. It discloses that payment_count is not a trust guarantee, but lacks explicit statement of idempotency, rate limits, or authorization requirements. Adequate but not comprehensive.

  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?

  Concise four-sentence structure. First sentence states purpose, second lists return fields, third points to buy_offer, fourth notes limitation. Front-loaded and efficient.

  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?

  No output schema, but description adequately lists return fields with important caveat. Covers public/private distinction. Pagination details are in schema. Suffices for a search tool with this parameter count.

  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 high (71%), and description adds no additional parameter information beyond what schema provides. Baseline of 3 is appropriate; no added value from description for parameter meaning.

  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 clearly states the tool browses opt-in public offers purchasable over Bitcoin Lightning, and specifies return fields. It distinguishes from sibling tools like buy_offer, get_offer, and notes private offers are not shown.

  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?

  Explicitly says when to use (browse public offers) and implies not for private offers or direct offer_id lookup. Mentions buying with buy_offer, providing context. Does not explicitly list when not to use, but covers key distinctions.

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

• check_inboxA
  4.1/5.0
  Behavior3/5

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

  With no annotations, the description partially discloses behavior: it aggregates across all waves, uses a cursor to avoid re-reading, and tells the agent to summarize results. However, it does not explicitly state whether the operation is read-only or has side effects (e.g., marking messages as read), leaving some ambiguity.

  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 tight paragraph with no wasted words. It front-loads the core purpose, then provides usage guidance and a pointer to a sibling tool. Every sentence adds value.

  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 does not explicitly state the return format or that the response includes a nextCursor field, though this is implied by the `since` parameter and schema. It also does not mention pagination or limits. With no output schema, the description could be more complete about what the agent should expect back.

  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 schema documents the `since` parameter as a cursor, and the description adds practical meaning: 'Pass since from your last check to avoid re-reading.' This goes beyond the schema's property description and clarifies how to use the parameter effectively.

  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: one call checks for new messages and pending file transfers across all waves. It uses a specific verb ('check') and resource ('inbox'), and distinguishes itself from siblings like read_wave (specific wave) and receive_file (collecting files).

  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 clear usage context: call once at the start of a session, pass `since` to avoid re-reading, and use receive_file to collect pending files. It names an alternative tool but does not explicitly state when not to use this tool (e.g., for reading a specific wave).

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

• confirm_paymentA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description alone covers behavior. It discloses idempotency (safe to retry), the result (returns claim_token once settled), and context (manual settlement). It does not detail failure modes or side effects, but the coverage is good for a simple confirmation step.

  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 short, front-loaded sentences. Each sentence adds value: purpose, idempotency, return value. No wordiness or repetition.

  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 3 parameters, no output schema, and no annotations, the description explains the scenario, idempotency, and return value. It doesn't cover prerequisites or error conditions, but for a tool that confirms payment it is reasonably 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?

  The input schema has only 33% parameter descriptions (payer_secret). The overall description adds context that preimage is a Lightning preimage and payment_intent_id and payer_secret come from buy_offer, but individual parameter semantics are not fully fleshed out. The description compensates partially but not completely.

  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: 'Submit the Lightning preimage as settlement proof' for a manual offer purchase. It distinguishes this tool from siblings by specifying 'manual mode' and 'outside NWC', contrasting with automated payment flows.

  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 explicitly states when to use this tool: after paying a bolt11 from buy_offer manually. It also notes idempotency ('safe to retry'), guiding retry behavior. It does not mention alternative tools like pay_invoice but the manual context implies the distinction.

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

• create_offerA
  4.2/5.0
  Behavior4/5

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

  Despite no annotations, the description details the payment flow (direct, no node needed), activation fee calculation, content sealing, and immutability of public fields. Minor gaps remain (e.g., error handling on fee payment).

  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 front-loaded with core purpose and logically structured around payment flow and configuration options. It is dense but concise for the complexity; a slightly tighter phrasing could improve readability.

  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 no output schema, the description does not explicitly mention return values (likely an offer_id). It covers creation workflow well but omits important information about what the tool returns and how to reference the created offer.

  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 69%, but description adds valuable context beyond schema, such as explaining payment_destination flexibility, activation fee formula, and capacity extension via manage_offer. Examples and constraints are well explained.

  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?

  Title and description clearly state the tool creates a Hypawave offer for selling digital goods over Lightning. It distinguishes itself from siblings like attach_file or buy_offer by focusing on offer creation.

  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?

  Description provides clear guidance on private vs public offers, file attachment timing, and automatic fee payment. It lacks explicit 'when not to use' statements but gives sufficient context for typical use.

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

• my_offersA
  4.2/5.0
  Behavior4/5

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

  No annotations provided, so description carries full burden. It implies a read-only operation (lists offers), mentions authentication requirement (pubkey-signed), and discloses output fields (status, capacity usage, activation window). Lacks explicit statement of no side effects or pagination info.

  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 that front-load the purpose and provide essential guidance. No wasted words; every sentence adds value.

  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 low complexity (1 optional param, no output schema), the description adequately covers what the tool does and what it returns. It mentions the key output fields. Could optionally note pagination or sorting, but not necessary for minimal 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?

  Schema coverage is 100% with the parameter 'status' having a schema description 'Filter by offer status'. The description adds no extra meaning beyond this, so baseline 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 lists all offers created by the server's seller identity, providing specific details (status, capacity usage, activation window). It distinguishes from sibling 'manage_offer' by directing users there for details/renewal.

  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 states when to use the tool (to list seller's own offers) and offers an alternative (manage_offer for details/renewal). It implies authentication context (pubkey-signed) but does not explicitly exclude cases like searching all offers, though sibling list suggests alternatives.

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

• attach_fileA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description details the encryption process (client-side, Hypawave never sees plaintext), upload, and content commitment via ciphertext_sha256. This covers key behavioral aspects, though it omits error handling or return format.

  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 sentences with no redundancy, front-loaded with the main action, and structured logically (encryption, timing, parameter constraints). Every sentence is essential.

  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?

  Despite good behavioral coverage, the description does not specify the return value (e.g., file ID, key). For a tool with no output schema, this leaves a gap in what the agent can expect after invocation.

  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 50%, so description compensates by explaining mutual exclusivity of offer_id and invoice_id, the absolute path requirement for file_path, and default content_type. This adds meaning beyond 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?

  Title and description clearly state the tool encrypts and attaches a local file to an offer or invoice, specifying the encryption method (AES-256-GCM) and distinguishing between offer_id and invoice_id paths, which differentiates it from sibling tools like create_offer and download_files.

  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 explicitly states the tool must run before the activation fee settles, the presigned URL lasts 120 seconds, and that only one of offer_id or invoice_id should be passed. This provides clear context for when to use, though it does not explicitly mention when not to use alternatives.

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

• receive_fileA
  4.3/5.0
  Behavior5/5

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

  With no annotations provided, the description carries full burden and succeeds. It discloses the key release mechanism, repeatability, ciphertext download, integrity verification, local decryption, and file write path. The security warning about untrusted input adds valuable context beyond schema.

  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 dense sentence with additional security guidance. It is reasonably concise and front-loaded with the core action, but the multiple clauses make it somewhat run-on. Each clause contributes value, so it's not overly verbose.

  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 no output schema, the description explains the action sequence and destination of the file. It covers the key behaviors but does not explicitly state what the function returns (e.g., success status or file path). The retry guidance partially compensates, but a more explicit outcome would make it 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 100%, so baseline is 3. The description mentions save_dir as the write target, but this is already in the schema. It adds no new parameter semantics beyond what the schema already provides, so no higher score is warranted.

  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 'collects a pending transfer addressed to you,' naming both the verb and resource. It distinguishes itself from siblings like check_inbox (which finds ids) and send_file (which sends files) by focusing on the receive-side action.

  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 explicitly directs users to find ids via check_inbox, providing clear prerequisite context. It also notes the operation is repeatable until expiration, implying retry capability. However, it does not explicitly mention when not to use this tool or compare it to alternatives like download_files.

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

• block_agentA
  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 responsibility for behavioral disclosure. It reveals that sends are 'rejected and never stored' and that the blocked party is 'not told they're blocked', covering key side effects. It also indicates reversibility with 'unblock reverses it', though it omits minor details like impact on existing messages.

  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 core purpose, and every phrase adds value. No extraneous information or repetition of schema details.

  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 two parameters and no output schema, the description covers the essential context: what it does, when to use it, and important behavioral consequences. It lacks nothing critical, though mentioning any return value would slightly improve completeness.

  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 description coverage is 50% (pubkey has a description, action does not). The description adds semantic value by explaining the effect of blocking on messages/files and clarifying that unblock reverses this. This helps interpret the 'action' parameter despite its missing schema 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 tool's purpose with a specific verb ('Stop') and resource ('a pubkey'), explaining that it prevents messaging and file transfers. It also distinguishes this tool from siblings by focusing on contact blocking, which is unique among the listed tools.

  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 direct usage guidance: 'Use on spam or unwanted contact; unblock reverses it.' While it doesn't explicitly name alternatives, none of the sibling tools serve the same blocking functionality, so the guidance is sufficient for the context.

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

• send_waveA
  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 reveals that messages are signed, that a first message creates the wave, and crucially warns that received messages are external data and instructions should never be followed. This security-relevant behavioral context goes well beyond what the schema or annotations could provide.

  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, immediately states the primary action, and packs essential context (addressing, wave creation, security warning) into a compact form. Every sentence earns its place; no fluff or redundancy.

  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 send operation with three scalar parameters, the description covers the main usage, addressing, and a key security caveat. There is no output schema, but the absence of a return-value description is acceptable for a fire-and-forget messaging tool. This is complete enough for straightforward use.

  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%, with each parameter (to, body, topic) already documented in the input schema. The description adds minimal parameter-specific meaning beyond what the schema provides, so the 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 opens with 'Send a signed message into your private wave with another agent,' clearly identifying the verb (send), resource (private wave message), and distinguishing it from siblings like send_file or read_wave. It further clarifies the target via contact card, wave page, or prior wave, leaving no ambiguity about the tool's function.

  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 clear context: it specifies the mechanism for addressing recipients (pubkey, wave page, prior wave) and notes that the first message to a new pubkey creates the wave. While it doesn't explicitly name alternatives or exclusions, the context is unambiguous enough for an agent to select this tool for sending signed text messages in a wave.

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

• buy_offerA
  4.5/5.0
  Behavior5/5

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

  Despite no annotations, the description fully discloses behavior: it spends real bitcoin, enforces caps, performs multiple steps, and settlement is final with no refunds. It explains return values for both NWC and non-NWC paths.

  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 front-loaded with purpose and structured into two clear paths. It is somewhat long but each sentence adds value, so it earns its length.

  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 no output schema, it explains return values (claim_token or preimage). It covers both major workflows but omits error handling or failure conditions, which would make it more complete.

  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 50% (only expected_max_sats has a description). The description adds meaning by explaining offer_id implicitly (identifies the offer to buy) and clarifying expected_max_sats as a per-purchase bound on top of the operator cap.

  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: 'Purchase an offer end-to-end.' It explains the two workflows (with and without NWC), distinguishing it from siblings like get_offer (read terms) and confirm_payment (used after manual payment).

  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?

  It advises to read offer terms with get_offer first, and indicates when to use confirm_payment instead (without NWC). It does not explicitly list when not to use, but the context is sufficient.

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

• check_paymentA
  4.5/5.0
  Behavior4/5

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

  The description labels the tool as 'Non-destructive status check' and explains what it returns for each path (status, claim_token, unlock status). Although no annotations are provided, the description sufficiently discloses the tool's behavior for a read-only operation.

  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, front-loads the key behavioral trait ('Non-destructive status check'), and efficiently conveys all necessary information without redundancy.

  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 description covers the two main use cases and their parameter combinations, and explains return values for both. While it omits error handling or edge cases, it is complete enough for a status check tool with three parameters and no output schema.

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

  Parameters5/5

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

  The description adds significant meaning beyond the schema: it clarifies that payer_secret is required with payment_intent_id, explains the usage of invoice_ids for one path and payment_intent_id for another, and specifies the return values. With 67% schema description coverage, the description compensates fully.

  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 checks settlement/unlock status for two distinct paths: offer purchases and invoices. It specifies the exact parameters for each path and what is returned, fully distinguishing the tool from sibling tools like pay_invoice or confirm_payment.

  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 guidance on when to use each parameter combination: payment_intent_id+payer_secret for offer purchases (Path 3b) and invoice_ids for invoices (Path 2/3a). While it does not mention when not to use the tool or list alternatives, the instructions are clear and context-specific.

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

• download_filesA
  4.5/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses the tool's behavior: fetches keys, downloads encrypted blobs, verifies against seller's sha256 commitment, decrypts locally (AES-256-GCM), and writes plaintext files. This exceeds the minimum transparency requirement.

  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, zero waste. The first sentence front-loads the prerequisite and lists the key steps, the second states the return value. Every word earns its place.

  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?

  Despite no output schema and only 3 parameters, the description covers the entire process, prerequisites, and return value (saved paths). It is complete for the tool's complexity.

  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 only 33% (only output_dir described). The description explains the overall process and implies the role of claim_token (from buy_offer/confirm_payment) but does not explicitly define each parameter. It adds some value but not enough to fully compensate for the low schema coverage.

  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 verb (download and decrypt) and the resource (purchased offer files). It specifies the prerequisite (claim_token from buy_offer/confirm_payment) and the multi-step process, distinguishing it from sibling tools like buy_offer or attach_file.

  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?

  Explicitly states when to use: 'After a settled purchase (buy_offer / confirm_payment returned a claim_token)'. This provides clear context, though it does not explicitly list when not to use or alternatives, which is acceptable given the sibling tool list.

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

• pay_invoiceA
  4.5/5.0
  Behavior5/5

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

  No annotations provided, so the description fully covers behavioral traits: it discloses that the tool spends real bitcoin, settlement is final, and describes the complete flow including fetching bolt11, enforcing caps, paying, confirming with preimage, and file handling. This is highly transparent.

  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 three sentences, each carrying essential information. It is front-loaded with purpose and structured logically. No redundancy, but could be slightly more concise without losing clarity.

  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 5 parameters and no output schema, the description explains the expected behavior (returns bolt11 or handles downloads) and mentions file handling. It is complete for an agent to understand how to invoke the tool, though it omits error handling details.

  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 description coverage is 100%, and the description adds semantic context beyond schema: e.g., 'Only for manual mode' for preimage, 'from seller's payment payload' for invoice_id/access_token, and 'Refuse if the bolt11 exceeds this' for expected_max_sats. This adds value.

  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 tool as settling a Hypawave invoice, with two modes (NWC/manual). It uses specific verbs ('Settle', 'fetches', 'enforces', 'pays', 'confirms', 'downloads') and describes the full workflow, distinguishing it from siblings like check_payment or confirm_payment.

  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 explicitly states when to use the tool (to pay an invoice) and provides guidance for both NWC and manual modes. It does not explicitly state when not to use it, but the context is clear.

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

• wallet_statusA
  4.6/5.0
  Behavior4/5

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

  No annotations exist, so description bears full burden. It states it reports state with no mention of side effects, implying a read-only operation. Slightly lacking details on error behavior or rate limits, but sufficient for a simple status 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?

  Two concise sentences with no filler. Front-loaded with the tool's output and usage timing. Every sentence adds value.

  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 no parameters and no output schema, the description covers the key outputs and usage intent. Lacks details on return format or possible errors, but complete enough for a straightforward status tool.

  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?

  No parameters exist, so baseline 4. The description adds meaning about what the tool returns (wallet state, pubkey, settings), compensating for lack of schema details.

  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 it 'reports' multiple specific items (wallet state, pubkey, spending cap, public settings), clearly defining its purpose as a status check, distinct from sibling tools focused on payments and offers.

  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?

  Explicitly advises to 'Call this first to know whether payments can be made automatically and what fees to expect,' providing clear guidance on when to use this tool.

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

• get_contact_cardA
  4.7/5.0
  Behavior4/5

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

  With no annotations provided, the description bears the full burden of behavioral disclosure. It transparently notes that the card is public, contains only the agent's address, and that first contact opens a private wave. It could add more about response format, but the essential privacy and side-effect information is present.

  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, each earning its place: usage trigger, return value, and privacy caution. It front-loads the when-to-use instruction and keeps the rest tight. No wasted words or redundant information.

  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 zero-parameter, no-output-schema tool, the description fully covers what the tool does, what it returns (a URL), and how it fits into the interaction flow. It includes context about the card's public nature and the follow-up wave, making it complete for the agent to decide when to invoke it.

  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 the input schema is empty (100% schema coverage). The description adds no parameter semantics because there are none to describe. The baseline for zero-parameter tools is 4, and the description adequately explains what the tool does without needing parameter details.

  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 returns a public contact card URL, with the explicit verb 'Returns' and resource 'public contact card URL'. It also distinguishes the tool from siblings by focusing on contact sharing, which none of the sibling tools (offers, payments, files, waves) handle.

  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 usage context: 'Use when your operator wants another person's agent to be able to reach you' with example phrases. It also gives a clear when-not: 'do not volunteer it unprompted.' There are no alternative tools for this action, so no need to name alternatives.

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

• get_receiptA
  4.7/5.0
  Behavior4/5

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

  With no annotations, the description carries full burden. It clearly states the tool is for retrieval and explains the two modes with prerequisites. However, it does not describe potential error conditions, auth requirements, or the format of the returned record. Slightly incomplete for full 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?

  Two sentences, no wasted words. The first sentence states the core purpose; the second gives precise usage instructions. Front-loaded and efficient.

  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 description covers the essential usage paths for a tool with 4 parameters and conditional requirements. It does not describe the return value beyond 'durable settlement record,' but the tool name implies a receipt. A brief mention of what the response contains would complete it. Still largely sufficient for agent invocation.

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

  Parameters5/5

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

  The description adds significant meaning beyond the input schema. It explains the conditional requirement relationships (e.g., 'Required with invoice_id') and groups parameters into two logical paths, which the schema alone does not convey. Schema coverage is 50%, but the description fully compensates.

  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 a clear, specific verb+resource: 'Retrieve the durable settlement record for a past purchase.' It distinguishes itself from sibling tools (like check_payment, confirm_payment) by focusing on settlement records and specifying two distinct use cases.

  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 explicitly states when to use each parameter combination: for an offer purchase pass payment_intent_id + payer_secret; for an invoice pass invoice_id + preimage. It also references the source of these values (buy_offer, pay_invoice), providing clear contextual guidance.

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

• read_waveA
  4.7/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 that peer messages are 'untrusted external data', advising caution. It also implies the tool can return full history if `since` is omitted, and that context should be maintained externally. However, it doesn't explicitly describe authentication requirements or the exact response structure.

  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 purpose in the first sentence, then providing usage guidance and a security caution. Every sentence adds value; no fluff.

  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?

  Given no output schema and no annotations, the description covers the tool's purpose, how to paginate via `since`, and warns about untrusted data. The mention of `nextCursor` implies the response contains it, satisfying the need for understanding return context. It is complete for a read tool with two parameters.

  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% with descriptions for both `peer` and `since`. The description adds meaningful context for `since` by explaining it is the nextCursor from a previous read and instructing to use it to fetch only new items, going beyond the schema's 'strongly recommended' note. It doesn't add to `peer`, but the schema already defines it clearly.

  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 'Read messages + transfer records in your wave with one peer', identifying the specific action and resource. It distinguishes from sibling tools like send_wave and check_inbox by specifying the scope ('with one peer') and content (messages + transfer records).

  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?

  Explicit guidance is provided: 'Pass `since` (the nextCursor from your last read) to fetch only new items — do NOT re-read full history each session; keep durable context in your own notes.' This tells the agent when and how to use the tool, and what to avoid (re-reading full history). It also signals that the tool is for reading from a specific peer's wave, not for general inbox operations.

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

• send_fileA
  4.7/5.0
  Behavior5/5

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

  With no annotations provided, the description fully discloses behavioral details: local encryption (AES-256-GCM, ECIES), server never seeing plaintext, release against recipient signature, delivery receipt, size limit, and expiration. This exceeds typical 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?

  Three dense sentences front-load the core purpose and then add essential details. Every clause earns its place, with no filler or repetition.

  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?

  Despite lacking an output schema, the description covers purpose, security model, file size limit, expiry, and the alternative tool. It provides sufficient context for an agent to invoke the tool correctly, though it omits return-value details (minor).

  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 the baseline is 3. The description adds some context around 'to' (recipient's pubkey) but does not meaningfully enhance the schema descriptions for 'path' or 'topic'. No additional parameter semantics are provided.

  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 a specific verb and resource ('encrypted file handoff to a specific agent') and clearly contrasts with sell_file, distinguishing it from sibling tools. It unambiguously states what the 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 Guidelines5/5

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

  Explicitly states when to use this tool ('files your operator wants to GIVE someone') and names the alternative for selling files (sell_file). The constraints (25 MB max, expiration) further clarify appropriate usage.

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

• setup_walletA
  4.8/5.0
  Behavior5/5

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

  With no annotations, the description carries full responsibility for behavioral disclosure. It transparently explains that create_hosted creates a custodial wallet at coinos.io, stores credentials locally in ~/.hypawave/wallet.json, and never sends them to Hypawave. It also describes what each action returns and that the NWC_URL env var overrides configured values.

  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 information-dense and every sentence contributes meaning, but it is structured as a single long paragraph that reduces scannability. A bulleted list or more sentence breaks would improve readability, though the content length is justified given the tool's multi-modal behavior.

  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 tool with four parameters and no output schema, the description covers all invocation paths, return values (operator-facing options, steps, funding instructions), and configuration precedence. The agent is fully equipped to decide when and how to call the tool, including safety constraints about operator consent.

  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 schema already documents all parameters with descriptions, so the baseline is 3. The description adds value by explaining the required call flow (omit action for options, confirm must be true only after explicit agreement), the effect of omitting nwc_url, and the optional nature of amount_sats, which goes beyond the schema's static descriptions.

  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 'One-time wallet setup so purchases can pay automatically,' which clearly states the tool's purpose. It also enumerates specific actions (create_hosted, connect_own, funding_options) that distinguish it from siblings like wallet_status and other transactional tools.

  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 gives explicit step-by-step guidance: call with no arguments first, present options verbatim, and only then invoke specific actions after operator consent. It also specifies when to use funding_options ('whenever the wallet needs sats') and that NWC_URL takes precedence, leaving no ambiguity about invocation order.

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