tollbooth-sample

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

With no annotations provided, the description takes on full behavioral disclosure. It reveals that the tool is free (no credits consumed), requires proof of npub ownership to prevent scraping, and returns specific data. This adds valuable transparency beyond the raw schema.

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

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

The description is concise (5 sentences) and front-loaded with the primary purpose. Every sentence 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?

Given that an output schema exists, the description does not need to detail return values. It sufficiently covers purpose, cost, authentication requirement, and differentiation from related tools, making it complete for its complexity.

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

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

Schema coverage is 100%, and the parameter descriptions in the schema are already explicit. The tool description adds no new semantic information about the parameters beyond what is 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?

Description clearly states the tool generates a patron's account statement, listing specific contents (purchase history, credit tranches, usage breakdown, daily logs) and explicitly distinguishes it from the operator's authority tax balance, which differentiates it from siblings like weather_check_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 notes that it is free and requires proof of npub ownership, providing some usage context. However, 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 discloses cost (1 api_sat per call) and a verification step (debit_or_deny) before cost. It does not mention idempotency or side effects, but for a read-like generation tool, this is adequate.

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 concise sentences, front-loaded with purpose, then features, cost, and verification. 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 key aspects: purpose, output components, cost, and verification. It does not mention output format details (likely in output schema) or potential limitations, but is sufficiently complete for the tool's complexity.

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

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

Schema coverage is 100% and description does not add significant meaning beyond what the schema already provides. It reiterates the parameters but lacks additional context like example or constraints.

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 generates a visual SVG infographic of an account statement, differentiating it from the sibling tool weather_account_statement which presumably returns raw data. It specifies the output format and components.

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 visual representation by stating it returns the same data as account_statement but as a graphic. It does not explicitly state when not to use or provide comprehensive alternatives beyond one sibling, but the context is clear.

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

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

No annotations provided, so description carries full burden. Mentions 'Free' and 'Polls...' implying external network call, but does not explicitly state read-only nature or potential side effects beyond polling.

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

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

Three short sentences, each serving a purpose: purpose, cost, behavior. No 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?

Covers key aspects: what status values to expect (pending/approved/rejected/provisioned), that it polls an authority, and that it's free. Lacks error handling or prerequisite info, but output schema likely covers return structure.

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. Describes 'at a chosen Authority' linking to authority_npub, but does not explain dpop_token (optional with default), leaving its purpose unclear.

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?

Specifies the verb 'Check' and the resource 'adoption-request status' for a specific operator and authority. Clearly distinguishes from sibling tools like weather_request_adoption by targeting status checking.

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?

States when to use: to check status at a chosen authority. Implicitly derives from sibling tools that it's used after requesting adoption, but lacks explicit when-not-to-use or alternative references.

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 cover behavioral traits. It states the return value (balance) and consequences of zero balance, but does not explicitly declare the operation as read-only or non-destructive. The note 'Free' hints at no cost but lacks full transparency.

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

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

The description is concise at four sentences, with the purpose stated first. Every sentence adds value, and there is 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?

For a simple check tool with no parameters and an output schema, the description is complete. It explains the balance's purpose and the actions required when it reaches zero, covering the essential context.

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 no parameters, so schema coverage is 100%. The baseline for zero parameters is 4. The description adds no parameter info because none exist, but it does explain the meaning of the returned value, which is 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 the tool checks the operator's tax balance at the Authority and specifies what the balance is used for (certifying patron credit purchases). It distinguishes from patron balance and is specific to this operator's funding, differentiating it from sibling tools like weather_check_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 explains when to use the tool (to check the balance) and what happens when it reaches zero, implicitly guiding the operator to call purchase_credits. It does not explicitly list alternatives or when not to use, but the context is clear.

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

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

No annotations provided, so description carries full burden. It discloses that the tool is free ('Free — no credits required') and requires proof of npub ownership. It does not describe error conditions but the output schema exists. No contradiction with 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 concise (three short paragraphs), each sentence adds value: purpose, differentiation, usage conditions. No 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 and full parameter documentation, the description covers purpose, usage guidelines, and key behavioral traits (free, auth). It is complete for an agent to understand and use the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add new parameter information beyond what the schema already provides, but it contextualizes the dpop_token requirement. The 'Free' note is not parameter-specific.

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 a patron's credit balance at this operator' and clarifies the specific type of balance. It distinguishes from the sibling authority_check_balance tool, ensuring no ambiguity.

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 clearly states when to use this tool (checking patron's spending balance) and when to use the alternative (authority_check_balance for operator's authority balance). It also notes the requirement for proof of npub ownership.

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 discloses that the tool is free, requires proof of npub ownership to prevent front-running, and implies read-only status check. Lacks explicit statement on side effects or return behavior, but sufficiently covers key behavioral traits.

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 with essential information front-loaded. Three short sentences, no redundancy, 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?

Description fully covers when and how to use the tool given the presence of an output schema. It addresses prerequisites, cost, and rationale, making it complete for the intended use case.

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 parameter descriptions. The description adds minimal extra meaning; it only reiterates that invoice_id comes from purchase_credits and dpop_token is a signed event. Given high 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 checks payment status of a Lightning invoice using a specific verb and resource. It differentiates from siblings by specifying it is called after paying the invoice from 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?

Explicitly states when to call ('after paying the invoice from purchase_credits'), mentions it is free, and explains the proof of npub ownership requirement, effectively guiding the agent on prerequisites and 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?

Without annotations, the description must disclose behavioral traits. It states the tool is free and shows cost details, but does not mention idempotency, authorization requirements, or side effects. The read-only nature is plausible but not explicit.

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

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

Two sentences, front-loaded with the core purpose. No fluff or redundancy. 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 presence of an output schema, the description need not detail return values. However, it omits any mention of how parameters like npub or dpop_token are used, and does not explain the output schema's role. Adequate but not comprehensive.

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

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

The description adds no information about parameters. Schema coverage is 50% (tool_id and tool_kwargs have descriptions; npub and dpop_token do not). The description does not clarify default values or usage, failing to compensate for the schema gaps.

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: 'Preview the effective cost of a tool call.' It specifies what it shows (base cost, constraint effects) and distinguishes itself from sibling tools focused on account, balance, or coupon 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?

The description implies usage context (before making a tool call) but provides no explicit guidance on when to use versus alternatives like 'weather_get_pricing_model'. No exclusions or when-not-to-use are 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?

With no annotations, the description fully covers behavioral traits: it states 'Free, no side effects — does not evict the cache or touch relays,' confirming the tool is non-destructive and safe. 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?

The description is extremely concise (3 sentences) and front-loaded, with the first sentence stating the core purpose. 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 tool's simplicity, good schema coverage, and the presence of an output schema, the description provides adequate context: use case, safety profile, and analogy. It is complete enough for the 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?

Schema description coverage is 100%, and the schema already describes both parameters well. The description does not add significant extra meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Check' and the resource 'whether a previously-cached dpop_token is still valid.' It distinguishes itself from siblings by contrasting with check_oauth_status and specifying the npub-proof flow, making its purpose 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?

The description provides clear usage context: 'a calling agent can ask "will my next paid call accept this dpop_token?" before burning credits on a guaranteed failure.' It implies when to use but does not explicitly mention when not to use or name specific alternatives among siblings.

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

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

No annotations provided, and the description only lists return fields (temperature, wind speed, weather code). Fails to disclose authentication requirements (npub parameter), rate limits, error handling, or other behavioral traits.

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

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

Two concise sentences with no extraneous information. Front-loaded with the core purpose.

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?

Output schema exists so return values are covered. However, the description lacks usage guidelines and does not mention that npub is required for billing, which is part of the input schema. Adequate but with clear 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?

Description does not add meaning beyond the input schema; schema coverage is high (75%) so baseline 3 is appropriate. Parameters are adequately described in 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 'Get current weather conditions for a location' using a specific verb and resource, and the word '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?

No guidance on when to use this tool versus alternatives such as weather_forecast or weather_historical. Lacks any 'when-not' or context for selection.

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?

Since no annotations are provided, the description carries the full burden. It discloses cascading behavior, the no-op effect on chain steps referencing the deleted coupon, and warning handling. This goes beyond a simple 'delete' statement and adds essential behavioral context.

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 three sentences, with the main action upfront. It avoids unnecessary words and includes key behavioral notes. Slightly more structure (e.g., separating usage from behavior) could improve readability, but it is well-organized.

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 (deletion with cascading) and the presence of an output schema (so return values need not be detailed), the description covers purpose, side effects, and access restrictions. However, it omits prerequisites, error handling, and explanation of 'proof,' leaving some gaps that the agent may need to infer.

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 parameter descriptions are missing. The tool description does not explain the parameters (coupon_id and dpop_token) nor relate them to the 'proof' requirement. This is a critical gap: the agent lacks guidance on what the parameters are and how to use them.

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 action: 'Delete a coupon.' This is a specific verb and resource, and it distinguishes the tool from siblings like weather_update_coupon, weather_mint_coupon, or weather_redeem_coupon. The cascading effect and restriction are additional clarifying details.

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 that the tool is 'RESTRICTED to operator — requires proof,' which provides explicit guidance on who can use it and under what conditions. It also implies use when deletion with cascading is desired. However, it does not explicitly compare to alternatives like weather_forget_coupon or state when not to use this tool.

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

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

No annotations provided, so the description carries the burden. It states the tool is free, requires proof of ownership, and is a write to a sensitive vault. It does not disclose rate limits, reversibility, or potential side effects beyond removal. Adequate but not comprehensive.

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

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

The description is succinct with two core sentences and one clarifying line. It is front-loaded with the purpose and avoids redundancy. 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 (single field delete), the description covers key aspects: purpose, auth, cost. An output schema exists, so return values need not be explained. Could mention idempotency or error conditions, but it is sufficiently complete for the use case.

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%, baseline 3. The description adds no new detail beyond the schema: it restates that 'field' is the credential field to remove and that dpop_token provides ownership proof. No extra parameter semantics are provided.

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 removes a single patron credential field, using specific verbs 'Remove' and 'Deletes'. It distinguishes from sibling tools like weather_forget_credentials (bulk) and weather_update_patron_credential by emphasizing single field deletion without affecting others.

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

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

The description indicates when to use: to delete one credential field. It mentions it is a write operation requiring proof of npub ownership, implying it should not be used for read operations. However, it does not explicitly contrast with alternatives like weather_forget_credentials for bulk deletion.

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 does not disclose behavioral traits such as authentication requirements (though 'npub' param suggests it), rate limits, idempotency, or side effects. The description only states what the tool returns, not how it behaves.

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: first states purpose, second details outputs. Front-loaded with essential information, 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 tool has 5 parameters and an output schema. The description provides the core output details (daily temps, precipitation, range) but lacks specifics like units or format. Given the presence of an output schema, the description is moderately complete but could be slightly richer for a forecast tool.

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

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

Schema description coverage is 80% (4/5 params have descriptions). The description adds context about outputs but does not elaborate on parameter semantics beyond the schema. The 'npub' parameter's role as authentication for credit billing is in the schema but not in the description, so the description adds minimal value.

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

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

The description clearly states the verb 'Get', the resource 'multi-day weather forecast', and the scope 'for a location'. It specifies outputs ('daily high/low temperatures and precipitation for 1-16 days'), which distinguishes it from sibling tools like 'weather_current' (single day) 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?

The description implies usage for multi-day forecasts but does not explicitly guide when to use this tool versus alternatives like 'weather_current' or 'weather_historical'. No when-not-to-use or alternative recommendations are 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 exist; description adds crucial behavioral context: coupon still exists, re-redeem possible, requires npub proof. Does not cover idempotency or failure modes.

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 plus a one-line note. 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?

Covers purpose, behavior, and usage constraints. Lacks parameter descriptions but output schema exists and overall complexity is low.

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?

0% schema coverage; description only mentions 'npub' in free note but provides no meaning for coupon_id or dpop_token. Users must infer parameter roles from 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?

Clear verb 'Remove a coupon from this patron's redemption list', specifies exact resource and distinguishes from destructive deletion 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?

States it's cosmetic only and allows re-redeem, implying non-destructive use. Provides context about npub proof but lacks explicit when-not-to-use or alternative references.

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 carries the burden. It declares the operation is destructive ('as destructive as a write') and requires npub ownership proof, which are critical. However, it does not disclose idempotency, error states, or what happens if credentials don't exist, leaving gaps in transparency.

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

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

Three succinct sentences front-load the action, provide context, and end with a critical caution. Every sentence earns its place; no 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 (not shown but stated), the description appropriately omits return value details. It covers the operation's purpose, parameter usage, and destructive nature. However, for a sensitive deletion tool, it could mention error behavior or prerequisites (e.g., credentials must exist). Still, it is mostly complete.

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

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

Schema coverage is 100%, but the description adds value by explaining how to use the 'npub' parameter differently for operator vs patron credentials. The schema description alone is generic; the description provides the necessary nuance. For service and dpop_token, the schema is sufficient, so the description complements well.

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 vaulted credentials for a specific service and npub, and distinguishes operator vs patron npubs. However, it does not explicitly differentiate from sibling tools like weather_delete_patron_credential or weather_forget_coupon, so purpose is clear but not fully distinguished.

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 which npub to use (operator's own vs patron's) and emphasizes required proof of ownership. But it lacks explicit instructions on when to use this tool instead of related tools (e.g., weather_delete_patron_credential) and does not mention prerequisites or side effects beyond the dpop_token.

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?

Specifies that data is public and latest, returns fields or empty profile. No annotations provided, so description carries burden; lacks disclosure on rate limits or staleness.

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 covering purpose, cost, authentication, and output fields with 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?

With output schema present, description completes by listing return fields. Could mention error handling but sufficient for a simple read 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?

Only one parameter (npub) is implied in the description as the subject, adding value over schema with 0% description coverage. Parameter is self-explanatory.

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 'Read an npub's public Nostr profile' with specific verb and resource, distinguishing it from write tools like 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?

Mentions it's free and requires no authentication, indicating when to use. Does not explicitly state when not to use but 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 provided, the description carries full burden. It discloses the main function (proof generation) but omits behavioral traits like authentication needs, error handling, or side effects (e.g., whether it modifies state). Adequate but 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 a single, concise sentence that immediately conveys the tool's function. No wasted words; front-loaded with key information.

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

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

For a simple two-parameter tool with an output schema, the description is largely complete. However, it lacks context about preconditions (e.g., notarization must exist) or error cases, which would enhance completeness.

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

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

Schema coverage is 100%, so the description adds no additional meaning beyond the schema. The schema already documents npub and notarization_id clearly. 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 generates a Merkle inclusion proof linking a patron's balance to a Bitcoin-notarized snapshot. It uses a specific verb ('generate') and resource ('Merkle inclusion proof'), distinguishing it from siblings like 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 implies the tool is used when a Merkle proof is needed, but it does not explicitly state when to use it versus alternatives like weather_check_proof_status or weather_notarize_ledger. No exclusions or prerequisites are 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 should fully disclose behavioral traits. It only states 'Report' and 'Free', which imply a read-only operation but are not explicit. There is no mention of side effects, idempotency, or authentication requirements.

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

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

The description is three sentences with no wasted words. It front-loads the main purpose, adds details about what is shown, and provides a sibling alternative--all in a compact form.

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 (no parameters, output schema exists), the description covers the main usage and output. It explains what the report shows and how to switch to a related tool. A minor gap is that it does not mention any prerequisites or account requirements.

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 no parameters and 100% schema description coverage (trivially), so the baseline is 4. The description does not need to add parameter info, and it doesn't--this 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 uses the verb 'report' and the resource 'operator's configuration readiness', clearly stating the tool's purpose. It distinguishes from the sibling weather_get_patron_onboarding_status by specifying 'operator' vs 'patron-level credential 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 explicitly tells when to use an alternative tool: 'For patron-level credential status, use get_patron_onboarding_status instead.' This provides clear guidance on scope. However, it does not give other contextual cues like 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?

Since no annotations are provided, the description carries full disclosure burden. It reveals that values are never exposed, the operation is free, requires proof of ownership, and the list is sensitive. This goes beyond basic read-only behavior by highlighting security implications.

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 adding value: the first states the core function, the second clarifies output, the third confirms no cost, the fourth explains security rationale. No redundancy or unnecessary 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 presence of an output schema and the simple nature of the tool (list field names), the description fully covers all necessary contextual information: what it returns, what it doesn't return, cost, authentication, and sensitivity.

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 context that dpop_token is used for proof of npub ownership, but does not provide additional semantic details beyond 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 states 'List stored patron credential field names (not values)', which is a specific verb-resource combination. It clearly distinguishes from sibling tools like weather_delete_patron_credential and weather_update_patron_credential by emphasizing that it only returns field names, 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 explicitly says 'use this to verify which fields are configured' and notes that proof of npub ownership is required. It does not mention when not to use this tool or compare to alternatives, but provides sufficient context for its intended 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?

Without annotations, description carries full burden. It discloses behavioral traits: shows configured/missing secrets for set-once services, reports no credentials needed for dynamic services, requires proof of npub ownership due to sensitivity, and notes it is free. Does not mention side effects or rate limits, but sufficiently 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?

Extremely concise: three sentences with zero waste. Front-loaded with main purpose, then details on service types, and authentication requirement. Every sentence earns its place.

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

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

Given existence of output schema, description need not explain return values. It covers the tool's purpose, service categories, authentication requirement, and cost. Complete for a read-like operation with clear behavioral context.

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. Description adds minimal extra meaning beyond schema: it explains dpop_token as proof of ownership, which the schema already states. No significant additional 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?

Description clearly states 'Report a patron's credential readiness for this operator' with specific verb 'Report' and resource 'credential readiness'. Differentiates from sibling tools like weather_get_operator_onboarding_status (operator vs patron) and weather_get_patron_credential_fields (fields vs readiness).

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 context on when to use: for checking credential readiness, distinguishing between set-once and dynamic services. Explains requirement of dpop_token for proof of ownership. However, does not explicitly mention when not to use or compare with closely related tools like weather_get_patron_credential_fields.

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 a key behavioral trait: self-initialization of a scaffold if no model exists. It also mentions 'Free' and 'No economic data from code', covering relevant aspects. 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?

The description is extremely concise with three short sentences, front-loading the purpose and adding essential behavioral info. Every sentence adds value without 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?

Given no parameters and an existing output schema, the description covers the main behavior (self-initialization) and cost ('Free'). It could briefly note idempotency or constant behavior, but is largely complete for a simple getter.

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 parameters with 100% coverage, so the description cannot add parameter semantics beyond the schema. The baseline for 0 parameters is 4, correctly reflecting that no additional info is 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 'Get the active pricing model for this operator' using a specific verb and resource, and the tool name aligns with this purpose. It effectively distinguishes from sibling tools like set/reset by being a retrieval operation.

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

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

The description implies usage by stating the tool retrieves the pricing model, but does not explicitly contrast with sibling tools (e.g., when to use get vs set/reset). The self-initialization behavior provides useful context for when the model is absent.

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 carries full burden. It does not disclose authentication requirements, side effects, rate limits, or billing implications despite parameters like npub and dpop_token hinting at these. Minimal behavioral disclosure.

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

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

Two sentences, no unnecessary words. Information is front-loaded and each part 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?

Description mentions returned data (daily temperature and precipitation) but fails to clarify the purpose of authentication parameters (npub, dpop_token). With output schema existing, return value coverage is adequate, but the description could be more complete regarding input parameter roles.

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 (83%), so the schema already documents most parameters. The description does not add extra meaning beyond what the schema provides. 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 clearly states verb (Get) and resource (historical weather data), specifies location and date range, and lists returned data (daily temperature and precipitation). It distinguishes from sibling tools like weather_current and weather_forecast via the term '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?

No explicit guidance on when to use this tool versus alternatives. The term 'historical' implies usage for past data, but no exclusions or alternatives are mentioned. Given sibling tools exist, this is a gap.

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 explains the behavior: no side effects, free, and that tool_id remains stable while mcp_name changes on rename. It does not cover rate limits or auth, but for a read-only list tool, the transparency 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 concise at five sentences, front-loaded with the main purpose. Each sentence adds value: returns canonical IDs, authoritative source, example use, stability behavior, and no side effects. It is well-structured but not extremely terse.

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 presence of output schema, the description provides complete context: why to use it (authoritative, stable IDs), how it behaves (tool_id stability), and that it has no side effects. It feels fully adequate for an agent to understand when and why to invoke this 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?

There are zero parameters and schema coverage is trivially 100%. The description does not add parameter info, but none is needed. Baseline for zero parameters is 4, and the description fulfills that.

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 returns canonical (tool_id, mcp_name, ...) for every registered tool, establishing a specific verb and resource. It distinguishes itself from other list tools like weather_list_coupons by focusing on tool identity, not other entities.

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 it is the authoritative source for clients needing tool identification and mentions a specific use case (Reconcile UUID-join). It implies use when canonical identities are needed, though it does not explicitly state when not to use it or name alternative tools.

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

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

Without annotations, the description carries full burden and discloses the read-only listing behavior, return contents, and zero cost. It does not mention rate limits or data freshness, but for a simple list tool it's 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?

Two concise sentences plus a line, no wasted words. Purpose and return value are 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?

Low complexity (no params, list operation) and description fully covers what, why, and cost. Output schema exists but is summarized in description. No gaps detected.

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% (empty object), so the description correctly adds that no parameters are needed. Baseline is 4 for zero‑parameter tools.

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' with specific return fields (type, category, description, parameter specs) and context (pricing pipeline). It distinguishes itself from all sibling tools by being the only constraint-listing tool.

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?

Mentions 'Free — no credits required' which implies low-cost usage, but does not explicitly state when to use or exclude alternatives. No sibling tool directly competes, so guidance is adequate but not exhaustive.

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 results are newest first and includes a progress bar field, but does not mention idempotency, side effects, or pagination limits. It adds some value but lacks full transparency.

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

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

The description is two sentences long, front-loading the main action and ordering. Every sentence adds value: purpose, data format, and access restriction. 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 the output schema exists, return values are not needed. The description covers purpose, ordering, and key fields, but lacks explanation of the dpop_token parameter and potential pagination. Adequate but with a notable 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 input schema has one parameter (dpop_token) with 0% description coverage. The description does not explain this parameter at all, despite mentioning 'requires proof'. This is a critical gap for tool invocation.

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 every coupon this operator has minted (newest first)', providing a specific verb+resource combination. The scope is well-defined as operator-specific, distinguishing it from sibling tools like weather_list_my_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 notes 'RESTRICTED to operator — requires proof', which gives a clear constraint on who should use it. Though it doesn't explicitly mention alternative tools, the restriction implies that non-operators should use weather_list_my_coupons.

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

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

No annotations are provided, so the description carries the burden. It discloses that results include status field and requires npub proof, but does not mention if the operation is read-only, error handling, 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?

Two sentences, front-loaded with action and resource, 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?

Description covers return format and auth requirements, but lacks details on the dpop_token parameter and error scenarios. With output schema present but not shown, it is adequate but incomplete.

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 description must compensate. Only 'npub' is mentioned in context; the 'dpop_token' parameter is completely unexplained.

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 coupons redeemed by a patron on this operator, specifying it returns both active and exhausted redemptions with status field. This distinguishes it from sibling tools like 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?

The description mentions 'requires proof of npub' which provides usage context, but lacks explicit guidance on when to use this tool over alternatives like weather_list_coupons or weather_redeem_coupon.

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 all behavioral traits. It only states the operation is a list but does not mention read-only nature, rate limits, authentication requirements, or pagination behavior. The existing schema describes parameters but not system-level 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 a single clear sentence with no fluff. Every word is necessary, and it is front-loaded.

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

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

Given the high schema coverage and existence of an output schema, the description is minimally viable. However, it lacks context about the scope of 'recent' and default ordering, which could confuse 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?

Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional meaning beyond what the schema provides, meeting the 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?

The description clearly states the verb 'List' and the resource 'recent Bitcoin notarization records', distinguishing it from the sibling tool 'weather_get_notarization_proof' which retrieves a single record. However, it lacks specificity on what 'recent' means.

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 explicit guidance on when to use this tool versus alternatives. It implies use for listing notarizations but does not mention exclusions or related tools like 'weather_get_notarization_proof'.

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 (create) but fails to disclose important behavioral traits such as authentication requirements, potential side effects (e.g., overwriting existing coupons), idempotency, or error conditions. The description is too minimal for safe autonomous execution.

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 is very concise, but lacks structured information like bullet points or usage context. While not verbose, the brevity sacrifices completeness. Still, 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 existence of an output schema (context signals indicate present) and rich parameter descriptions, the overall description still misses critical context: expected output, typical workflow, constraints (e.g., uniqueness of name), and integration with other coupon tools. The agent lacks essential information to use the tool effectively.

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 no additional meaning beyond the schema's parameter descriptions. It does not explain parameter relationships or provide examples, but schema already covers most fields adequately.

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 creates a new operator-owned discount coupon. The verb 'create' is specific, and 'operator-owned' distinguishes from possible patron-owned coupons. It clearly differentiates from sibling tools (delete, update, list, redeem, etc.).

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 like weather_update_coupon or weather_redeem_coupon. No prerequisites, exclusions, or context provided. The agent must infer usage from the name alone.

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 key behaviors: it's a background task, takes 1-6 hours, and is free (no credits). This is sufficient behavioral transparency for an operation-triggering 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?

Three sentences, each adding value: the action, the operator-only restriction, the time and cost details. No redundant 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?

Given no parameters and an output schema present, the description covers the main aspects: action, audience, timing, cost. Could mention the nature of the output (e.g., a notarization ID), but the output schema likely handles that.

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 (100% schema coverage), so baseline score of 4 applies. Description adds no parameter info, but none is 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?

Description clearly states verb 'Build' and 'submit', resource 'Merkle tree of all patron balances' and 'root to Bitcoin via OpenTimestamps'. It distinguishes from sibling tools by indicating it is an operator-only background task, which is unique among the listed tools.

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

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

Specifies operator-only usage and that Bitcoin confirmation takes 1-6 hours, implying asynchronous behavior. Does not explicitly state when to use versus alternatives, but the context is clear enough.

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

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

No annotations provided, and description only mentions 'Free.' Does not disclose behavioral traits like read-only nature or 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?

Extremely concise at seven words. Not wasteful, but could benefit from slightly more detail about what the description entails.

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?

Adequate for a zero-parameter tool with output schema; however, description is vague and could elaborate on the 'DPYC ecosystem' or 'Oracle'.

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; baseline score of 4 applies. Description does not add parameter info, but none 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?

Clearly states verb 'Describe' and resource 'DPYC ecosystem via the Oracle'. Distinguishes from sibling tools like weather_check_balance or 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 explicit guidance on when to use vs alternatives. The phrase 'Free.' hints at no cost but doesn't specify use cases or 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 must cover behavioral traits. It only adds 'Free.', but does not disclose if the tool is read-only, requires authentication, or has rate limits. This is insufficient transparency.

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

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

The description is extremely concise: two sentences with no superfluous words. It is front-loaded with the main action and adds the key detail 'Free.' efficiently.

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 and zero parameters, the description is reasonably complete. It states the purpose and adds the 'Free.' context. It does not mention prerequisites, but for a simple getter, 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?

The input schema has zero parameters and 100% schema coverage. Per guidelines, a baseline of 4 applies since there are no parameters to describe.

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 the resource 'the current DPYC certification tax rate'. It uniquely identifies the tool among siblings, as no other sibling mentions tax rate.

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. While it is the only tax rate tool, there is no explicit when/when-not or alternative information.

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 only mentions 'Free' but does not disclose other behavioral traits like read-only nature, authentication needs, or 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 very short with two phrases. However, 'Free.' could be integrated into the first sentence. Still, it is 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 zero parameters and an output schema, the description is minimally adequate. However, it lacks context on what DPYC stands for or what the instructions contain, which could help the 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 tool has zero parameters and the schema coverage is 100%. The description does not need to add parameter information, and 'Free' adds a minor non-parameter detail. Baseline for zero params 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 action (Get), the resource (DPYC onboarding instructions), and the source (from the Oracle). It distinguishes from sibling tools like 'weather_oracle_about' which are about general oracle info.

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 includes 'Free' implying no cost, but lacks explicit guidance on when to use this tool vs alternatives. No context on prerequisites or exclusions is 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 provided, so description carries full burden. Only states 'look up by npub' with no disclosure of read-only nature, return format, side effects, or authorization requirements. Minimal transparency.

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

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

Description is extremely concise (one sentence, 8 words), but this brevity omits critical details. It is front-loaded but lacks necessary information beyond the bare action.

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

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

For a simple lookup with one parameter and an output schema, the description is too sparse. It doesn't explain what is returned (e.g., member details), any preconditions, or the meaning of 'Free'. Incomplete context.

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 'npub' has a 0% schema description coverage. The description adds 'by npub' to clarify its role as identifier, but provides no format, constraints, or example. Minimal added value.

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

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

Description clearly states the tool looks up a DPYC community member by npub. The verb 'look up' and specific resource 'member' make the purpose clear, though it does not explicitly differentiate from sibling lookup tools.

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

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

Description includes 'Free' which hints at no cost, but gives no guidance on when to use this tool vs. alternatives like weather_get_nostr_profile or weather_check_balance. No when-to-use or when-not-to-use 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 relies on 'Get' to imply read-only behavior, but it does not disclose side effects, authentication needs, or limits. The mention of 'Free' hints at cost but not behavioral traits.

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 one concise sentence plus 'Free.' with no wasted words. It is front-loaded and efficient for a simple tool.

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

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

While the output schema exists, the description lacks context about what 'network advisories' entail (e.g., weather network status or operational alerts). For a zero-parameter tool, it is minimally complete but could benefit from additional context.

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 in the schema, so the description has no parameter details to add. Baseline score of 4 is appropriate given 0 parameters and full schema coverage.

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

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

The description specifies the verb 'Get' and resource 'active network advisories' from the Oracle, clearly stating the tool's purpose. However, 'network advisories' is somewhat vague, and it does not explicitly differentiate from sibling tools like 'weather_service_status' or 'weather_oracle_about'.

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 such as 'weather_service_status' for service status or 'weather_oracle_get_tax_rate' for tax info. The context 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?

No annotations provided, so description carries full burden. It discloses key behaviors: wheel never holds nsec, frontend signs, verification, relay to public relays, free. This is thorough and sets correct expectations.

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

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

Three sentences, front-loaded with purpose, then behavioral details, then summary. No redundant 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 2 parameters with 100% schema coverage and an output schema, the description explains the process flow and constraints (signing, relay). It lacks error scenarios but is largely complete.

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

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

Schema coverage is 100%, baseline 3. Description adds context: npub must match signature, signed_event is client-signed kind-0 event. This clarifies the signing requirement beyond 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 the verb 'publish' and the resource 'client-signed kind-0 profile to relays for an npub'. It distinguishes from siblings like weather_get_nostr_profile by specifying the action and the signed nature.

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 when to use it (frontend signs, passes signed event) and what not to do (wheel holds no nsec, no proof token). It provides context but does not explicitly name alternative tools.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool creates a Lightning invoice, requires a dpop_token for authentication, and is free to call ('Free — no credits required to call'). It does not detail timeout or expiration, but overall 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 with four sentences. The first sentence immediately states the purpose. It is front-loaded with the key action, followed by workflow and additional notes. 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?

With an output schema present, the description does not need to explain return values. It covers the workflow and prerequisites. It mentions that the invoice is created and to use check_payment afterward, which is sufficient. Could note that the invoice details are returned, but overall 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?

All three parameters are fully described in the input schema (100% coverage). The description adds context for npub and dpop_token ('Proof of npub ownership is required'), but this is not significantly 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 tool's purpose: 'Buy credits via Bitcoin Lightning.' It specifies the action (buy), resource (credits), and payment method (Lightning). This distinguishes it from sibling tools like weather_check_balance or weather_check_payment.

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

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

The description explains when to use this tool (to purchase credits) and prerequisites: 'Proof of npub ownership is required so credits land in the correct ledger.' It also instructs to 'call check_payment to confirm' after payment. It does not explicitly mention when not to use or 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?

Despite no annotations, the description fully discloses behavioral traits: deterministic one-shot retrieval, draining only the pinned relay, deleting wrong DMs and NACK'ing sender, accepting first matching DM, returning courier_not_found if none match, and redeeming credential_card bypassing relay. Also mentions reinitialization without server restart.

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 detailed but well-structured with clear sections and bullet points. Every sentence adds value. Could be slightly more concise, but the structure aids readability.

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

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

Given no annotations and a relatively complex tool with 4 parameters and an output schema, the description is thorough. It covers the entire flow, error handling, alternative credential_card path, and post-success action. No gaps identified.

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 schema already describes parameters. However, the description adds meaning by explaining the role of dpop_token as 'session phrase', sender_npub as 'the npub that sent the credentials', service matching the request, and credential_card as an alternative path that bypasses relay. Adds integration context 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 it picks up credentials from the Secure Courier and completes the CREDENTIAL-DELIVERY flow, distinguishing itself from the sibling receive_npub_proof by specifying it is the ownership-proof counterpart. The verb 'pick up' and resource 'credentials' are specific.

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 'Call this only after the user confirms they have replied.' Provides a clear procedure: one-shot retrieval, naming response with parameters, and drain behavior. Also includes prohibitions: 'Do NOT poll, loop, or retry.'

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 fully discloses behavior: drains only pinned relay, deletes mismatched DMs, stores proof as hash, and requires app to remember dpop_token. No hidden 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?

Description is detailed but all sentences add value. Structured with paragraphs and bold emphasis on critical usage instructions. Slightly long but justified by 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?

Explains the full flow, return value (dpop_token), and post-call requirements. Output schema exists to cover return format, so description is 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?

Both parameters have schema descriptions (100% coverage). Description adds context: dpop_token comes from request_npub_proof, and explains the naming convention for the response.

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 the tool receives npub ownership confirmation and completes the npub-OWNERSHIP-PROOF flow. Distinguishes from sibling tool 'receive_credentials' by naming it as the credential-delivery counterpart.

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 usage instructions: call only after user confirms reply, deterministic one-shot retrieval, naming convention, and what happens if called early. Also warns against polling, looping, or retrying.

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 key traits: free, requires npub proof, idempotent, validates window and cap, auto-applies discount. With no annotations, this is good but could detail error behavior (e.g., expired coupon).

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

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

Concise at 4 sentences, front-loaded with main action. No fluff, but slightly more detail on dpop_token would not hurt.

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 core behavior (validation, recording, auto-apply, idempotency). Has output schema so return values not needed. Missing edge cases, but otherwise 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?

Explains `code` and `npub` adequately, but `dpop_token` is not mentioned. Schema coverage is 0%, so description must compensate; it partially covers 2 of 3 params.

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 claims a coupon by its code/name, validates conditions, and records redemption. Distinguishes from sibling coupon tools (e.g., mint, delete) via specific action and mention of auto-applying 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?

Describes when to use (to claim a coupon) but lacks explicit when-not-to-use or alternatives among the many sibling coupon tools (e.g., mint, update). No guidance on choosing this over other coupon-related tools.

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

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

With no annotations, the description carries full burden. It discloses key behaviors: requires proof, resolves MCP endpoint, mints ownership proof, delivers request MCP-to-MCP, and records as pending. It stops short of detailing error conditions or rate limits, but overall is informative.

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 paragraph that front-loads the main purpose and follows with procedural details. It is not overly long but could be slightly more concise by merging some sentences.

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 process. It explains the adoption request lifecycle and directs to polling 'adoption_status'. Minor gaps in error handling do not detract significantly.

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 value by linking 'dpop_token' to the required proof and explaining the overall adoption flow, providing context beyond 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 the tool's action: 'Ask a chosen Authority to adopt this operator (deferred courtship).' It provides detailed context on the process, differentiating it from siblings like 'weather_adoption_status' which is for checking 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 ('RESTRICTED to the operator') and explains the prerequisite (proof of npub control). It also links to 'adoption_status' for progress. However, it does not explicitly contrast with alternatives or provide when-not-to-use scenarios.

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 human-in-the-loop flow, no polling, destructive nature of receive_credentials, and the need to stop and wait for user confirmation.

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?

Well-structured with front-loaded purpose, but slightly verbose with some redundancy (e.g., 'This is the CREDENTIAL-DELIVERY flow'). Still efficiently conveys necessary 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?

Comprehensive given complexity: covers purpose, alternatives, workflow, behavioral constraints, and integration with receive_credentials. Output schema exists so return value explanation not needed.

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 3. Description adds minimal context beyond schema (e.g., source of service parameter), but does not add significant new 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 opens a Secure Courier channel for credential delivery, differentiating from request_npub_proof and mentioning dynamic OAuth2 exceptions.

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 specifies when to use (credential delivery) and when not (proof_required errors, dynamic OAuth2), and provides workflow instructions including calling receive_credentials afterward.

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 human-in-the-loop, destructive mailbox drain on receive, expiration lifecycle, and non-persistence of dpop_token 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?

Well-structured with bold headers and logical flow, but slightly verbose; still each 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?

Complete coverage of workflow, return value, lifecycle, and interaction with sibling tools; no gaps given the tool's complexity.

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

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

Only one parameter with 100% schema coverage; description does not add meaningful detail beyond what the schema already provides for patron_npub.

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 requests npub ownership proof via Nostr DM, distinguishes it from credential delivery, and specifies it proves ownership only.

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 (when proof_required returned), when not to (use request_credential_channel instead), and provides step-by-step workflow with warnings against polling/retrying.

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 destructive action (delete all models) and the subsequent initialization process, plus returns the new model. With no annotations, it carries the transparency burden and adequately discloses the key 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?

Four sentences front-load the main action, then explain process and restrictions. No superfluous content; each 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?

Covers purpose, process, restriction, and output. While it does not elaborate on irreversibility or handling of dpop_token, it is adequately complete for a destructive tool with 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 0% and description does not mention the single param 'dpop_token', failing to add meaning beyond its existence. The token's purpose is only vaguely implied via 'requires proof (nsec-signed)'.

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 'Erase all pricing models and restore a viable default,' providing a clear verb and resource. This distinctively separates it from siblings like set_pricing_model or get_pricing_model.

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?

Clearly indicates the tool is 'RESTRICTED to operator' and requires proof, implying usage only by authorized users. However, it does not explicitly contrast with alternatives or specify 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?

Discloses idempotency and behavior when invoice already credited (returns success with credits_granted=0). Mentions access restriction. Missing explicit statement about state modification, but overall good given 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?

Efficient structure: core purpose, restriction, use cases, idempotency. Every sentence earns its place. Front-loaded with key 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?

Covers purpose, restrictions, use cases, behavioral traits. Given high schema coverage and existence of output schema, 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 has 100% coverage, but description adds value for dpop_token (type of event, operator-only). For invoice_id and patron_npub, context is provided. This goes 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 the tool credits a patron's ledger from a BTCPay-settled invoice. It specifies the verb 'Credit', the resource 'patron's ledger', and the condition. It distinguishes from siblings by noting it's restricted to operator and addresses specific failure scenarios.

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 the operator' and provides concrete use cases: cold-start vault races, ncred delivery hiccups, patrons closing Top-Off sheets before settle. It also tells patrons to escalate to operator support, clarifying 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, description provides key behavioral traits: idempotent, uses CREATE TABLE IF NOT EXISTS, returns per-step result, surfaces Neon error inline, restricted to operator. Could mention if any side effects 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?

Well-structured with three focused paragraphs. Front-loads the core purpose. Every sentence adds value, with clear separation of usage, behavior, and restrictions.

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 only one parameter, the description covers purpose, usage, idempotency, error handling, and restrictions. However, the missing parameter explanation is a notable gap, slightly reducing completeness.

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

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

Schema coverage is 0%, and the description does not explain the sole parameter `dpop_token` (default empty). No guidance on its purpose or usage, leaving the agent without necessary 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?

Clearly states it re-runs `ensure_schema()` on every NeonVault as a diagnostic/recovery tool for persistent 4xx errors. Distinguishes from sibling tools by its recovery focus and operator restriction.

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 (persistent 4xx errors, suspect schema/grants) and that it's idempotent and harmless. Mentions restricted operator access with nsec proof. Lacks explicit alternatives or when-not-to-use but context is clear.

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

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

No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as whether it is read-only, requires authentication, or has rate limits. The description is too minimal to provide meaningful transparency.

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

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

The description is very concise with one sentence and an additional word 'Free'. It is front-loaded, but the word 'Free' seems slightly extraneous. Still, it's 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 the tool's simplicity (no parameters, output schema exists), the description is adequate but could be more complete by specifying what health aspects are checked or what configuration details are returned. The presence of output schema reduces the need to describe return values, but additional context would help.

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 schema coverage is perfect. Baseline is 4, and description adds no extra meaning since there are no parameters to elaborate on.

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 health and configuration of the service, which is a specific verb+resource. It distinguishes itself from sibling tools like weather_forecast or weather_account_statement by being a generic health check.

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 vs alternatives. There is no comparative information about when to choose weather_service_status over other diagnostic tools like weather_session_status or weather_oracle_about.

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 carries full burden. It discloses that the tool is free, returns lifecycle state and guidance, and explains behavior for each state. It does not mention side effects, but the nature of checking readiness implies no destructive actions.

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 clear and well-structured with bullet points for lifecycle states. It could be slightly more concise, but the information is front-loaded and each 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 has an output schema (not shown), the description explains return values (lifecycle state and guidance) and provides explicit next steps for each state. It is complete for a status 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?

The schema covers 100% of parameters (only one optional parameter), and the description adds value by explaining that supplying patron_npub includes an 'upstream_oauth' block for proactive token refresh.

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 'Check' and the resource 'operator readiness', and explains lifecycle states. It distinguishes itself from siblings like weather_service_status by focusing on operator's lifecycle and guidance.

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 when to use the tool: to check operator readiness and get guidance. It provides explicit actions for each lifecycle state, but does not contrast with siblings like weather_service_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?

Without annotations, the description adds value by disclosing access restrictions and authentication proof requirements. However, it does not explain error behavior, whether the operation is reversible, or effects on existing settings.

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, front-loaded with the main action. No redundant information. Every word serves a purpose.

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 restricted admin action with authentication, the description lacks critical details: expected format of 'model_json', error handling, and operational behavior (e.g., immediate effect, persistence).

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 parameter descriptions in the description, despite 0% schema coverage. The 'model_json' parameter remains undefined (expected format/structure), and 'dpop_token' is not explained.

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

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

The description clearly states the action ('Set the active pricing model') and differentiates from sibling tools like 'weather_get_pricing_model' (read-only) and 'weather_reset_pricing_model' (reset vs 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?

Explicitly states that the tool is restricted to the operator and requires a valid proof. This provides clear usage context, though it doesn't explicitly list when-not-to-use or alternatives.

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

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

Describes key behavior: renaming code preserves patron rows, use of clear flags to set unlimited values, and operator restriction requiring proof. No annotations provided, so description carries full burden. Lacks detail on reversibility of other fields.

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?

Five sentences, each adding unique value. Front-loaded with main action, then special cases, then restriction. 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 core patching behavior, clearing mechanics, and restriction. Output schema exists, so return values need not be explained. Could mention that coupon_id is required, but schema already shows that.

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?

Adds meaning for clear_uses_per_patron and clear_total_uses parameters, and explains renaming. However, with 0% schema coverage, does not cover all 10 parameters (e.g., coupon_id, total_uses, valid_from). Partial compensation.

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 'Patch a coupon's editable fields,' specifying verb and resource. Distinguishes from siblings like weather_delete_coupon and weather_mint_coupon by focusing on patching rather than deleting or creating.

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 to 'Pass only the fields you want to change' and explains how to clear fields with boolean flags. Notes operator restriction, implying when not to use. Could explicitly mention alternatives among siblings.

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

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

No annotations exist, so description carries full burden. It discloses that this is a write to a sensitive credential vault, requires proof of ownership, and is free. This is adequate behavioral context.

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: 5 sentences, no redundancy, front-loaded with the core action. 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 (no need to describe return values) and the simple update nature, the description covers purpose, guidelines, transparency, and parameter behavior completely.

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. Description adds value by explaining the merge semantics for the field parameter, which goes beyond the schema's 'The credential field name to set.'

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' with a specific verb and resource. It mentions merging behavior and differentiates from siblings like weather_delete_patron_credential and weather_get_patron_credential_fields.

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?

Gives concrete examples ('setting an account identifier after OAuth, changing a default brain') and mentions the prerequisite of proof of npub ownership. Lacks explicit when-not-to-use, but provides sufficient context.

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