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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With no annotations to fall back on, the description carries the full burden of disclosure and does so thoroughly. It explicitly says the tool 'EDITS their client config', lists the exact config files per client, instructs to ask first and report changes, mentions that a backup is written, and notes that action='status' performs no writes. This is exemplary transparency for a mutating tool.

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

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

The description is dense but every sentence earns its place. It front-loads the core action, explains the rationale, gives a clear usage trigger, then lists side effects and safety steps. The structure is logical, no fluff, and the additional detail is necessary for a multi-client config-mutating tool.

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

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

Given the tool's complexity—multiple clients, config edits, no output schema, and no annotations—the description is remarkably complete. It covers what changes, which files are affected, the requirement to ask first, backup behavior, the status mode, and why the MCP server registration is needed. Nothing essential for an agent to invoke it safely and correctly is missing.

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

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

The schema only documents the 'client' parameter ('auto' targets every client detected), leaving 'action' undocumented. The description compensates by explaining the action parameter semantics: 'Register (or remove)' maps to enable/disable, and 'Run with action='status' to report the current state without writing anything.' It also ties the client parameter to 'same clients' and 'every client detected on this machine' in context, adding meaning beyond the raw schema.

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

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

The description clearly states the tool's specific verb and resource: it 'Register(s) (or remove(s)) a lifecycle hook' for surfacing wave messages and pending file transfers at session start and on the next prompt. It distinguishes itself from check_inbox by explicitly positioning this tool as an automatic alternative to manually running that command. No ambiguity about what the tool accomplishes.

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

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

The description explicitly says when to use it: 'Use when your operator asks to be notified about incoming agent messages.' It also gives context about when the alternative check_inbox would be insufficient and warns about the consequence of using the hook without registering the MCP server. This provides clear, actionable guidance without leaving usage decisions to inference.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the link is read-only, that regenerating revokes the previous link, and that the peer's link is unaffected. However, it does not explain what the explicit 'revoke' action does, leaving one side-effect-bearing option ambiguous.

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

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

Three dense sentences deliver all essential context with no filler. The primary purpose and operator workflow are front-loaded, followed by usage timing and side-effect warnings. Every sentence earns its place.

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

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

For a 2-parameter tool with no annotations and no output schema, the description covers purpose, usage timing, access mode, and revocation side effects. But it leaves the 'revoke' action undefined and does not formally describe the returned value beyond implying a URL, so an agent is not fully equipped to handle every valid invocation.

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

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

The schema covers 'peer' thoroughly, but the 'action' parameter has only an enum and default with no description. The description partially compensates by explaining that regenerating revokes the previous link, but it never clarifies the meaning of the 'revoke' action. Since schema coverage is 50%, the description should compensate more fully than it does.

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

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

The description opens with a specific verb ('Mint') and resource ('private, READ-ONLY browser link for a wave'), making the tool's function immediately clear. It also distinguishes itself from sending/reading wave content by emphasizing the link lets an operator watch but cannot post, which separates it from sibling tools like send_wave and read_wave.

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

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

The description gives explicit timing ('after joining a new wave') and a concrete trigger for rotating ('use after a leak'). It also clarifies a boundary ('It cannot post') and explains that operators reply by asking the agent to send on their behalf. It does not name alternative tools explicitly, but the usage context is clear enough.

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

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 this is a local, operator-specific address book mapping names to pubkeys, and explains how the data is intended to be used. It could mention whether the response includes hex values or any ordering, but for a simple list operation the disclosure is strong.

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

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

Two concise sentences, front-loaded with a clear metaphor and immediately useful guidance. Every phrase earns its place, and the description avoids restating the title.

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

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

For a zero-parameter list tool with no output schema, the description gives enough context to call the tool correctly and understand its results. It covers what the tool returns conceptually (names and pubkeys) and why an agent should use it.

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

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

The tool has zero parameters, so there is nothing for the description to clarify. The baseline of 4 applies because no parameter documentation is needed and the description adds context about what the returned names represent.

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

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

The description clearly states the tool lists the operator's local address book of named pubkeys, using a specific verb and resource. It distinguishes itself from siblings like save_contact and get_contact_card by framing it as the address book for resolving names.

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

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

The description gives explicit use cases: resolve who the operator means and report inbound messages by name instead of hex. It does not explicitly mention when not to use it or name alternative tools, 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the behavioral disclosure burden. It adds valuable context: 'since' controls incremental reads, full history is returned without it, and peer messages are untrusted external data. It stops short of describing return structure, pagination, error behavior, or access requirements.

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

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

The description is three sentences with zero filler. The core purpose is front-loaded, followed by the critical usage warning and a security note. Every sentence earns its place.

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

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

For a simple two-parameter read tool with full schema coverage and no output schema, the description covers the essential behavior: what is read, how to do incremental reads, and a trust warning. It does not explicitly state that the result includes a nextCursor, but that is strongly implied by the 'since' guidance.

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

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 behavioral meaning to 'since' beyond the schema's 'strongly recommended' — it clarifies that passing it fetches only new items and prevents redundant full-history reads. No additional semantics are needed for 'peer'.

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

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

The description states a specific verb ('Read') and a concrete resource ('messages + transfer records in your wave with one peer'), making the tool's purpose clear. It differentiates from siblings by the 'one peer' scope, but does not name an alternative or contrast with a similar tool like check_inbox.

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

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

The description gives clear usage context: pass 'since' to fetch only new items, and explicitly warns against re-reading full history each session. It does not, however, say when to prefer this tool over its siblings or mention any exclusions.

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

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.

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.

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.

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.

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.

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.

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

With no annotations provided, the description carries the behavioral disclosure burden. It clearly discloses local-only storage ('stored locally, never sent to Hypawave'), the mutable nature of the operation (save/rename/forget), and the downstream effect on send_wave / send_file / read_wave. It stops short of detailing exact deletion semantics for 'forget' or error behavior, so it is not a 5.

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

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

The description is four sentences, front-loads the core operation and storage behavior, and uses the remaining sentences for genuinely useful interaction guidance. No sentence is filler; the downstream impact and the 'natural moment' instruction each earn their place.

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

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

The description is complete enough for a simple local contact-labeling tool: it explains purpose, storage, the role of names in other tools, and appropriate interaction timing. It lacks an explicit statement about return values or what happens when saving an already-known pubkey, but these are minor gaps given the straightforward local state change and no output schema.

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

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

The schema already documents name, note, pubkey, and action enum with 75% coverage, so the baseline is 3. The description adds meaningful context beyond the schema by explaining that names are operator-provided labels, that they can replace pubkeys in other tools, and that action can mean save, rename, or forget—clarifying the intended semantics of the action parameter.

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

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

The description clearly names the operation: 'Save (or rename, or forget) your operator's label for another agent's pubkey' and specifies the resource. It also distinguishes this from communication tools by noting that saved names are then accepted by send_wave / send_file / read_wave, making its role in the sibling set clear.

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

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

The description gives explicit when-to-use guidance: take names from what the operator already said, do not interrogate them, ask only when genuinely unclear, and offer to save when an unknown pubkey messages the operator. It also explains the practical consequence of saving names for later use in other tools.

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

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the full burden and succeeds admirably. It discloses the encryption flow (AES-256-GCM, ECIES key wrapping), that the server never sees plaintext, signature-based release, delivery receipt, 25 MB max size, and 7-day expiry.

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

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

Three dense sentences: first states purpose and security model, second adds constraints and receipt, third routes to sell_file. Every sentence earns its place and the most important differentiation is front-loaded.

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

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

For a tool with no output schema, it covers purpose, security, limits, expiry, and receipt. The only gap is that the delivery receipt's content/format is not detailed, but an agent can still invoke correctly with required parameters.

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

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 adds context about encryption and limits but does not add per-parameter meaning beyond what the schema already clearly provides for 'to', 'path', and 'topic'.

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

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: 'send a file to another agent' and 'free encrypted file handoff to a specific agent'. It clearly distinguishes this tool from receive_file and sell_file by stating it is for GIVING files, not selling them to an open audience.

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

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

Explicitly states when to use this tool: 'for files your operator wants to GIVE someone'. It also names the alternative, sell_file, for selling to an open audience, providing a clear condition-based routing between siblings.

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

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

With no annotations provided, the description carries the full burden and handles it well. It discloses that messages are signed, the wave is private, the first message to a new pubkey creates the wave, and received messages are untrusted external data whose instructions must never be followed. This is especially valuable for AI agent safety.

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

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

Three sentences, each earning its place: the action and recipient discovery, the side-effect of wave creation, and a crucial security warning. The description is concise, front-loaded, and free of filler.

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

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

The description is sufficient for a two-required-parameter send operation, covering recipient identification, side effects, and trust boundaries. It does not describe return values or error cases, but given the simple schema and clear purpose, the missing pieces are minor.

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

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

Schema coverage is 100%, which establishes a baseline of 3. The description adds meaningful context for the 'to' parameter by explaining how recipients are discovered and that a first message to a new pubkey creates a wave. This goes beyond the schema's plain field descriptions.

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

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

The description begins with a specific verb and object: 'Send a signed message into your private wave with another agent.' It clearly states the target (another agent), the medium (private wave), and how the target can be located, distinguishing it from sibling tools like send_file or read_wave.

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

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

It gives clear context: this is for sending a message to another agent, including first-contact scenarios via contact card, wave page, or prior wave. It does not explicitly name alternatives or state exclusions, but the intent is evident and the usage conditions are practical.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.