tollbooth-sample

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

With no annotations provided, the description effectively discloses key behaviors: the tool is free (no credits consumed), requires proof of npub ownership via dpop_token, and focuses on spending account data (not operator authority). It explains the dpop_token format in detail. However, it does not mention potential side effects (likely none) or rate limits, leaving some gaps.

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?

Six focused sentences, starting with the core purpose. Every sentence adds value: what is returned, what it is not, cost, and authentication requirement. No redundancy or fluff. Ideal conciseness.

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 presence of an output schema and moderate complexity (3 parameters), the description is complete. It covers all key aspects: data returned, cost, authentication, and scope (spending vs. authority). With an output schema, return value details are not needed. No obvious gaps.

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 baseline is 3. The description adds significant value by explaining the dpop_token parameter in detail (raw JSON, required tags, timing constraints) and noting the days default. This goes beyond the schema's field descriptions, justifying a score above baseline.

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 generates a patron's account statement, listing specific data returned (purchase history, credit tranches, usage breakdown, daily logs) and explicitly distinguishes it from the operator's Authority tax balance. This aligns with sibling context (e.g., weather_account_statement_infographic likely returns an infographic version).

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?

No explicit when-to-use or when-not-to-use guidance. While it notes the tool is free and requires npub ownership proof, it does not contrast with alternatives like weather_check_balance for quick balance checks or weather_account_statement_infographic for visual summaries. Usage is implied but not differentiated.

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 behavior: SVG generation, cost of 1 api_sat per call, and proof verification by 'debit_or_deny' before cost is incurred.

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 paragraphs, front-loaded with the main purpose, each sentence adds value without redundancy or fluff.

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 an output schema exists and the tool has only 3 parameters, the description adequately covers behavior, cost, and verification, fulfilling contextual needs.

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% and the description does not add extra meaning beyond what is in the schema, providing only a general reference to parameters.

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 generates an SVG infographic of an account statement, and distinguishes itself from the sibling tool 'weather_account_statement' by noting it returns the same data rendered as a graphic.

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 contrasts with 'weather_account_statement' and mentions cost, implying when to use for visual output, but does not explicitly list when not to use or provide alternative conditions.

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 full burden. It discloses that the operation is free, polls via MCP-to-MCP, and returns status values ('pending/approved/rejected/provisioned'), implying it is read-only. However, it does not detail error handling, authorization requirements, or side effects. Still, it provides enough context for safe invocation.

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 extremely concise: just two sentences with no wasted words. It is front-loaded with the core purpose and provides essential details (free, polling, possible statuses) in a clear, efficient format.

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 that an output schema exists, the return values are documented separately. The complexity is low (2 params, 1 required), and the description covers the main purpose and behavior. However, it omits explanation of the dpop_token parameter and does not mention error scenarios. Overall, it is nearly complete but has a minor gap.

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 has 2 parameters (authority_npub required, dpop_token optional) but schema description coverage is 0%. The description mentions 'chosen Authority' which maps to authority_npub, but does not explain dpop_token. Thus, only one parameter is partially described. The description adds some value but does not fully compensate for the lack of schema 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 clearly states 'Check this operator's adoption-request status at a chosen Authority.' This specifies the verb (check), the resource (adoption-request status), and the context (operator at Authority). It distinguishes itself from sibling tools like weather_request_adoption (which creates a request) and weather_get_operator_onboarding_status (which checks onboarding status).

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 says 'Free. Polls the Authority MCP-to-MCP for the status of this operator's request.' It indicates that the tool is free and performs polling, but it does not provide explicit guidance on when to use this tool versus alternatives (e.g., weather_request_adoption). There is no mention of when not to use it or prerequisites.

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?

Without annotations, the description carries the full burden. It discloses the return value (sats available), the condition at zero balance, and the consequence (patron top-ups cannot be certified). It also mentions the tool is 'Free', implying no cost. However, it does not explicitly state that the tool is read-only or non-destructive, which is inferred but not guaranteed.

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 and front-loaded, with the first sentence immediately stating the purpose. Each subsequent sentence adds valuable information without redundancy or fluff.

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 zero parameters and the presence of an output schema, the description is fully complete. It explains the tool's role in the broader process (patron top-up certification) and its relationship to purchase_credits, which is helpful for an AI agent deciding between sibling tools.

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 zero parameters with 100% coverage, so the baseline is 3. The description does not add parameter-level details since none exist.

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 the operator's tax balance at the Authority, specifying it returns the sats available for certifying patron credit purchases. It distinguishes itself from sibling tools like weather_check_balance by clarifying this is the operator's own funding, not a patron balance.

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 explains when to use the tool (to check available sats for patron top-ups) and what action to take when the balance reaches zero (call purchase_credits). It also clarifies the balance is operator-specific, preventing misuse with patron balances.

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?

Discloses that the tool is free ('no credits required') and requires proof of npub ownership to prevent balance enumeration. However, does not mention what happens on failure (e.g., invalid npub).

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 concise paragraphs, each sentence adds value. Front-loaded with primary purpose, then context.

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?

Covers purpose, distinction from sibling, cost, and authentication requirement. Output schema exists, so return values need not be described. Complete for a simple balance check 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 covers both parameters with descriptions. The description adds context about the dpop_token purpose (proof of ownership) and explains the balance type, adding 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 clearly states 'Check a patron's credit balance at this operator', specifying the verb and resource. It distinguishes from the sibling tool 'authority_check_balance' by contrasting patron vs operator balances.

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 tells when to use (check patron balance) and when not to (use authority_check_balance for operator balance), providing a clear alternative.

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 that the tool is free, requires proof of npub ownership, and explains the reason (anti-front-running). This is good behavioral context, though it does not detail side effects or return behavior.

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 extremely concise—four short lines—with no wasted words. It front-loads the purpose and flows logically.

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 purpose, usage timing, cost, and authentication requirement. Given the tool's simplicity (3 params, no nested objects, output schema present), it is fully complete and leaves no gaps.

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?

Input schema has 100% coverage with detailed descriptions for each parameter. The description adds context about when to call (after purchase_credits) but does not provide additional meaning beyond the schema. Baseline of 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's purpose: 'Check the payment status of a Lightning invoice.' It specifies the exact action (check) and the resource (payment status), and distinguishes itself from siblings by linking to purchase_credits.

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 'Call after paying the invoice from purchase_credits' and notes it is free, providing clear when-to-use guidance. It does not mention alternatives or when not to use, which would improve clarity further.

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 discloses that the tool is a preview (not a mutation) and is free (no credits required), adding behavioral context beyond the absent annotations. However, it does not mention authentication needs (npub, dpop_token) or any 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 three sentences long, front-loads the main purpose, and contains 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 the tool's simplicity and the presence of an output schema, the description provides adequate purpose and behavioral info. However, it lacks details on parameter usage and optional inputs, which would help the agent use 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?

With schema description coverage at 50%, the description does not add any meaning to the parameters beyond what the schema provides. It does not explain the purpose of npub or dpop_token, nor the usage of tool_kwargs for pricing preview.

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 previews the effective cost of a tool call, using a specific verb ('preview') and resource ('cost of a tool call'). It distinguishes this from sibling tools like weather_check_balance and weather_check_payment by focusing on cost preview.

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 implies usage when the agent needs to know the cost of a tool call before executing it, but it does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it.

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 and clearly states the tool is free, has no side effects, and does not evict the cache or touch relays. This provides good behavioral insight, though it could mention whether authentication is needed.

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 very concise: four sentences covering purpose, context, usage scenario, and side effects. Every sentence adds value, and key information is front-loaded in the first sentence.

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 annotations and an output schema (unknown content), the description provides reasonable completeness. It covers the core function, utility, and side effects. It could elaborate on what 'valid' means or error handling, but overall sufficient.

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?

Both parameters are fully described in the input schema (100% coverage). The tool description adds no additional semantic value beyond the schema, so baseline score of 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's purpose: checking validity of a cached dpop_token. It distinguishes itself from the similar check_oauth_status by specifying it's for the npub-proof flow, which differentiates it among siblings.

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 this tool: before a paid call to avoid burning credits on a failure. It also mentions that it mirrors check_oauth_status, implying the alternative for other authentication flows.

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 must disclose behavioral traits like side effects or authorization needs. It only states the output fields and data source, omitting that the npub parameter indicates credit-based billing and that the tool requires authentication. It does not mention rate limits, destructive potential, or idempotency.

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 short sentences that front-load the purpose and return information. Every word adds value, with no redundancy or 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?

An output schema exists, so the description need not explain return values. However, the description lacks billing context and prerequisites. For a tool with no annotations, it should mention the npub requirement or that credits are consumed, leaving the agent with incomplete context for safe 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?

Input schema has 4 parameters, all with descriptions (75% coverage). The description adds no additional meaning beyond the schema, merely implying the location parameters via 'for a location'. Given high schema coverage, 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 is for retrieving current weather conditions, specifying the verb 'Get' and resource 'current weather conditions'. It also lists the return fields (temperature, wind speed, weather code) and the data source (Open-Meteo). The name 'current' distinguishes it from sibling tools like 'weather_forecast' and 'weather_historical'.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as the required npub parameter for billing, nor does it advise against using it for forecasts or historical data. The agent must infer usage purely from the tool name.

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?

Discloses cascade deletion, effect on chain steps (neutral on unknown ids), and studio warnings. With no annotations, this provides good insight into tool behavior, though it could mention reversibility or audit trail.

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?

Very concise, three sentences, front-loaded with the primary action and cascade effect. Every sentence adds value with no extraneous content.

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 presence of an output schema, the description appropriately focuses on input behavior and side effects. It covers delete action, cascade, and authorization. Missing details about return values are compensated by the 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?

Schema coverage is 0% and the description adds no meaning to parameters. It does not explain coupon_id or dpop_token beyond what the schema already provides (type and default). This is a significant gap.

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 deletes a coupon and describes the cascade effect on patron redemptions and chain steps. Distinguishes from siblings like weather_update_coupon or weather_redeem_coupon.

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 'RESTRICTED to operator — requires proof', indicating who can use it and the prerequisite. Does not explicitly compare to alternatives or state when not to use, but the context is sufficiently 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 exist, so the description carries full burden. It discloses that this is a write operation to a sensitive credential vault, requires proof of npub ownership, and is free. It states deletion affects only one field without affecting others. While it doesn't elaborate on response or error conditions, it provides sufficient behavioral context for a deletion 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 two sentences long, front-loaded with the primary action. It includes the key points (action, safety, cost, auth) without extraneous words. Every sentence adds value, making it concise and well-structured.

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 presence of an output schema (context signal) and full schema coverage, the description explains the core purpose, behavioral implications, and authentication requirement. It doesn't differentiate from similar tools like 'weather_forget_credentials' or detail output, but it is largely complete for a straightforward deletion 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 coverage is 100%, with detailed descriptions for all three parameters. The description adds minimal extra meaning: it ties 'dpop_token' to proof of ownership and 'field' to targeted deletion. This marginally enhances understanding but does not significantly expand on the schema 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 clearly states 'Remove a single patron credential field' and 'Deletes one field from stored credentials without affecting other fields.' The verb (remove/delete) and resource (patron credential field) are specific. It distinguishes from siblings like 'weather_update_patron_credential' (overwrites) and 'weather_forget_credentials' (likely removes all) by focusing on single field deletion without side effects.

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 mentions 'Free' and 'Proof of npub ownership is required,' providing some context for when to use. However, it does not explicitly state when not to use this tool versus alternatives like 'weather_update_patron_credential' or 'weather_forget_credentials.' No exclusionary guidance is given.

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 full burden. It discloses the output structure but does not mention authentication requirements (npub is required but not described as auth), rate limits, caching, or the credit billing mechanism. Behavioral traits beyond output are omitted.

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?

Extremely concise at two sentences, with the primary purpose front-loaded in the first sentence and output details in the second. No 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?

The description covers the return values but omits critical context such as the requirement for an npub for credit billing, the purpose of dpop_token, and any authentication flow. For a tool with 5 parameters and an output schema, this is insufficient for the agent to handle billing and authorization 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 80% (4 of 5 parameters have descriptions), so baseline is 3. The tool description does not add new meaning beyond the schema; it implicitly references 'days' via 'multi-day' but offers no extra context for npub (required for billing) or dpop_token.

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 retrieves a multi-day weather forecast for a location, specifying return values (daily high/low temperatures and precipitation) and the range of days (1-16). This distinguishes it from sibling tools like 'weather_current' (current conditions) and 'weather_historical' (past data).

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?

No explicit guidance on when to use this tool versus alternatives such as weather_current or weather_historical. The description does not clarify that this is for future forecasts only, leaving the agent to infer usage context without direction.

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 adequately discloses that the operation is cosmetic, the coupon persists, and re-redemption is possible. It also notes it is free and requires npub proof, though it does not detail side effects or error conditions.

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 action, and provides essential behavioral context without any fluff. 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 the existence of an output schema, the description does not need to detail return values. It covers the key behavioral nuance (cosmetic removal) and prerequisites (npub proof). However, it omits error handling and token details, leaving minor gaps.

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 0%, so the description must add meaning. It explains npub (requires proof) and coupon_id implicitly, but dpop_token is not mentioned. This partially compensates for the lack of schema documentation.

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 'Remove a coupon from this patron's redemption list,' which is a specific verb+resource. It further differentiates from siblings like weather_delete_coupon by noting it is 'cosmetic only' and the coupon still exists.

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 'cosmetic only' and that the patron can re-redeem later, implying when this tool is appropriate. It does not explicitly state when not to use it, but the context provides clear 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 effectively discloses that the operation is destructive and requires authentication (dpop token). This adds necessary behavioral context beyond the input 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?

Two concise sentences that front-load the core function and then provide usage context. Every sentence adds value 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?

Given the presence of an output schema and detailed parameter schema, the description covers the essential function and usage context. It mentions destructive nature and authentication, though could note what happens on failure or success.

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 parameter descriptions are detailed (e.g., dpop_token specifies format and constraints). The tool description does not add extra parameter info, meeting the baseline expectation.

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 ('Delete vaulted credentials') and the target resource ('for a specific service and npub'). It distinguishes from sibling tools like weather_delete_coupon and weather_delete_patron_credential by focusing on vaulted credentials.

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?

Provides guidance on when to use operator vs patron npub and emphasizes the requirement for proof of ownership. Does not explicitly list when not to use or name 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, description carries full burden. Discloses read-only nature, public accessibility, and return behavior (fields or empty profile). No contradictions.

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 concise sentences: action, context (free/public), returned fields. No unnecessary words.

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?

Covers all necessary aspects: purpose, parameters, returns, edge case (empty profile), and context (free/public). With output schema present, return details are adequate.

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?

Only one parameter 'npub'; description explains it as a public key in context ('Read an npub's public Nostr profile'). Schema has 0% coverage, so 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?

Clearly states 'Read an npub's public Nostr profile' (specific verb+resource), specifies NIP-01 kind-0 metadata, and lists returned fields. Distinguishes from sibling 'weather_publish_nostr_profile'.

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 'Free, no proof — the data is already public on relays,' indicating no authentication needed and public data. Implicitly suggests when to use (for reading profiles) but does not explicitly mention alternatives or 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?

With no annotations, the description should fully disclose behavior. It states the tool generates a proof (implying a read-only operation) but does not explicitly mention side effects, prerequisites, or whether the operation is destructive. The description is adequate but lacks explicit behavioral clarity.

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, clear sentence with no wasted words. It is front-loaded with the key action and resource.

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 low complexity (2 params, no enums, output schema exists), the description adequately explains the tool's purpose. It does not elaborate on the output format, but the output schema presumably covers that. Minor gap: no mention of what the proof contains.

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 schema already documents both parameters. The description adds no additional meaning beyond what the schema provides (e.g., 'npub' and 'notarization_id' are described in 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?

The description clearly specifies the verb 'Generate' and the resource 'Merkle inclusion proof' with context about a patron's balance in a Bitcoin-notarized snapshot. This distinguishes it from sibling tools like 'weather_receive_npub_proof' or 'weather_check_proof_status'.

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 does not provide any guidance on when to use this tool versus alternatives (e.g., when to generate a proof vs. check proof status). No exclusion or context for when not to use it is given.

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 discloses what the tool shows (configured/missing settings, delivery instructions) and implies read-only behavior. However, it could clarify if any side effects or authentication requirements exist.

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 concise sentences, front-loaded with purpose, minimal waste.

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?

With an output schema present and zero parameters, the description sufficiently covers the tool's purpose and behavior.

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 is 4. Description adds no extra beyond schema but is not needed.

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 reports operator configuration readiness, listing specific outputs (configured, missing, delivery instructions). It distinguishes from the sibling 'get_patron_onboarding_status' for patron-level status.

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 tells when to use this tool (operator readiness) and when to use the alternative 'get_patron_onboarding_status' for patron-level credential status.

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 covers behavior: it returns field names and delivered_at timestamps (null for old records), never exposes values, is free, and requires proof of ownership. It does not discuss error handling or limits, but the core behavior is well explained.

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 at four sentences, front-loads the core purpose, and uses clear structure. Every sentence adds value, with no redundant or extraneous content.

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 simple parameter set and presence of an output schema, the description provides all necessary context: purpose, return value structure, authentication requirement, and cost. No gaps remain.

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 detailed parameter descriptions. The description adds context about dpop_token being proof of ownership, but does not fundamentally extend meaning beyond the schema. 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 verb ('List') and the resource ('stored patron credential field names'), and distinguishes it from siblings like weather_delete_patron_credential or weather_update_patron_credential by noting it returns only names and timestamps, not values.

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 tells when to use ('verify which fields are configured and how old each one is') and notes prerequisites (proof of npub ownership). It does not explicitly list when not to use or compare to alternatives, but the purpose is sufficiently clear to avoid misuse.

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 the description carries full burden. It discloses that the tool is free, requires dpop_token for proof, and explains behavior per service type. It does not discuss rate limits or error cases, but is otherwise 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?

Two concise paragraphs with front-loaded purpose. Every sentence adds information without redundancy. Could be slightly more structured but 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 that an output schema exists, the description adequately explains return value types for different service categories. It does not list all possible secrets, but provides sufficient context for an agent to understand the tool's output.

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%, but the description adds value by explaining why dpop_token is needed (proof of ownership) and how patron_npub is used. This goes beyond the schema's minimal 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 clearly states the tool reports a patron's credential readiness, specifying that for set-once services it shows configured/missing secrets, and for dynamic/OAuth2 services it reports no credentials needed. This distinguishes it from siblings like weather_delete_patron_credential or weather_get_operator_onboarding_status.

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 implies usage for checking readiness before credential-dependent operations, and explicitly states proof of npub ownership is required. It does not explicitly list alternatives or when not to use, but the context of sensitive information provides sufficient 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?

The description discloses a key behavioral trait: 'If no model exists, self-initializes a scaffold with all registered tools at 0 sats.' This reveals a side effect that goes beyond a simple read. It also states 'No economic data from code,' clarifying a limitation. However, it does not mention authorization requirements or whether the initialization is idempotent. Since there are no annotations, the description carries full burden and does a good job overall.

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 extremely concise—two short sentences that front-load the main purpose and immediately provide critical behavioral context. Every sentence adds value; there is no wasted text.

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 no parameters and an output schema exists, the description provides sufficient context, including the self-initialization behavior. However, it could mention that this is a read operation with a potential write side effect more explicitly. Overall, it is fairly 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 tool has zero parameters, and the input schema covers 100% of parameters (none). The description adds no parameter info, which is acceptable as there are none to document. Per the guidelines, 0 parameters yields a baseline of 4.

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 'Get the active pricing model for this operator,' specifying the verb and resource. It also notes that the tool is free. However, it does not explicitly distinguish itself from sibling tools like weather_set_pricing_model or weather_reset_pricing_model, though the name and action make the distinction obvious.

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 no guidance on when to use this tool versus alternatives. It does not mention when to prefer this over weather_set_pricing_model or when not to use it. The context of usage is implied but not explicit.

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 available, the description only states what is returned (daily temperature and precipitation) but does not disclose other behavioral traits like side effects, authentication 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 two sentences, front-loaded with the primary action, and contains no wasted words.

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 adequate for a straightforward historical data retrieval tool, especially with an output schema present. However, it could mention date range limitations or data source reliability.

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 83%, so the baseline is 3. The description does not add any additional meaning beyond what the schema already provides for the parameters.

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 it retrieves historical weather data for a location and date range, which distinguishes it from siblings like 'weather_current' and 'weather_forecast'.

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?

No guidance is provided on when to use this tool versus alternatives, nor are there any prerequisites or exclusions mentioned.

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 full burden. It openly states 'Free, no side effects,' explicitly naming the tool as safe and non-mutating. It also discloses the diff behavior against the live FastMCP wire surface and the unregistered flag semantics, being transparent about what the tool reports beyond a simple list.

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 well-structured with sections covering purpose, use case, canonical-UUID rationale, drift detection, and safety. It's longer than strictly necessary but every sentence adds value — the canonical-design explanation and the drift-flag rationale genuinely help the agent understand the tool's role. It front-loads the core purpose and adds detail afterward.

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?

There is an output schema present, so return value details don't need to be in the description. The tool is complex in purpose (canonical identity, drift detection, unregistered reporting) and the description fully explains the nuance, references issues (#174, #175), and states safety explicitly. Complete for a read-only introspection 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?

The tool takes zero parameters, so the 100% schema coverage trivially suffices. The description adds context about the output shape (registered true/false, top-level unregistered array) which enriches understanding of what's returned, though it doesn't need to document parameter semantics since there are none.

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+resource: 'Return canonical (tool_id, mcp_name, …) for every tool the wheel exposes.' It clearly describes what the tool does, who it serves (Studio, agents, FE), and distinguishes its canonical-UUID role from sibling tools which operate on weather data, coupons, pricing, etc. This uniquely positions the tool in a large sibling set.

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 this is 'the authoritative source for any client' needing to know how the MCP identifies its tools, and describes the Reconcile UUID-join use case ('no name-based UUID derivation, no guessing'). It also explains the unregistered/registered:false behavior with issue references, giving clear guidance on when and why this tool matters.

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 full burden. It discloses that the tool is free and returns type, category, description, and parameter specs. It is transparent about cost and output, but lacks details on side effects.

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 waste. The first sentence states the action and object, the second lists return fields and cost. Highly efficient and 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?

Given the tool has an output schema, the description provides a high-level summary. It mentions 'pricing pipeline' for context and is complete for a straightforward listing tool. Could be slightly more specific about scope.

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 100% schema coverage (empty). The description adds meaning by detailing the return fields (type, category, description, parameter specs), which is valuable for a no-param tool.

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 'List all available constraint types and their parameter schemas,' which is a specific verb+resource. It distinguishes from sibling tools, none of which mention constraint types.

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 implies usage by stating 'Free — no credits required' but provides no explicit guidance on when to use this tool vs alternatives or any prerequisites.

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 must disclose behaviors. It mentions the sort order and output fields, but does not state whether the operation is read-only or destructive, nor any side effects 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 concise, using two short paragraphs with the core action in the first sentence. It is well structured and 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?

Given the tool's simplicity (1 param, simple list output) and the presence of an output schema, the description adequately covers the purpose and output hints. The missing parameter explanation is a minor gap.

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 sole parameter dpop_token has no schema description (0% coverage) and is not explained in the description. The description therefore fails to add 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?

The description clearly states it lists coupons minted by the operator, sorted newest first. This distinguishes it from sibling tools like weather_list_my_coupons, which likely shows the user's own coupons.

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 specifies 'RESTRICTED to operator — requires proof,' indicating the intended user and authentication needs. It implies that non-operators should use alternatives, though it does not explicitly name them.

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 discloses behavior: it returns both active and exhausted redemptions with specific statuses. It also states it's 'Free' (cost implication). However, it doesn't describe potential side effects, but since it's a list operation, this is sufficient.

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 verb and resource. Every sentence adds value: the first states the primary purpose, the second adds details about return content and a prerequisite. No unnecessary words.

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 main behavior and return values, and output schema exists so return details are adequate. However, it omits explanation of the 'dpop_token' parameter and the broader context of the 'free' claim (e.g., what conditions apply). Given the tool has 2 parameters and no annotations, the description should be 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 description coverage is 0%, and the description does not explain the 'dpop_token' parameter. It only hints that 'npub' is required ('requires proof of npub'), but does not elaborate on its format or the role of 'dpop_token'. With no parameter details in the description, it fails to compensate for the schema's lack of 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 clearly states the tool lists redeemed coupons for a patron on an operator, using the verb 'list' and specifying the resource as 'coupons this patron has redeemed'. It distinguishes from sibling tools like 'weather_list_coupons' by focusing on patron-specific redemptions.

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 mentions a prerequisite ('requires proof of npub') and implies it's for listing redeemed coupons, but does not explicitly state when to avoid this tool or mention alternatives like 'weather_list_coupons' for all coupons. Clear context but no 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?

No annotations are provided, so the description bears full responsibility for disclosing behavior. It only says 'List recent Bitcoin notarization records' without explaining ordering, pagination, recency criteria, idempotency, or potential side effects. This is insufficient for an agent to safely invoke the 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 a single sentence with no wasted words. However, it omits critical usage context, which reduces its overall efficiency. The conciseness is good but comes at the cost of completeness.

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 having an output schema and two well-documented parameters, the description lacks essential context such as how 'recent' is defined, whether results are paginated, and what status filter options are valid. Given the absence of annotations, the tool description is too sparse for an agent to use reliably.

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%, meaning both parameters (limit, status) are already described in the input schema. The description adds no additional meaning or context 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?

Description explicitly states 'List recent Bitcoin notarization records', providing a specific verb ('List') and resource ('recent Bitcoin notarization records'). This clearly distinguishes it from sibling tools like 'weather_get_notarization_proof' (retrieves a specific proof) and 'weather_notarize_ledger' (creates a notarization).

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?

No guidance on when to use this tool versus alternatives. Siblings such as 'weather_get_notarization_proof' exist for more targeted operations, but the description does not indicate when listing is appropriate or when to prefer a different tool.

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 only states the action but does not disclose idempotency, authentication needs, error states, or side effects like uniqueness constraints on 'name'.

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?

Single sentence, 7 words, no fluff. Could be slightly longer to add necessary context without becoming 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?

Despite having an output schema, the description does not explain return values. For a create tool, it should mention what is returned (e.g., coupon ID). Also lacks guidance on uniqueness of 'name' and default values.

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 high (86%), so baseline is 3. The description adds minimal parameter context ('operator-owned') beyond the schema, but does not compensate for the uncovered 14%.

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 'Create', the resource 'discount coupon', and the qualifier 'operator-owned'. It distinguishes from sibling tools like weather_update_coupon, weather_delete_coupon, and weather_list_coupons.

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?

No guidance on when to use this tool versus alternatives (e.g., update, delete, list). Does not mention prerequisites or constraints.

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 behavioral transparency burden. It discloses the operator-only restriction, background nature, long confirmation time, and zero cost. These are key behavioral traits. It does not describe failure modes or status checking, but the sibling 'weather_get_notarization_proof' likely covers that.

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 consists of three concise, front-loaded sentences. The first sentence captures the core action, the second adds access and timing context, and the third clarifies cost. Every sentence adds value with no 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?

Given no parameters and presence of an output schema (context indicates it exists), the description adequately covers what the tool does and its behavioral characteristics. It could mention the output or how results are returned, but the output schema likely fills that gap. The description is complete for an operator-only background task.

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 schema coverage is 100%. The description adds no parameter information, which is appropriate since none exist. The baseline for 0 parameters is 4, and the description meets that standard.

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 'Build a Merkle tree of all patron balances and submit the root to Bitcoin via OpenTimestamps,' which is a specific verb+resource. It distinguishes from sibling tools, as none of the listed siblings perform this ledger notarization function.

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 clear context: 'Operator-only background task. Bitcoin confirmation takes 1-6 hours. Free — no credits required.' This informs when and by whom the tool should be used, and sets expectations about duration and cost. It does not explicitly exclude alternative tools, but given the uniqueness of the task, further guidance is unnecessary.

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 only states the tool is 'Free' and describes the ecosystem, but fails to mention whether it is read-only, requires authentication, or any side effects. This is insufficient for an agent to assess risks.

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 extremely concise at six words, with no redundant information. It is front-loaded with the core action and resource, making it efficient for quick comprehension.

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 presence of an output schema, the description need not explain return values. However, the tool is simple but the description is too sparse for the overall context. It does not clarify what 'the Oracle' is or what constitutes the 'DPYC ecosystem', leaving ambiguity. A bit more context would 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?

The tool has zero parameters, and the input schema is empty. With 100% schema coverage, the description does not need to elucidate parameters. The additional context ('via the Oracle', 'Free') provides value beyond the schema, explaining the tool's operation and cost.

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 'describe' and the resource 'DPYC ecosystem via the Oracle', which sets a distinct purpose from sibling tools that focus on weather data, accounts, or balances. The phrase 'via the Oracle' adds some context, though it could be more specific about what aspects of the ecosystem are described.

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 no guidance on when to use this tool versus alternatives. The mention of 'Free' hints at no cost, but there is no comparison with similar tools like weather_oracle_network_advisory or weather_oracle_how_to_join. Agents are left to infer usage 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?

No annotations provided; the description only adds 'Free,' which may hint at no cost but does not disclose side effects, rate limits, or read-only nature. The verb 'Get' implies idempotence, but the description is minimal.

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

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

Extremely concise single sentence that is front-loaded and contains no unnecessary words.

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 brevity, the description covers the core purpose. Output schema exists to explain return values. Could expand on what 'DPYC certification' means, but not required for basic use.

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 applies. The schema coverage is 100%, and the description adds nothing about parameters, which is acceptable.

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 and resource: 'Get the current DPYC certification tax rate.' It clearly distinguishes from sibling tools like account or balance checkers.

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?

No guidance on when to use this tool versus alternatives, or any prerequisites or exclusions. The description only states the action without 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?

No annotations are provided, so the description carries full burden. It states 'Free' implying no cost, but does not disclose required permissions, rate limits, or whether it is read-only. The minimal disclosure is insufficient for a tool with no annotations.

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 extremely concise at one sentence. It is front-loaded with the core action. However, it could include more context (e.g., what DPYC means) without becoming verbose. It earns its place but leaves room for improvement.

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 parameterless tool with an output schema, the description is largely complete. It explains the core function. It does not elaborate on output schema content, but that is not required. The tool is simple so the description suffices.

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?

There are zero parameters, and the schema coverage is 100%. The description does not need to add parameter information. The baseline score of 4 is appropriate since the schema fully handles parameter definitions.

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 'Get' and resource 'DPYC onboarding instructions from the Oracle'. It distinguishes from sibling tools focused on accounts, balances, and other topics. However, the acronym 'DPYC' is not explained, which could be unclear to some agents.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or alternative tools. The agent has no context for making selection decisions.

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. The description only mentions it's 'free' but does not disclose any behavioral traits like rate limits, idempotency, or side effects. For a read-only lookup, this is insufficient.

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?

Very concise single sentence with no wasted words. Could include more structured details but is not 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?

Despite having output schema, the description does not explain what data is returned or typical use cases. It is too minimal for a tool with only one parameter.

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 0%. The description mentions 'by npub' but does not explain what npub is or any format expectations. Adds minimal value 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?

The description clearly states the action 'look up', the resource 'DPYC community member', and the lookup method 'by npub'. It distinguishes itself from siblings as no other tool mentions member lookup.

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?

No guidance on when to use this tool versus alternatives. No prerequisites, exclusions, or context provided.

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 must disclose behavioral traits. It mentions 'Free' (implying no cost) but does not state that it is read-only, whether authentication is needed, or any side effects. For a tool with zero annotations, this lacks depth.

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 sentence with no extraneous information. Every word is necessary and adds value, making it highly 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 tool has no parameters and an output schema exists, so the description need not explain return values. The core purpose is clearly communicated. Minor gap: no mention of the advisory's time range or severity, but given the tool's simplicity, this is acceptable.

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?

There are zero parameters and schema coverage is 100% (trivially). The description does not need to add parameter information. Baseline for zero parameters is 4, and the description provides the context that the tool is free.

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 'Get', the resource 'active network advisories', and the source 'from the Oracle'. It immediately distinguishes this tool from siblings like weather_forecast or weather_current by specifying 'advisories', which no other tool name contains. The addition of 'Free' provides extra context.

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?

No guidance on when to use this tool versus alternatives or when not to use it. There is no mention of prerequisites, filters, or exclusions. With many sibling tools, explicit usage guidelines would be beneficial.

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?

Describes the trust model (no nsec held, signature as authorization) and that it relays to public relays. Lacks details on error behavior, idempotency, or rate limits. With no annotations, description carries full burden but remains incomplete.

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?

Four sentences, front-loaded with purpose, followed by necessary technical explanation. No redundant or irrelevant content.

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?

Covers the essential aspects for a publish tool: action, trust model, and process. Output schema exists, so return details are not required. Slightly lacking in failure mode description.

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% but description adds valuable context: explains signature verification and authorization flow beyond schema descriptions. Adds just enough extra 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?

Clearly states it publishes a client-signed kind-0 profile for an npub. Distinguishes from sibling 'weather_get_nostr_profile' by specifying publishing vs. retrieval.

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?

Implies usage when a client-signed event is ready, but lacks explicit when-not or alternative suggestions. Context is clear enough from the description and sibling 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?

No annotations are provided, so the description must convey behavior. It states the tool creates a Lightning invoice, requires proof of npub, and that calling it is free. This provides sufficient transparency for the agent to understand side effects.

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 long, front-loaded with the core purpose, and every sentence provides essential information (invoice creation, payment process, proof requirement, free usage). No wasted words.

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?

With an output schema present, the description doesn't need to explain return values. It covers the purchase flow, prerequisites (dpop_token), and post-call step (check_payment). This is complete for a payment creation 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 coverage is 100%, but the description adds critical details for the dpop_token parameter: it must be raw JSON of a kind-27235 Nostr event with specific formatting constraints, which is far more helpful than the schema alone.

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 'Buy credits via Bitcoin Lightning', which clearly states the action and resource. It distinguishes itself from siblings like weather_check_balance and weather_check_payment by focusing on purchasing.

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 explains the flow: create invoice, pay, then call check_payment. It also notes the requirement of npub ownership proof. While it doesn't explicitly list when not to use, the context is clear for a purchase tool.

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 details behavior: deterministic one-shot retrieval, draining only the rendezvous relay, deleting wrong DMs, accepting the first match, and returning 'courier_not_found' if none match. It also describes the alternative credential_card path. However, it doesn't explicitly state that messages are deleted (a destructive side effect), which would earn 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 well-structured with paragraphs and bullet points, front-loading the main purpose. Every sentence adds value, though the detailed drain process could be slightly more concise. Overall, it is efficient and clear.

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 (4 parameters, side effects) and the presence of an output schema (not shown), the description covers the flow, conditional paths, and result types. It mentions 'courier_not_found' and the reinitialization of the payment processor on success. It is complete enough for an agent to understand the tool's full behavior.

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 100% coverage, so the baseline is 3. The description adds meaning: it explains dpop_token as the 'session phrase' from request_credential_channel, clarifies that credential_card bypasses the relay drain, and notes that service must match the earlier request. This extra context justifies a 4.

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: 'Pick up credentials from the Secure Courier' and completes the CREDENTIAL-DELIVERY flow. It differentiates from the sibling 'receive_npub_proof' by mentioning it as the ownership-proof counterpart, making the tool's role distinct.

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 instructs when to call: 'Call this only after the user confirms they have replied.' It also warns against polling, looping, or retrying. While it doesn't explicitly compare to sibling alternatives beyond the counterpart mention, the guidance is clear and actionable.

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 fully discloses behavioral traits: it drains only the pinned rendezvous relay, stops at the first matching DM, deletes and NACKs mismatched DMs without revealing the expected phrase, and explains the token handling and storage. The non-deterministic outcome if called too early is also noted.

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 informative but somewhat lengthy. It includes necessary details without redundancy, and key instructions are front-loaded. However, it could be slightly more concise by removing minor clarifications that could be inferred from context.

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 of the flow and the presence of an output schema (assumed adequate), the description covers the essential aspects: purpose, prerequisites, behavior, and return value. It explains the proof mechanism and token lifecycle sufficiently for an AI agent to use 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?

Although the input schema covers both parameters and provides descriptions, the description adds value by clarifying the relational context: 'dpop_token' is the value returned by 'request_npub_proof' and must be remembered, and 'patron_npub' is the patron's npub. This contextual linkage enhances understanding beyond the schema alone.

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 receives npub ownership confirmation and completes the npub-OWNERSHIP-PROOF flow. It distinguishes itself from the sibling tool 'receive_credentials' by specifying it is the credential-delivery counterpart. The verb 'receive' and resource 'npub ownership proof' are specific and unambiguous.

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?

Explicit usage instructions are provided: 'Call this only after the user confirms they have replied.' It warns against polling, looping, or retrying, and explains the one-shot deterministic nature. The conditions for successful execution are clearly stated, including the requirement for the user's reply to be present.

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 key behaviors: validation, recording, auto-apply discount, idempotency, and zero cost. It also notes the requirement for npub. No contradictions or omissions.

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 brief (5 sentences) with a clear front-loaded purpose. Every sentence adds value, covering action, validation, effects, cost, and idempotency. No redundant or vague statements.

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 coupon redemption tool with an output schema, the description covers all essential aspects: how it works, prerequisites, side effects (auto-apply discount), and idempotency. It is sufficient for an agent to use correctly without additional information.

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 explains 'code' as the operator-shared coupon name and 'npub' as required proof. The optional dpop_token is not described, but it has a default and is less critical. Given 0% schema coverage, the description adds meaningful context.

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 that the tool claims a coupon by code, with specific actions: lookup, validation, and recording. It distinguishes from sibling coupon tools (mint, delete, update, list) by focusing on redemption and auto-application of discounts.

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 explicitly states when to use (claim a coupon) and prerequisites (npub). It mentions idempotency and the free nature. However, it does not explicitly contrast with alternatives or state when not to use, slightly reducing clarity.

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 description carries full burden. It discloses behavioral traits: costs a small fee, requires npub for attribution, report is public and not verified, and returns either issue details or an unconfigured situation. This is thorough for a reporting 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?

Description is well-structured: starts with purpose, then details prerequisites, costs, and returns. Every sentence adds value. Slightly longer than necessary but remains clear. Appropriate for a non-trivial tool with authentication and cost implications.

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 annotations but presence of output schema (context signal says true), description covers prerequisites, cost, attribution, public nature, failure mode, and return information. For a reporting tool with 5 parameters, it provides sufficient guidance for safe use.

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% (all 5 parameters described in schema). Description adds meaning beyond schema: npub is 'author of record', dpop_token requires specific format and constraints (kind-27235, u tag with tool name, 60s validity), title and body are summarized, tool_name is optional. This additional context helps the agent use parameters correctly.

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 files a field report as a GitHub issue about tool metadata or responses. It uses specific verbs ('File a field report') and identifies the resource ('GitHub issue on the operator's repo'). No sibling tool offers similar functionality, ensuring no confusion.

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 explicitly states when to use: when tool metadata or response is wrong/confusing. It explains costs, public nature, and attribution via npub. Also covers failure mode (unconfigured, no charge). Lacks explicit exclusions or alternatives, but siblings are unrelated, so the guidance 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 fully discloses behavioral traits: it requires proof of npub control, resolves MCP endpoints, mints ownership proof, and delivers MCP-to-MCP. It also explains that the request is recorded as pending and awaiting Authority owner approval.

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 and well-structured: one paragraph with clear front-loading of purpose, followed by necessary details. Every sentence adds value, with no redundant or verbose language.

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, the description is comprehensive. It explains the initiation, restrictions, and expected outcome, and references how to check progress via a sibling tool. The presence of an output schema means return values are covered elsewhere.

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 baseline is 3. The description adds no additional meaning to the parameters beyond what the schema's descriptions provide. It focuses on the overall process rather than individual parameter semantics.

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: to ask an Authority to adopt the operator. It uses specific verbs like 'ask', 'adopt', and describes the deferred process, effectively distinguishing from sibling 'weather_adoption_status' which polls progress.

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 restricts usage to the operator and mentions the need for proof of npub control. It also advises polling 'adoption_status' for progress, providing clear context for when to use this tool and what to do after.

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. Discloses that the flow is human-in-the-loop, sends a welcome DM requiring manual reply, and that receive_credentials calls destructively drain the relay mailbox. Warns against polling or retrying.

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?

Description is concise at 8 sentences, each adding value. Structured with purpose, comparison, caveat, flow detail, and explicit instructions. No fluff or 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?

Covers all necessary aspects for a credential-delivery tool with human-in-the-loop: what it does, when to use alternative, post-call actions, and warning about destructive drain. Output schema exists to handle return value 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 coverage is 100% with existing descriptions indicating 'Required' and source tools. The description does not add significant meaning beyond the schema; both parameters are already well-documented in the input 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 purpose: 'Open a Secure Courier channel for credential delivery.' It specifies the resource (credential channel) and action (open), and distinguishes from sibling tool 'request_npub_proof' by contrasting 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?

Explicitly states when to use this tool vs alternatives: 'To merely prove you control an npub, use request_npub_proof instead.' Also advises checking service_status for dynamic/OAuth2 services. Provides clear post-call instructions: 'After calling this tool, STOP and tell the user what to do. Wait for the user to confirm...'

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 behavioral traits: human-in-the-loop flow, destructive drain of relay mailbox, dpop_token return, and non-persistence across restarts.

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?

Front-loaded with purpose, well-structured with sections, every sentence adds value. No wasted words.

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?

Covers purpose, usage, behavior, lifecycle, return value, and parameter semantics comprehensively. Nothing missing for a tool with this complexity, no annotations, and an 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?

Schema coverage is 100% (baseline 3), but the description adds significant context: 'reason' shown in DM, 'verify_at' one-time code matching, and 'patron_npub' required nature.

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 requests npub ownership proof via Nostr DM, and distinguishes from sibling tool 'request_credential_channel' by explicitly stating what it does NOT do.

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 (when a call returns proof_required), when not to (not for delivering service secrets), and provides alternatives ('request_credential_channel'). Includes lifecycle 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?

No annotations are provided, so the description fully discloses the destructive behavior (erasing all models), the initialization process, and the returned model. It also notes the access restriction. Slightly more detail about potential side effects could push it to 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, each earning its place: first sentence states the purpose, second explains the process, third notes the restriction, and fourth implies the return. It is front-loaded and efficiently conveys 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 tool's complexity (destructive reset with auth) and that an output schema exists, the description covers behavior, restriction, return value, and necessary prerequisites. No further details are needed for an AI agent to invoke it 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?

The sole parameter dpop_token is not explained in the description, and schema coverage is 0%. While the description mentions 'requires proof (nsec-signed)', it does not connect this to the parameter, leaving ambiguity about how to provide the proof. The description adds limited semantic value for the 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 states the tool erases all pricing models and restores a viable default, with specific details about initialization. It distinguishes itself from siblings like weather_get_pricing_model and weather_set_pricing_model by being a reset/reinitialize 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 specifies that the tool is restricted to operators and requires a signed proof, providing clear context for when to use. However, it does not explicitly compare with alternative tools like weather_set_pricing_model for partial updates.

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 discloses idempotency and operator restriction. However, it does not detail failure modes, side effects beyond crediting, or rate limits. Adequate but not exhaustive.

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?

Four well-structured paragraphs, front-loaded with the main action. Every sentence adds value, no fluff. High signal-to-noise ratio.

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 recovery tool with 3 required params and an output schema, the description covers purpose, use cases, restrictions, and idempotency. Sufficient for an agent to decide and invoke 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 100%, so baseline is 3. The description adds context (operator-only dpop_token, idempotency) but does not significantly expand on the schema's parameter descriptions. Adequate.

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 'Credit a patron's ledger from a BTCPay-settled invoice' with a specific verb and resource. It distinguishes from siblings like weather_purchase_credits (normal flow) and weather_check_payment (payment check), making its unique role obvious.

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 restricts usage to the operator, lists concrete use cases (cold-start vault races, delivery hiccups, etc.), and tells patrons to escalate. Does not explicitly state when not to use, but the restriction and context imply exceptional situations only.

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 discloses idempotency (using CREATE TABLE IF NOT EXISTS), harmlessness, return of per-step results, inline error message surfacing, and restriction to operator with nsec-signed proof. This provides good behavioral transparency, though it does not explain the dpop_token parameter's role in behavior.

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 with several sentences, front-loading the purpose and then adding details. It could be slightly more concise but is well-structured and readable.

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 purpose, usage context, behavior, and restrictions. However, it omits any explanation of the dpop_token parameter, which is a gap. Given an output schema exists (though not shown) and only one optional parameter, the description is mostly complete but lacks parameter clarity.

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 does not mention the single parameter dpop_token at all, nor explain its purpose or effect. With 0% schema description coverage, the description adds no value beyond the raw schema, leaving the agent without guidance on this 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 states the tool re-runs ensure_schema() on every NeonVault the operator uses, and specifies it's a diagnostic/recovery tool for persistent 4xx errors from the Neon HTTP SQL API. The verb and resource are specific, and no sibling tool appears to have a similar purpose.

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: when the Neon HTTP SQL API returns persistent 4xx errors and schema or grants are suspected. It does not explicitly exclude other scenarios or mention alternatives, but the context is clear and sufficient for the intended use case.

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 must convey all behavioral traits. It only states it is free and checks health, but omits details like whether it is read-only, any authentication needs, rate limits, or side effects. The transparency is minimal.

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

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

The description is extremely concise with two short sentences. The first clearly states the purpose; the second adds 'Free.', which is relevant but could be integrated. No waste, but could be slightly more precise.

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 zero parameters and an output schema, the description is minimally adequate. It states the core function but lacks context about prerequisites, rate limits, or how the output is structured (though output schema covers that). Leaves gaps for an agent.

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 zero parameters, so schema description coverage is 100%. The description adds no parameter information, but none is needed. Baseline for 0 parameters is 4.

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 the health and configuration of the service, using the verb 'check' and a specific resource. This distinguishes it from sibling tools like weather_current or weather_forecast, which serve different purposes.

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 no guidance on when to use this tool versus alternatives. For example, it does not compare with weather_session_status or clarify scenarios where a health check is appropriate.

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 explains states and failure modes, including retry advice and availability of free tools. It implies read-only behavior but does not explicitly state no side effects, missing a slight transparency opportunity.

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 lengthy but well-structured with bullet points for lifecycle states. Every sentence adds value; it is front-loaded with the purpose. Could be slightly more concise, but clarity justifies 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 an output schema exists (not shown), the description explains return values adequately via state enumeration and guidance. It covers all states and actionable next steps, though exact response shape is not detailed.

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 the schema already explains the optional patron_npub parameter well. The tool description adds no extra parameter details, but the schema suffices; baseline 3 applies.

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 states 'Check operator readiness' and details lifecycle states, clearly distinguishing this tool from siblings that handle other weather-related operations.

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?

Provides explicit guidance per lifecycle state (e.g., 'Proceed with tool calls' for ready, 'Try a tool call' for warming_up, and instructions to not retry for misconfigured and quota_exceeded, including alternatives like repairing or upgrading). It also notes prerequisites (e.g., register_operator first for not_registered).

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 explicitly states the critical behavior: a valid Schnorr-signed proof is required to prove operator status. This is a key behavioral trait that is not captured elsewhere. However, it does not describe other behaviors such as success/failure responses, side effects, or reversibility.

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

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

The description is only two sentences, with the primary action front-loaded in the first sentence. Every word earns its place: the verb 'Set' and resource 'active pricing model' are immediately clear, and the second sentence provides critical auth context without fluff.

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 presence of an output schema (although not detailed) and the important auth requirement disclosure, the description covers the most critical aspect. However, it lacks details on parameter semantics (what 'model_json' should contain, how to pass the proof via 'dpop_token') and does not set expectations about return values or possible errors. A more complete description would include these to support safe 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 input schema has 0% description coverage, meaning the description must compensate by explaining parameters. The description mentions 'model_json' implicitly (the pricing model being set) but does not clarify its format or expected content. The 'dpop_token' parameter is not even mentioned, despite its likely role in the proof requirement. The description adds almost no value 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 action: 'Set the active pricing model.' It also immediately adds the restriction 'RESTRICTED to operator,' which helps distinguish this mutation tool from read-only siblings like 'weather_get_pricing_model' and even from 'weather_reset_pricing_model' (which likely performs a different 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 specifies that the tool is restricted to an operator and requires a valid proof. However, it does not provide guidance on when to use this tool versus alternatives (e.g., using 'weather_get_pricing_model' to read current model first) or when not to use it (e.g., if not operator). The restrictions are mentioned but not framed as explicit usage guidelines.

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 patch semantics, cap-clearing behavior, renaming with survival of redemption rows, and operator restriction. Lacks some details like validation rules but sufficient for basic understanding.

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?

Extremely concise: 4 sentences, no fluff. Each sentence adds value: purpose, usage tip, behavioral note, restriction. Perfectly 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?

Despite having output schema, the description fails to cover most parameters and behavior in depth. With 10 parameters and no schema descriptions, the description is incomplete for an agent to use correctly without guessing.

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 0%, so description must compensate. It only explains clear_uses_per_patron and clear_total_uses, leaving 8 parameters (e.g., dpop_token, valid_from, discount_percent) unexplained. Does not meet the need for a tool with 10 parameters.

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 'Patch a coupon's editable fields', using a specific verb and resource. It distinguishes from siblings like weather_delete_coupon and weather_mint_coupon through the patching concept and mentions renaming the code as allowed.

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?

Provides explicit guidance: 'Pass only the fields you want to change' and explains how to set caps to unlimited via boolean flags. Also notes restricted to operator with proof, implying who can use it.

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 fully owns behavioral disclosure. It reveals the merge behavior ('without touching the others'), side-effect context (courier reply destroys omitted fields), the never-echoed value, and authentication requirements (nsec-signed kind-27235 or cached dpop_token phrase). No contradictions exist.

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 composed of three short paragraphs, each with a distinct purpose: purpose, merge/contrast logic, and auth/restriction context. Every sentence adds essential information without redundancy or filler, matching the tool's complexity.

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 mutating nature, restricted access, and the presence of an output schema, the description is fully complete. It covers the merge semantics, destruction caveat of alternatives, value privacy, and authentication requirements, leaving no critical contextual gaps.

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% for all three parameters, so the baseline is 3. The description adds a concrete example field name ('btcpay_api_key') and overall purpose, but does not need to compensate for schema gaps. It does not provide additional per-parameter semantics beyond what the schema already states.

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: 'Add or update a single operator secret field.' It clearly distinguishes from siblings like weather_update_patron_credential and weather_get_patron_credential_fields by emphasizing 'operator' and the field-level scope, reinforced by the analogy 'field-level counterpart to re-delivering the whole bundle.'

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: 'rotate one secret' without restating unchanged fields, contrasting with courier bundle delivery. It also gives exclusion criteria: 'RESTRICTED to the operator' and 'patron proofs are rejected,' preventing misuse by non-operators.

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 full burden. It discloses that it is a write to a sensitive credential vault, requires proof of npub ownership, and merges without affecting other fields. It does not detail auth beyond npub proof 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 five sentences, each adding distinct information: action, merge behavior, examples, cost, and requirement. It is front-loaded with the main purpose and contains no extraneous content.

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 (4 required params, no nested objects, output schema exists), the description covers what the tool does, when to use it, and key behavioral notes. It does not discuss error handling or conflict resolution, but is largely sufficient.

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%, baseline 3. The description adds value by explaining the merge behavior ('Merges into existing stored credentials without affecting other fields') and providing usage context, which goes beyond the schema parameter 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 clearly states 'Add or update a single patron credential field,' specifying the verb and resource. Among sibling tools like 'weather_delete_patron_credential' and 'weather_get_patron_credential_fields', this differentiation is 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 provides usage context with examples: 'Useful for setting an account identifier after OAuth, changing a default brain, etc.' and notes it is free. However, it lacks explicit when-not-to-use or direct comparisons to sibling alternatives.

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