tollbooth-authority-northamerica

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

No annotations provided; description carries full burden. It discloses that the tool is free (no credits), read-only (returns data), and requires authentication (dpop_token). Provides specific constraints on the token format and freshness, adding value beyond basic safety.

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

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

Description is three concise paragraphs: purpose, content listing, and additional notes (cost, prerequisite). Every sentence adds value with no redundancy. Slightly longer than necessary but 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?

Output schema exists, so detailed return values are not required. Description adequately covers what the tool does, what it returns, and critical prerequisites. For a statement tool with 3 parameters and a known output shape, it is sufficiently complete.

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

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

Schema coverage is 100% with good descriptions. The description adds context on the dpop_token's role as proof of ownership and its strict requirements (kind-27235, proper tags, freshness). This goes beyond the schema's description, compensating for the parameter's complexity.

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 generates a patron's account statement, listing specific data included (purchase history, credit tranches, per-tool usage, daily logs). Distinguishes it from 'authority_account_statement_infographic' implicitly by focusing on raw data rather than visual representation. 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?

Explicitly states it is free and requires proof of npub ownership via dpop_token, guiding the agent on prerequisites. However, it does not explicitly mention when not to use this tool or suggest alternatives like the infographic sibling, limiting completeness.

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 cost (1 api_sat) and proof verification (debit_or_deny), which are behaviors beyond the schema. However, it does not mention failure modes, rate limits, or additional side effects. The transparency is 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 two sentences, front-loaded with purpose, and contains no unnecessary words. Every sentence adds value: the first defines the tool, the second details output components and cost. Highly concise and well-structured.

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

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

Given the presence of an output schema, the description does not need to explain return values. It describes the visual components, cost, and proof verification. It is mostly complete, though it could mention error handling or prerequisites. Overall, it provides sufficient context for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description does not add new information about parameters beyond what is in the schema. Baseline score of 3 is appropriate as the description provides no extra semantic value for parameters.

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

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

The description clearly states the tool generates a visual SVG infographic of an account statement, distinguishing it from the sibling authority_account_statement tool by specifying it returns the same data as SVG. The verb 'Generate' and resource 'SVG infographic' are specific and unambiguous.

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

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

The description implies that if you need raw data, use account_statement; if you need a visual, use this. It provides context about cost and proof verification, but does not explicitly state when not to use it or compare with alternatives. The usage context is clear but lacks 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 were provided, so the description carries full burden. It mentions 'Polls' but does not explain polling behavior, timeouts, or authentication requirements (dpop_token parameter is unexplained). It also does not state whether it is read-only or has 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 brief with two sentences. The main purpose is front-loaded. No redundant information, though the word 'Free.' could be integrated more naturally.

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 lacks prerequisites (e.g., must have submitted an adoption request), does not explain the polling nature, and does not clarify how this tool relates to siblings like 'authority_get_adoption_status'. The output schema exists but the description does not use it to explain return values.

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

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

Schema description coverage is 0%, yet the description does not explain the parameters. 'authority_npub' is required but its format or purpose is not described. 'dpop_token' is mentioned in schema but not in description.

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

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

The description clearly states the action ('check') and resource ('adoption-request status') and lists possible statuses. However, it does not differentiate from the sibling tool 'authority_get_adoption_status', which may cause confusion.

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

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

The description mentions 'Free.' and 'Polls', implying it's a query operation. It does not specify when to use this tool versus alternatives like 'authority_get_adoption_status' or provide exclusions.

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

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

With no annotations, the description must disclose behavioral traits. It mentions approval and provisioning, and notes the same consent and effect as register_operator. However, it lacks details on side effects, permissions, or output 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?

Two sentences with no wasted words. First sentence directly states purpose; second sentence elaborates on relationship to sibling. Highly efficient.

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

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

Given the tool has only 2 parameters (fully described in schema), an output schema, and moderate complexity, the description adequately covers usage context. It could mention what the tool returns, but 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?

Schema coverage is 100%, so baseline is 3. The description adds context that 'authority_proof' is the same as in register_operator, which provides marginal value beyond the schema's parameter descriptions.

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

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

The description clearly states 'Approve a pending request and provision the operator,' using a specific verb and resource. It distinguishes itself from the sibling 'authority_register_operator' by framing it as a deferred 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?

It explains this tool is used after review, contrasting with register_operator for immediate consent. Implicitly indicates when to use but does not explicitly state when not to use or list alternatives beyond the one sibling.

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 that the paid_tool decorator handles fee debit and stores cost, and that no recomputation is needed. This provides useful side-effect and performance information. It could further clarify auth or error handling.

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

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

The description is three sentences, each adding distinct value: purpose, behavioral note, caller context. No redundancy or fluff.

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

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

Given the presence of an output schema, the description adequately covers purpose, caller, and side effects. It could be improved by mentioning error conditions or typical usage steps, 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 description coverage is 67%. The description restates schema info for npub and amount_sats but adds nothing for dpop_token. It adds no new meaning beyond the schema, so a 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 certifies a purchase order and returns a Schnorr-signed Nostr event certificate. It specifies the resource (purchase order) and the output, and distinguishes from siblings like authority_purchase_credits by noting it is called after a purchase.

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

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

The description specifies that the tool is called by operator MCP servers when a patron purchases credits, providing clear context for invocation. It does not, however, explicitly state when not to use it or list 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 must carry the full behavioral burden. It fails to disclose side effects (e.g., activation consequences), error states for failed approval, or idempotency. Important traits like 'check' and 'activate' imply state changes but are not elaborated.

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

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

The description is a single sentence with an informative prefix ('Step 3/3 of Authority onboarding'), making it front-loaded and concise. However, it sacrifices some behavioral detail for brevity.

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 only one parameter and an output schema exists, the description is minimally adequate. It lacks context on the overall onboarding flow, what 'activate' entails, or error handling, but meets basic completeness for a simple 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 single parameter candidate_npub is fully described in the schema (100% coverage). The description adds no additional semantic context beyond the schema, meeting the baseline expectation.

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

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

The description clearly identifies the tool as Step 3/3 in Authority onboarding, with the specific actions of checking parent approval and activating Authority. This distinguishes it from siblings, which handle other onboarding steps or unrelated 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 positions the tool as Step 3/3, implying it should be used after prior onboarding steps. However, it does not explicitly state prerequisites or alternatives, leaving some ambiguity for agents unfamiliar with the process.

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 fully bears the burden. It discloses that it returns sats available, that zero balance prevents patron top-ups, and that this is a read-only check. It also notes 'Free.', implying no cost. 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?

Four sentences, front-loaded with main purpose, no extraneous information. Each sentence adds value, making it efficient and well-structured.

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

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

Description is complete for a simple check tool: explains balance, its purpose, and the action needed when zero. Output schema likely covers return format, so no gaps.

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

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

No parameters, so baseline is 4. Description adds meaning beyond the empty schema by explaining what the tool checks and the context of the balance.

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 'Check this operator's tax balance at the Authority' and distinguishes from other balances by explicitly noting it is the operator's own funding, not a patron balance. This distinguishes it from sibling tools like authority_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?

Description explains when to use (to check balance for certifying credits) and what to do when balance is zero (call purchase_credits). While it doesn't explicitly state when not to use, the context is clear.

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

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

With no annotations, description conveys non-mutation, free usage, and security requirement for dpop_token. It explains what the balance represents and that no credits are consumed. But does not explicitly state it's read-only or describe 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?

Well-structured with clear sections, front-loads purpose. The confusing sibling reference adds slight noise. Overall efficient given the complexity of dpop_token.

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 balance concept, why dpop_token is needed, and distinguishes from operator balance. With output schema present, not describing return format is acceptable. Almost complete for a simple query.

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

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

Schema coverage is 100%, but description adds significant value: clarifies npub format and gives exhaustive details on dpop_token construction, constraints (not base64, not NIP-98, u tag with exact tool name, content empty, 60s timeliness, random nonce).

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 'Check a patron's credit balance at this operator' with specific verb and resource. Distinguishes from sibling by mentioning operator's own balance should use authority_check_balance, but this reference is confusing since the tool name is the same (likely meaning authority_check_authority_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?

Provides context on when to use (patron balance check) and hints at alternative (operator balance). Mentions requirement of npub ownership proof. However, the sibling tool name is incorrectly stated, reducing clarity.

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

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

No annotations are provided, so the description carries full burden. It implies a read-only operation ('look up'), but does not confirm idempotency, side effects, or behavior for missing npubs.

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 is front-loaded with the key action. However, it omits necessary details, which could be included without verbosity.

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 an output schema exists (not shown), the description does not hint at return values or error conditions. Given the many sibling tools, more context is needed for effective selection and invocation.

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

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

The schema has 0% description coverage for the single parameter 'npub'. The description mentions 'an npub' but does not specify format (e.g., hex, bech32) or constraints, leaving ambiguity for the AI agent.

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

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

The description clearly states the action ('look up') and the resource ('npub in the DPYC community registry'). It distinguishes from sibling tools like authority_get_nostr_profile, but could be more specific about what the lookup returns.

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

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

No guidance is provided on when to use this tool versus alternatives such as authority_oracle_lookup_member. The description does not mention prerequisites or limitations.

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 fully disclose behavior. It reveals that the tool is free (no credits) and requires npub proof for security. However, it does not describe error behavior (e.g., if the invoice doesn't exist or hasn't been paid), idempotency, or rate limits. The disclosure is adequate but lacks depth for a tool with no annotations.

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

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

The description is concise, consisting of three short sentences. It front-loads the purpose and then adds context about free usage and security. There is no fluff, but the 'Call after paying' line could be integrated more smoothly. Overall, it is efficient and well-structured.

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

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

Given that an output schema exists (indicated in context signals), the description does not need to detail return values. It provides essential workflow context (order relative to purchase_credits), cost (free), and security (npub proof). It covers the key aspects for an agent to use the tool correctly, though it omits potential error scenarios.

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 input schema already documents all parameters well. The description adds minimal extra meaning beyond the schema—it ties invoice_id to the purchase_credits workflow and reiterates the npub requirement. It does not elaborate on dpop_token beyond what the schema says. With high coverage, a baseline of 3 is appropriate.

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

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

Description clearly states 'Check the payment status of a Lightning invoice.' The verb 'Check' and resource 'payment status of a Lightning invoice' are specific. It also provides context by saying 'Call after paying the invoice from purchase_credits,' linking it to a specific workflow and distinguishing it from sibling tools like authority_purchase_credits and authority_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?

Explicitly states when to use: 'Call after paying the invoice from purchase_credits.' Also mentions it is free and requires proof of npub ownership to prevent front-running, which guides usage constraints. It does not mention when not to use or provide alternative tools, but the guidance is clear and actionable for an AI agent.

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 is free and shows cost details, but does not explicitly state it is read-only (though 'preview' implies it). No mention of side effects or permissions.

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 short sentences, front-loaded with purpose. Zero waste, efficiently communicates the tool's function and a key behavioral note.

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 need not be described. However, the description is minimal and does not explain the required tool_id parameter or optional tool_kwargs, leaving ambiguity 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 coverage is 50%, but the description adds no explanation for parameters (npub, tool_id, dpop_token, tool_kwargs). It does not elaborate on how to use tool_kwargs for pricing preview, which is necessary for proper 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 that the tool previews the effective cost of a tool call, including base cost and constraint effects. It distinguishes from sibling tools like authority_get_pricing_model, which gets the entire model rather than a specific preview.

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

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

No guidance on when to use this tool versus alternatives (e.g., authority_get_pricing_model). The note 'Free — no credits required' is a behavioral detail but not a usage guideline 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?

No annotations are provided, so the description carries the full burden. It clearly states the tool is free, has no side effects, and does not evict the cache or touch relays. This sufficiently discloses the behavioral impact, though it could elaborate on what constitutes 'validity' for the dpop_token.

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 plus a code reference) and front-loads the core purpose. Every sentence has a clear function: purpose, usage guidance, and behavioral note.

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 does not need to explain return values. It covers the essential behavioral and usage context, and the input schema fully documents the parameters. The description is complete for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'previously-cached dpop_token' which adds some context beyond the schema, but it does not provide additional details for the 'patron_npub' parameter. Overall, the description adds limited extra meaning beyond what the schema already provides.

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 a specific verb ('Check'), identifies the resource ('previously-cached dpop_token'), and states the condition ('still valid'). It also distinguishes itself from the sibling 'check_oauth_status' by naming the alternative flow, making the purpose unmistakable.

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

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

Explicitly tells when to use the tool ('before burning credits on a guaranteed failure') and what not to expect ('Free, no side effects — does not evict the cache or touch relays'). It also references the alternative tool 'check_oauth_status' for 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?

With no annotations, the description must fully disclose behavioral traits. It explains the escalation logic (parent resolved from upstream_authority_npub) and the verification step. However, it does not mention failure modes, side effects, or whether the operation is idempotent, which would be valuable for an agent.

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

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

The description is two sentences, front-loaded with the tool's purpose and step number. It efficiently conveys the core functionality without unnecessary words, though the second sentence is somewhat technical.

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 specialized nature and the existence of an output schema, the description is reasonably complete. It explains the purpose and the parent resolution mechanism. However, it lacks mention of prerequisites or the implications of the escalation, which would improve completeness.

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

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

Schema coverage is 100%, so the input schema already fully documents the single parameter (candidate_npub) with a description. The tool description adds no additional parameter information, so it meets the baseline of 3.

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 role as 'Step 2/3 of Authority onboarding' and specifies the actions: verify candidate DM and escalate to parent Authority. This distinguishes it from sibling tools like authority_check_authority_approval or authority_get_operator_onboarding_status, which serve different purposes.

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

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

The description indicates it is part of a multi-step process ('Step 2/3') but does not explicitly state when to use this tool versus alternatives, nor does it exclude scenarios where it should not be used. Some context is provided, but guidance is minimal.

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, but description discloses cascading deletions, behavior of chain steps becoming no-ops, and access restriction (operator only). Could add more on error handling.

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, front-loaded with main action, then effect details. No redundant 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?

Covers deletion behavior and restrictions, but lacks explanation of dpop_token parameter and does not mention output or error scenarios. Output schema exists but not referenced.

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 0% description coverage; description adds no information about coupon_id or dpop_token. Agent must infer meaning from names only.

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 verb 'Delete' and resource 'coupon', with additional details about cascading effects and orphan references, making it distinct from sibling tools like update_coupon or 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?

Implicitly clear that this is for deletion; mentions restriction to operator with proof, but no explicit contrast with alternatives or when not to use.

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

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

With no annotations, the description carries full burden. It discloses that the operation is a write ('write to the patron's sensitive credential vault'), requires proof of npub ownership, and is free. It does not elaborate on error cases (e.g., field not found) or return behavior, but the output schema is present. Overall, it adds significant behavioral context beyond the 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 very concise: two sentences clearly stating the purpose, scope (single field, free, requires proof). Every sentence adds value, and the structure is front-loaded with the core 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 deletion tool with 3 parameters and an output schema, the description covers the main behavior (delete one field, free, proof required). It is mostly complete but could mention that the field must exist or what happens if it doesn't. The presence of output schema reduces the need to describe return values.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add extra parameter-specific details beyond what the schema already provides for npub, dpop_token, and field. It only repeats the purpose.

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 'Remove a single patron credential field' and 'Deletes one field from stored credentials without affecting other fields.' This clearly specifies the action (delete) and the resource (single field), distinguishing it from siblings like authority_forget_credentials (which likely removes all fields) and authority_update_patron_credential (which modifies 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?

The description implies when to use this tool: to delete a single field without affecting others. However, it does not explicitly mention when not to use it or provide alternatives like authority_forget_credentials for bulk deletion. The lack of explicit exclusions gives a score of 4.

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 that the tool removes an operator and requires two proofs, and explains the risk without authority_proof. However, it does not mention any side effects or what happens to the operator's data after removal.

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, front-loaded with purpose, and uses clear bullet-like enumeration for the proofs. 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?

The description covers prerequisites, security context, and required proofs. An output schema exists, so return values are handled elsewhere. A minor gap is the lack of information about post-removal state.

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 context by explaining the role of 'proof' and 'authority_proof', which is not fully detailed in the schema. However, the parameter 'dpop_token' lacks description both in schema and description, limiting 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?

The description clearly states 'Remove an Operator from the DPYC community registry' using a specific verb and resource, effectively distinguishing it from sibling tools like register_operator and update_operator.

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

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

The description explains the required proofs (proof and authority_proof) and the security implication of missing authority_proof, providing clear context on when to use. However, it does not explicitly state when not to use or mention alternatives.

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

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

With no annotations, the description carries full burden. It explains the cosmetic nature (coupon still exists, re-redeemable) and requires npub proof. This provides useful behavioral context beyond the tool name.

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

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

Three sentences, each earning its place: action, nuance, requirement. Front-loaded with primary purpose. 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?

Given an output schema exists and the tool is simple, the description covers the main effect and constraints. Lacks details on error handling or preconditions (e.g., coupon must exist in list), but overall 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?

Schema coverage is 0%, so description must compensate. It adds meaning for npub ('proof') but does not explain coupon_id or dpop_token. This is insufficient for a tool with three parameters.

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

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

The description clearly states 'Remove a coupon from this patron's redemption list' with the verb 'remove' and resource 'coupon'. It distinguishes from sibling 'authority_delete_coupon' by clarifying this is cosmetic only and the coupon remains valid for re-redeem.

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 context: 'Cosmetic only' implies use when patron wants to hide a coupon without invalidating it, and 'Free — requires proof of npub' gives prerequisite. However, it does not explicitly differentiate from alternatives like authority_delete_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 carries full burden. It states deletion is destructive 'as a write,' but does not disclose consequences of deleting non-existent credentials, reversibility, or potential impact on other operations. More detail would improve 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 sentences: first states purpose, second provides usage distinction, third emphasizes ownership requirement and destructiveness. Every sentence adds value with no redundancy.

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

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

Given the tool has an output schema (not shown), the description need not explain return values. It covers purpose, parameters with clarity, and usage context. For a destructive tool with three required params, this is sufficiently complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning: it distinguishes npub usage for operator vs patron, and provides highly detailed instructions for dpop_token (raw JSON, kind 27235, constraints on tags, content, timing, and recommendation for nonce). This far exceeds schema documentation.

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

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

The description clearly states the verb 'Delete' and the resource 'vaulted credentials for a specific service and npub.' It distinguishes this tool from siblings by specifying it deletes credentials, which is unique among many authority_ tools.

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

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

The description provides explicit context on when to use this tool (for operator vs patron credentials) and emphasizes the need for proof of npub ownership. However, it does not explicitly state when not to use it or compare to alternatives like authority_delete_patron_credential.

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

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

With no annotations provided, the description bears full responsibility. It discloses that the tool is read-only, free, requires no proof, and that the status is not sensitive. This is good behavioral context for a read operation, though error or edge cases are not mentioned.

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 two sentences, front-loading the primary purpose. The second sentence adds useful context about status sensitivity and alternative tool, though the reference to 'its adoption_status tool' is slightly cryptic. Overall, 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?

Given the tool's simplicity (one optional parameter, output schema exists), the description covers the essential aspects: what it does, cost, authentication, and sensitivity. It does not exhaustively list status values but implies them. The mention of an alternative tool adds completeness.

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

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

Schema description coverage is 100%, with the input schema already clearly describing the sole parameter ('the operator npub whose request status to read'). The description adds no additional 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 it reads an operator's adoption-request status, specifying the resource and action. It distinguishes from a similar sibling tool by mentioning that the operator can poll via its own 'adoption_status' tool, though the differentiation is not fully explicit.

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 some context (free, no proof, status not sensitive) and alludes to an alternative tool for operators, but does not explicitly state when to use this tool versus related siblings like authority_adoption_status or authority_check_proof_status. The guidance is implicit rather than direct.

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 present, the description fully takes on the transparency burden. It lists the specific metadata fields returned and mentions the empty profile fallback, which are important behavioral details. It does not mention rate limits or other constraints, but as a read operation, this is acceptable.

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 two sentences; the first clearly states the action and resource, the second adds important constraints and return details. No superfluous content, and the critical information is front-loaded.

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

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

For a simple read operation with an output schema, the description covers the purpose, usage context, return fields, and edge case (empty profile). It is complete and leaves no significant gaps for an AI agent to understand the tool's behavior.

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

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

The input schema has one parameter (npub) with 0% description coverage, meaning the schema provides no semantic hints. The description does not elaborate on the parameter's meaning or format beyond the tool name itself. A brief mention of the expected format (e.g., bech32) would be helpful.

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 ('Read') and the resource ('an npub's public Nostr profile (NIP-01 kind-0 metadata)'), making the tool's purpose unmistakable. It differentiates from sibling tools like 'authority_publish_nostr_profile' by specifying it is a read 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 explicitly states the tool is free and requires no proof, indicating it is appropriate for public data retrieval. However, it does not explicitly mention when not to use it or provide alternatives, though the context implies it's for reading only.

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

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

With no annotations, the description carries full weight. It correctly implies a read-only, idempotent operation (generating a proof), but does not disclose authentication needs, rate limits, or whether the proof is returned directly or stored. The behavior is adequate for a simple query 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?

A single, well-structured sentence that immediately conveys purpose. No redundant or filler content.

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

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

The description is complete for a tool with a full output schema and two well-documented parameters. However, it could benefit from mentioning that the proof is generated upon request and is not precomputed, or that it requires the notarization to have occurred.

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 parameter-level detail beyond what the schema already provides. The mention of 'patron's balance' provides context but does not clarify parameter formats or usage.

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 ('Generate a Merkle inclusion proof') and the resource ('a patron's balance included in a Bitcoin-notarized snapshot'). It distinguishes the tool from siblings, which mostly handle CRUD or other operations, by specifying a unique output (proof).

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 authority_notarize_ledger or authority_check_proof_status. No prerequisites, post-conditions, or exclusions are mentioned, leaving the agent to infer context 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 carries the full burden of behavioral disclosure. It reveals that the tool requires a Schnorr signature for access, which is a significant behavioral trait. However, it does not mention read-only nature, error conditions, or other potential 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 consists of two short sentences that are front-loaded with the purpose and include only essential information. There is no redundancy or unnecessary detail.

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 (though not provided), the description's brief mention of 'Neon URL, schema' may suffice for output understanding. However, the description does not explain the dpop_token parameter or provide broader context on when this configuration retrieval is needed. It is minimally adequate but leaves gaps.

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

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

Schema description coverage is 50% (one of two parameters described in schema). The description does not add any further meaning to the parameters; it does not explain the purpose of dpop_token or clarify how npub is used beyond what is in the schema. Thus, it fails to compensate for the parameter documentation 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 uses a specific verb 'Retrieve' and clearly identifies the resource as 'operator bootstrap configuration (Neon URL, schema)', making the tool's purpose unambiguous. It distinguishes itself from sibling tools, such as those that retrieve other operator-related data, by focusing on bootstrap configuration.

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 'gated by Schnorr signature', providing a security requirement but offering no guidance on when to use this tool versus alternative tools (e.g., authority_operator_status or authority_get_operator_onboarding_status). There is no explicit when-to-use or when-not-to-use advice.

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 behavioral burden. It clearly conveys a read-only report operation, mentions 'Free' (likely indicating no cost), and describes the output. Could be improved by explicit statement of non-destructiveness, but sufficient given 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?

Three concise sentences with no filler. Front-loaded with main purpose, then details, then alternative. Efficient and scannable.

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

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

For a zero-parameter tool with output schema, the description covers all needed: purpose, output content, usage context, and alternative. No gaps given the context signals.

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

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

No parameters exist, so baseline 4 applies. Schema coverage is 100% (vacuous). Description does not need to add parameter details.

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

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

Explicitly states it reports operator configuration readiness, lists what it shows (configured/missing values and how to deliver them). Clearly distinguishes from sibling tool authority_get_patron_onboarding_status by specifying patron-level scope.

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

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

Provides explicit guidance: use this for operator-level readiness, and for patron-level use get_patron_onboarding_status instead. Leaves no ambiguity about when to use which 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, but description details return format (names + delivered_at timestamps with null handling), states 'Free', notes 'Proof of npub ownership required', and warns that the list itself is sensitive. Good 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?

Concise, front-loaded with main purpose, uses clear formatting. Each sentence adds value (return format, auth requirement, sensitivity). 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 only 2 parameters and presence of output schema, description sufficiently covers behavior, return content, auth requirements, and sensitivity. No missing 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 covers both parameters (npub, dpop_token) with descriptions (100% coverage). Description adds context that dpop_token proves npub ownership, which is useful but not critical beyond schema. Baseline 3 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 the tool lists field names (not values), distinguishes from sibling tools like authority_delete_patron_credential by emphasizing its read-only nature and focus on names/timestamps.

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 says 'use this to verify which fields are configured and how old each one is', providing clear context. It implies when not to use (e.g., when values needed) but doesn't explicitly name alternatives; still strong guidance.

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

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

With no annotations provided, the description is the sole source for behavioral traits. It mentions sensitivity and the need for proof of ownership, and states it is 'Free.' However, it does not explicitly confirm that the tool is read-only or describe error/edge-case behaviors. The disclosure is moderate but not fully 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 four sentences long, front-loading the main purpose. Each sentence provides a distinct piece of information: purpose, behavior per service type, cost, and prerequisite. It is well-structured and avoids redundancy, though it could be slightly more concise.

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

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

The description covers the tool's function, service-specific behavior, cost, and a prerequisite. With an output schema present, return values are presumably documented elsewhere. However, it does not explicitly state that the tool is safe and read-only, leaving some behavioral completeness gaps. Given the complexity and absence of annotations, the description is adequate but not exhaustive.

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 already covers both parameters with clear descriptions, achieving 100% coverage. The description adds no additional meaning beyond restating the requirement for dpop_token via 'Proof of npub ownership is required.' Thus, it adds minimal value over the schema.

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

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

The description clearly states the tool's purpose: reporting a patron's credential readiness for the operator. It distinguishes between service types (set-once vs. dynamic/OAuth2) and specifically mentions which secrets are configured vs. missing, making it clear and distinct from sibling tools like authority_get_operator_onboarding_status.

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

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

The description provides clear context on when to use the tool (checking credential readiness before using services) and the prerequisite of dpop_token for proof of ownership. However, it does not explicitly state when not to use it or list alternative tools, though the sibling list implies differentiation.

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 bears full responsibility. It discloses that the call is free, that it auto-initializes a scaffold if no model exists, and that no economic data is derived from code. This goes beyond a simple 'get' description. It could be more explicit about idempotency, but the disclosed behavior 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 extremely concise: two sentences that immediately state the purpose and key behavioral traits. Every word adds value; 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 a simple tool with no parameters and an existing output schema, the description adequately covers the essential context: what it gets, its cost, and initialization behavior. The presence of an output schema means the description does not need to detail return format.

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

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

The input schema has zero parameters with 100% coverage, so the description does not need to elaborate on parameters. Baseline score of 3 is appropriate as no additional value is required.

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 'active pricing model', with the additional qualifier 'for this operator'. It distinguishes itself from sibling tools like authority_set_pricing_model and authority_reset_pricing_model by focusing on retrieval.

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

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

The description provides context on when to use: it mentions self-initialization if no model exists, implying it's safe to call even without a pre-existing model. However, it does not explicitly compare to alternatives or state 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool lists pending requests and requires owner consent. However, it does not explicitly state it is a read-only operation or mention any side effects, pagination, or rate limits. The description adds some context ('Owner queue', 'Pricing Studio') but lacks full behavioral detail.

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

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

The description is extremely concise with two sentences. The first sentence front-loads the purpose and queue context. Every sentence provides essential information 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 the tool has an output schema (not shown), the description does not need to explain return values. It fully covers the tool's scope, access restriction, and usage context, making it complete for an AI agent to understand and invoke correctly.

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

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

Schema coverage is 100% with the single parameter 'authority_proof' having a clear description. The description adds no additional semantic value beyond what the schema provides, maintaining the baseline of 3.

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 'pending operator-adoption requests' specific to the owner queue. It distinguishes from sibling tools like authority_approve_adoption and authority_reject_adoption that handle different actions.

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 Authority owner with consent proof, providing a clear precondition. It also mentions the tool is the review surface for Pricing Studio, giving context. It does not explicitly state when not to use, but the sibling set implies alternatives for other actions.

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 of behavioral disclosure. It discloses it's free with no side effects at the end, and explains what happens in edge cases (unregistered tools appear with registered:false and in the unregistered array; renames change mcp_name but keep tool_id). It explains the diffing behavior against the live wire surface and references issues #174/#175. It doesn't describe output shape beyond the identity fields but discloses the important behavioral traits well.

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

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

The description is front-loaded with the core purpose in the first line, then elaborates on consumer context, edge-case handling, and design rationale. It's a bit verbose with some redundancy—'flag deploy drift instead of silently reporting clean' and 'flag deploy drift instead of silently under-reporting' appear twice for issues #174 and #175, which are near-duplicate statements about the unregistered array. Still, every section earns its place and the structure is logical.

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

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

There's an output schema present, so return values don't need full explanation. The description explains the canonical identity fields, the registered:false flag semantics, the design intent behind stable tool_id across renames, and the wire-surface diffing. For a metadata-listing tool with zero parameters, this is thorough and complete. It could arguably describe the output schema structure slightly more, but the output schema already covers 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?

The tool has 0 parameters with 100% schema coverage a priori (empty object schema), so per the rubric baseline is 4. The description correctly focuses on behavior instead of parameters, which is appropriate since there are no parameters to document. No additional param semantics are 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 this tool returns canonical (tool_id, mcp_name, …) for every tool the wheel exposes. It names the verb (return), resource (canonical identities of tools), and scope (every tool), and distinguishes it from siblings by positioning it as the authoritative identifier source for clients and Reconcile. It explicitly contrasts it against 'name-based UUID derivation, no guessing'.

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 who should use it (any client needing to know how the MCP identifies tools) and the intended consumers (Studio, agents, FE, Reconcile for UUID-join). It explains a specific workflow detail (no name-based UUID derivation, UUID-join against pricing model) that tells an agent when this is the correct tool to select. It clarifies that unregistered entries flag deploy drift, giving clear contextual purpose.

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 the return structure (type, category, description, parameter specs) and notes it is free and no credits required. It does not cover caching, pricing implications, or side effects, but for a read-only list, this is 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?

The description is three sentences, front-loading the primary action in the first sentence. The second sentence adds output details, and the third adds cost info. Every sentence adds value, though the second and third could be merged. Efficient overall.

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 zero-parameter input and presence of an output schema, the description is complete. It explains what is returned and that no credits are consumed. No additional context is necessary for an agent to use this tool correctly.

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

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

The tool has zero parameters and schema description coverage is 100%. Per rubric baseline, score is 4. The description adds no parameter details because there are none, which 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 'List all available constraint types and their parameter schemas', specifying the verb 'list' and the resource 'constraint types'. It identifies the domain 'pricing pipeline', distinguishing it from sibling tools that deal with statements, adoption, or 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 explains what the tool does but does not provide explicit guidance on when to use it versus alternatives or when not to use it. For a simple list tool without parameters, this is adequate but lacks explicit usage direction.

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

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

Reveals ordering and mentions restricted access. Lacks details on error cases, auth details beyond 'proof', or rate limits. With no annotations, description carries the behavioral burden but only partially satisfies it.

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. The second sentence about the Studio progress bar is slightly extraneous but not harmful.

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 simple list tool with an output schema. Missing details like pagination, but overall sufficient given low 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 0% and description does not explain the sole parameter 'dpop_token'. No added meaning beyond the schema; fails to compensate for missing 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?

Clearly states 'List every coupon this operator has minted (newest first)' – specific verb, resource, and scope. Differentiates from siblings like 'authority_list_my_coupons' by specifying operator-level access.

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

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

Explicitly restricts usage to operator with 'requires proof' and states ordering. Does not directly compare with sibling tools, but the restriction implies when to use.

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

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

With no annotations, the description discloses return behavior (active and exhausted redemptions with specific statuses) and cost model (free). It does not mention side effects but the tool appears read-only. This goes beyond minimal 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?

Extremely concise: three sentences with no redundant information. Front-loaded with the core action, followed by return details and a constraint (free, npub required).

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 and return format adequately for a list tool with an existing output schema. However, parameter documentation is missing, and the description does not specify pagination or order, which might be needed for 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 only mentions 'npub' in passing ('requires proof of npub') without explaining its role or the optional 'dpop_token'. Parameters are largely left to inference.

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 lists coupons redeemed by a patron on an operator. The verb 'list' and resource 'coupons' are specific. Differentiates from siblings like 'authority_list_coupons' by scoping to 'this patron'.

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 'requires proof of npub' and that it's free, giving some usage context. However, it does not explicitly contrast with similar sibling tools (e.g., 'authority_list_coupons') or provide when-not-to-use guidance.

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

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

With no annotations, the burden falls on the description. It discloses the tool is a read operation listing operators with a specific error, and notes authorization requirement. It does not detail rate limits or error behaviors, but the output schema may cover return format. The companion reference adds useful 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 two dense sentences, front-loaded with the core purpose. Every sentence adds value, no redundancy. The structure efficiently conveys purpose, restriction, and relation to a sibling tool.

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

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

Given the tool's domain (authority/operator management) and the large sibling set, the description provides sufficient context: what it lists, who can use it, and how it complements a specific sibling. The output schema exists, so return value documentation is not required.

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% (the single parameter is described in the schema). The description does not add any additional meaning beyond what the input schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states it lists operators that reported a Neon-402 (store locked), providing a specific verb-resource pairing. It explicitly distinguishes itself from the companion tool 'network_persistence_health' by noting this is the reactive list versus proactive.

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

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

The description specifies access restriction ('Restricted to the Authority owner') and indicates usage context via the companion comparison ('reactive list' vs. 'proactive per-project compute posture'). It also implies the parameter 'authority_proof' is needed for owner consent, giving clear when-to-use and when-not-to-use guidance.

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

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

No annotations provided, and description is minimal. Doesn't disclose ordering, freshness, or pagination behavior beyond the schema's limit parameter.

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 concise and front-loaded, but could include slightly more context without becoming verbose.

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

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

Adequate for a simple list tool with output schema, but lacks explanation of 'recent' and how this fits with sibling tools.

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

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

Schema description coverage is 100%, so parameters are already well-documented. Description adds no additional meaning.

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

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

Description states a specific verb 'List' and resource 'Bitcoin notarization records', clearly distinguishing from sibling tools like authority_get_notarization_proof that focus on individual proofs.

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 (e.g., authority_get_notarization_proof). Missing context on use cases or prerequisites.

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

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

No annotations exist, so the description must carry the full burden. It only states that the tool creates a coupon, without disclosing authorization needs, uniqueness constraints, side effects, or return behavior. This is insufficient for an agent to understand the tool's full behavioral profile.

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

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

The description is a single sentence with no redundancy, front-loading the core action 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's moderate complexity (7 parameters, output schema) and the richness of the schema descriptions, the one-line description provides minimal additional context. It does not explain the output or the significance of the coupon's lifecycle relative to siblings.

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 86%, meaning the input schema already provides detailed parameter semantics (e.g., units, formats, defaults). The description adds no extra meaning beyond stating the tool's purpose, so it meets the baseline without improvement.

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 'Create a new operator-owned discount coupon' uses a specific verb (Create) and resource (operator-owned discount coupon), clearly distinguishing it from sibling tools like update, delete, or list, which have different verbs.

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

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

No guidance is provided on when to use this tool versus alternatives such as authority_update_coupon or authority_redeem_coupon. The agent receives no context about prerequisites or usage context.

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

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

With no annotations, the description carries full transparency burden. It details three layers, their conditions (e.g., 'configured=false' when no key), and what each returns. It does not mention side effects, rate limits, or authentication details beyond 'Restricted to the Authority owner,' but overall provides sufficient 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 well-organized with a clear heading and numbered list, making it easy to scan. It is somewhat lengthy but every sentence adds value; no redundant or 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 the output schema exists, return values are covered. The description comprehensively explains all three health layers, their prerequisites, and what information each provides, leaving no ambiguity for an AI 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 coverage is 100% with a single optional parameter described in the schema as 'Proof signed by the Authority's OWN npub (owner consent).' The description does not add additional semantic meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool checks the health of the DPYC economy's accounting store (Neon), with specific layers and their purposes. It distinguishes itself from sibling tools by being a health check, not an action 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?

The description explicitly restricts usage to the Authority owner, providing clear access control. It explains when each layer is available (e.g., 'projects' only if NEON_API_KEY is configured). However, it does not strongly differentiate when to use this tool versus other authority_ tools, though the context implies it's for health monitoring.

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

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

With no annotations provided, the description fully assumes the burden of behavioral disclosure. It discloses that it is a background task, operator-only, free, and has a specific time horizon. It does not explicitly mention destructiveness or side effects, but the nature of the task suggests it is non-destructive.

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

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

The description is extremely concise at four sentences, each carrying significant information: the action, the operator restriction, the time estimate, and the cost. No fluff or redundancy.

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

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

Given the tool has no parameters and there is an output schema (not shown but present), the description is complete enough for an AI agent to understand the tool's purpose, constraints, and outcome. It could mention what the output looks like or how to use the result, but the provided info is sufficient for invocation.

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

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

The tool has zero parameters and the schema coverage is 100% (empty). The description does not add parameter-specific meaning, but the baseline for zero parameters is 4, and the description appropriately mentions the tool takes no input.

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 builds a Merkle tree of patron balances and submits the root to Bitcoin via OpenTimestamps. It distinguishes itself from siblings by being a background notarization task, with no parameters and specific use case.

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

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

The description specifies it is an operator-only background task with a confirmation time of 1-6 hours and that it is free. It implicitly guides usage by noting the time requirement and operator restriction, but does not explicitly contrast with alternatives among the many sibling 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 fully discloses the Schnorr proof requirement for non-empty npub, the security rationale, and the fallback to self-inspection. This goes beyond schema details.

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 (two sentences and a paragraph), front-loaded with purpose, and every sentence adds value. No extraneous content.

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

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

Given that an output schema exists (so return values are covered), the description adequately covers parameter behavior, conditional logic, and security implications. No gaps.

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

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

While the npub parameter has a basic schema description, the tool description adds significant context: proof requirement and fallback behavior. The dpop_token parameter is not explained, but it defaults to empty and likely relates to the proof.

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 views registration status, balance summary, and Authority's Nostr npub. This distinguishes it from sibling tools that check balance, operator config, 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?

The description explains when to provide an npub (requires proof) vs when to leave it empty (self-inspection). However, it does not explicitly mention alternatives or 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 are present, placing full burden on the description. The description only states 'Free,' which offers minimal insight into behavior. It does not disclose whether the tool is read-only, requires authentication, or has any side effects. For a description-only tool, key behavioral context is missing.

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 (two fragments) and front-loaded with the key action and resource. While extremely concise, it could include a bit more context without becoming wordy. The 'Free.' note is a slight addition but does not detract.

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 (which likely covers return values), the description is minimally adequate. However, it does not clarify what 'DPYC ecosystem' or 'via the Oracle' means, nor does it explain how this tool differs from closely related siblings like authority_oracle_network_advisory.

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% coverage (trivially). The description correctly indicates no parameters are needed. No additional parameter explanation is required, so the description fully suffices.

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 specific verb 'Describe' and clearly identifies the resource as 'the DPYC ecosystem via the Oracle.' This distinguishes it from sibling oracle tools that target specific queries (e.g., tax rate, membership lookup). The purpose is immediately clear.

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

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

No guidance is provided on when to use this tool versus alternative oracle tools like authority_oracle_lookup_member or authority_oracle_network_advisory. The description lacks context for appropriate usage 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 carries full burden. It only mentions 'Free.', but fails to disclose other behavioral traits like idempotency, side effects, or authentication needs.

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, one sentence plus 'Free.', with no wasted words. It is front-loaded with the key 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?

Given no parameters and an existing output schema, the description is nearly complete for this simple tool. It lacks usage context but is otherwise sufficient.

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

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

With zero parameters and 100% schema coverage, the description need not add parameter info. 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 'Get the current DPYC certification tax rate', providing a specific verb and resource. It distinguishes from siblings by focusing on a unique tax rate query.

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 siblings or alternatives. The only extra info is 'Free.', which does not help in decision-making.

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 of behavioral disclosure. It only states the basic purpose and that it is free. It does not describe return format, side effects, permissions, or other behavioral traits. This is minimal.

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

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

The description is extremely concise with two sentences: 'Get DPYC onboarding instructions from the Oracle. Free.' It is front-loaded and contains no unnecessary words, earning every sentence's 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 no parameters and existence of an output schema, the description is largely adequate for a simple info-retrieval tool. It could mention that it returns instructions, but the output schema covers that. Minor gap: no context on what DPYC is, but domain knowledge may compensate.

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

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

The tool has zero parameters, and schema description coverage is 100%. The description does not need to add parameter information. The score is baseline 4 as no parameter details are required.

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: 'Get DPYC onboarding instructions from the Oracle.' The verb 'Get' and resource 'DPYC onboarding instructions' are specific. Though it doesn't explicitly differentiate from siblings, the unique purpose is implied by the name and context.

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

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

No guidance is provided on when to use this tool versus alternatives. The description only mentions 'Free.' but does not explain prerequisites, context, or exclude other tools. With many sibling tools, this omission reduces usability.

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 must disclose behavior. Only states 'Free.' which implies no monetary cost but does not confirm read-only behavior, rate limits, or auth requirements. Very limited 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?

Extremely concise: one sentence plus a short note. No redundant information. Front-loaded with 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?

For a simple lookup with one parameter and an output schema, the description is minimal but covers the basic purpose. Lacks usage context and differentiation from similar tools. 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?

With 0% schema coverage, description adds minimal meaning: 'by npub' confirms that npub is the lookup key. But no format, length, or validation hints. Adequate for a single parameter but insufficient for complete clarity.

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 verb 'Look up', resource 'DPYC community member', and method 'by npub'. It is distinct from sibling tools like 'authority_get_nostr_profile' which likely has a different purpose.

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

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

No guidance on when to use this tool vs alternatives, no prerequisites, and no exclusions. The description only states what it does, not when it should be chosen over other lookup 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 provided, the description carries full burden. It indicates the tool is read-only ('Get') and free, which is sufficient for a simple operation. However, it does not disclose any potential rate limits, access requirements, or other behavioral traits beyond what is obvious.

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

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

The description consists of two short sentences that convey essential information without redundancy. It is front-loaded with the action and resource, meeting the conciseness criteria perfectly.

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

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

Given the tool has no parameters, an output schema exists, and the description clearly states its purpose, the description is complete enough for an agent to understand what the tool does and invoke it correctly.

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

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

The tool has zero parameters, so the description needs no parameter information. The baseline score is 4, and the description adds no unnecessary details about parameters.

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

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

The description clearly states the action ('Get'), the resource ('active network advisories'), and the source ('from the Oracle'). It is specific and distinguishes this tool from sibling oracle tools like authority_oracle_about or authority_oracle_get_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 implies that the tool is for retrieving advisories but provides no guidance on when to use it versus alternatives or when not to use it. Since there is no sibling tool with overlapping functionality, the lack of explicit exclusions is acceptable but still minimal.

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 bears the burden of behavioral disclosure. It clearly explains that the wheel verifies the signature against the npub, relays to public relays, does not hold nsec, and uses the signature as authorization—free of charge. However, it does not mention failure behavior or relay selection details, so it's not fully exhaustive.

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

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

The description is concise, using multiple sentences efficiently. It front-loads the purpose and then provides necessary detail. Every sentence contributes value, though slight redundancy in explaining the signing process could be tightened.

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 and the presence of an output schema (unseen), the description covers the essential behavioral and security aspects: client signing, verification, relaying, no key custody, and cost. It lacks explicit error handling or relay failure details, but overall it provides a solid understanding of the tool's operation.

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

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

Although schema coverage is 100% and baseline is 3, the description adds meaningful context beyond the schema: it explains that the signed_event is a client-signed kind-0 event passed as JSON, and that npub is the signer's public key. This enriches the schema descriptions, justifying a higher score.

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' with the target 'for an npub'. It distinguishes the tool from its sibling 'authority_get_nostr_profile' by emphasizing the publishing action and the client-signed nature, leaving no ambiguity about what the tool does.

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

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

The description implies usage when a client has a signed event and wants to broadcast it, but it does not explicitly contrast with alternatives like direct relay publishing or other tools. No when-not or alternative tool guidance is provided, so the guidance is merely adequate.

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 must carry behavioral details. It states that the tool creates a Lightning invoice, requires proof of npub ownership, and is free to call. This provides key behaviors but omits details like invoice expiry, idempotency, or failure handling.

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 short, focused sentences. No filler. Front-loaded with the core purpose. Every sentence adds necessary information (purpose, flow, requirement, cost).

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, flow, prerequisite, and cost. Given that an output schema exists (not shown here) and the tool is part of a larger system, the description is reasonably complete. Could mention invoice expiry or cancellation, but the main points are covered.

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

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

Schema coverage is 100% with detailed descriptions for each parameter (npub, dpop_token, amount_sats). The tool description adds context about why dpop_token is needed ('Proof of npub ownership is required'), but this is marginal. Baseline 3 applies as the schema already does the heavy lifting.

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 starts with 'Buy credits via Bitcoin Lightning.' This is a specific verb+resource combination. Among siblings, only this tool handles purchasing credits, clearly distinguishing it from balance checks 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 outlines the flow (create invoice, pay, call check_payment) and states 'Free — no credits required to call.' However, it does not explicitly say when to use this tool versus alternatives like authority_restore_credits or authority_mint_coupon. The usage context is implied but lacks direct exclusions or comparisons.

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 fully discloses key behaviors: inline Schnorr verification (no relay round-trip), durable pending row creation, best-effort owner-notification DM, and deferred provisioning. No contradictions or omissions.

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

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

The description is concise, well-structured, and front-loaded. Each sentence serves a purpose: invocation context, verification mechanism, record creation, notification, and limitation. 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?

Given the complexity and existence of an output schema, the description is complete. It explains the role in the broader workflow (inbound from request_adoption, followed by approve_adoption), the cryptographic verification, and the pending state. It adequately covers all necessary context for correct usage.

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 some context (e.g., dpop_token is 'inline kind-27235 proof bound to the adoption sentinel' and 'request_adoption mints this automatically'), but for service_url and operator_npub, it largely restates the schema. It does not provide significant additional semantic meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'record an operator's request to be adopted by this Authority.' It specifies it's inbound and called by request_adoption. This distinguishes it from siblings like authority_approve_adoption, authority_reject_adoption, and authority_list_adoption_requests.

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: when an operator requests adoption via their request_adoption tool. It provides context on the flow (verification, pending row, notification) and explicitly states what it does NOT do: 'Does NOT provision — provisioning waits for owner's approve_adoption.' This gives clear limitations but stops short of explicitly mentioning when not to use or listing direct alternatives.

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

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

With no annotations, the description fully discloses behavior: deterministic one-shot retrieval, draining specific relay, deletion of wrong DMs, NACK/ACK logic, stop on first match, queue draining with courier_not_found return, and credential_card bypass. Also notes no server restart needed.

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

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

Every sentence adds unique value. Well-structured: overview, flow context, usage guidance, detailed behavior, optional path. No redundancy or 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?

Given 4 parameters, complex flow, and existing output schema, the description covers behavior on success (reinitialization) and failure, optional path, and constraints. 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%, but description adds valuable context: service must match request_credential_channel, dpop_token is session phrase, sender_npub identifies sender, credential_card optional and bypasses relay. Goes beyond basic 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 it 'pick up credentials from the Secure Courier' and completes the CREDENTIAL-DELIVERY flow. It distinguishes itself from the sibling receive_npub_proof, providing a specific verb and resource.

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 instructs 'Call this only after the user confirms they have replied.' It warns against polling, looping, or retrying, and describes the alternative credential_card path. Differentiates from receive_npub_proof as the ownership-proof counterpart.

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

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

The description discloses key behaviors: verifying Schnorr proof, recording a durable state row, and sending a best-effort DM. However, it omits details on failure modes, idempotency, or potential side effects of recording state. Given no annotations, the description could be more transparent about error handling.

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 only four sentences covering purpose, trigger, mechanism, and significance. It is well-structured, front-loading the core function and avoiding unnecessary verbosity.

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 (verification, state recording, notification), the description covers the essential workflow. The presence of an output schema reduces the need to detail return values. However, it could mention the output schema's structure or key fields for completeness.

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

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

The schema provides 100% coverage of parameters with descriptions. The tool description adds value by explaining the role of `dpop_token` (inline proof bound to wire name) and the context of `npub` and `detail`. This enriches the agent's understanding beyond the schema alone.

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

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

The description clearly defines the tool's purpose: receiving a Neon 402 alert from an operator's runtime. It uses specific language ('Inbound: an operator reports its Neon store is 402-locked') and distinguishes this from sibling tools by explaining its unique role in alerting the Authority before complaints.

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

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

The description explicitly states the trigger ('Called MCP-to-MCP by the operator's runtime the instant it catches a Neon HTTP 402') and what the tool does (verifies npub, records state, fires DM). It lacks explicit exclusion of other scenarios, but the context is clear enough for an agent to understand when to invoke 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?

Detailed behavioral description without annotations: deterministic one-shot retrieval, drains only pinned relay, stops at matching DM, deletes mismatched DMs without revealing phrase, proves ownership via signed DM, returns dpop_token, and notes that MCP never stores raw token. Fully 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?

Well-structured with clear sections: purpose, prerequisites, behavior, and result. Every sentence adds necessary information without redundancy. Front-loaded with key points.

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 output schema exists, description does not need to explain return values. It covers flow, prerequisites, failure modes, side effects, and security considerations. Leaves no obvious gaps.

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

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

Schema coverage is 100% and parameter descriptions are present. The description adds value by explaining that dpop_token must come from request_npub_proof and that patron_npub is the patron's npub, reinforcing how they are used together. Does not exceed but complements 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?

Clearly states it receives npub ownership confirmation from a patron, completes a specific flow, and names the required parameters. Distinguishes itself by referencing its counterpart 'receive_credentials' and the overall proof flow.

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

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

Explicitly says 'Call this only after the user confirms they have replied.' Warns against polling, looping, or retrying, and explains the consequence of premature calls. Names an alternative tool ('receive_credentials') for a different phase.

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: validates window and cap, records redemption, auto-applies discount on subsequent calls until uses exhausted, free, requires npub proof, idempotent. 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?

Description is four concise sentences, front-loaded with the primary action, and efficiently conveys all key behavioral and usage details without redundancy.

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

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

Given the presence of an output schema (signal indicates yes), the description does not need to explain return values. It covers purpose, behavior, idempotency, cost, and prerequisites, making it complete for this 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 0%, so description must compensate. It explains 'code' as the operator-shared coupon code and mentions 'npub' in context of required proof. However, it does not explain the 'npub' field itself or the optional 'dpop_token' parameter, leaving 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 verb-resource pair: 'Claim a coupon by its name (the code the operator shared).' It further explains the mechanics (lookup, validate, record) and distinguishes from sibling tools like authority_mint_coupon, authority_delete_coupon, 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?

Provides clear context for when to use: to claim/redeem a coupon. Includes usage conditions: free, requires npub proof, idempotent. Does not explicitly list alternatives or when-not-to-use, but the action is distinct and well-scoped.

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 mentions an external action (sending a DM challenge) but does not disclose side effects, required permissions, or whether the operation is reversible. For a tool with no annotations, more behavioral context is needed.

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

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

The description is a single, front-loaded sentence that conveys the core action. It avoids redundancy, though slightly more context could be added without harming conciseness.

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

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

Despite having an output schema, the description does not explain the challenge purpose, expected next steps, or how to handle the response. For a multi-step onboarding process, this is insufficiently 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% and the description indirectly references the parameter, but it adds minimal extra meaning beyond the schema's own description of 'candidate_npub'. 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 specifies the action ('send a Nostr DM challenge') and the context ('Step 1/3 of Authority onboarding'), making it distinct from sibling tools like authority_register_operator.

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 such as authority_register_operator or authority_receive_npub_proof. The 'Step 1/3' hint is insufficient without explaining the onboarding flow or prerequisites.

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

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

No annotations are provided, so the description carries full burden. It discloses the tool is idempotent, requires two proofs, and creates a ledger entry. It does not mention rate limits or auth beyond proofs, but given no annotations, it adds useful 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 moderately long but well-structured with a one-line summary, bullet points, and a next step. It is efficient for its content, though slightly repetitive on proof details.

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

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

Given the tool's complexity (5 params, output schema exists), the description covers prerequisites, idempotency, and next steps. It does not fully explain the dpop_token parameter or the exact return values, but the output schema may cover returns. Overall, it is complete enough for usage.

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 80% but the description introduces a 'proof' parameter not present in the input schema, which is confusing (schema has dpop_token). It adds context about how authority_proof is obtained, but does not clarify dpop_token's role. This reduces value beyond 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 it provisions an operator in the Authority ledger, creating an entry for purchasing credits and certifying orders. It distinguishes from sibling tools like authority_deregister_operator, authority_check_balance, etc., by focusing on registration and including a next step (purchase_credits).

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

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

The description explains prerequisites (two identity proofs), refers to related tools (request_npub_proof/receive_npub_proof) for obtaining the first proof, and outlines the next step (purchase_credits). It does not explicitly say when not to use or compare with all siblings, 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. Description only says 'Reject' without disclosing side effects (e.g., notification, irreversibility, state changes). Insufficient for a potentially destructive action.

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, 8 words, direct and to the point with zero 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?

Output schema exists (though not shown) which may compensate for missing return value details. However, description omits what happens on rejection (e.g., success/failure criteria, effects on request).

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 descriptions are clear. Main description adds no extra meaning beyond what the schema already provides.

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 states specific action 'Reject' on resource 'pending operator-adoption request' with context 'owner consent'. Clearly distinguishes from siblings like 'authority_approve_adoption'.

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 implies use when rejecting an adoption request with owner consent, but no explicit when-not-to-use or alternatives beyond sibling names.

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 fully disclose behavioral traits. It states the tool is idempotent and only fixes ownership and grants. However, it lacks details about required permissions, potential side effects (e.g., locking), or error conditions. The description is 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 three sentences long, each serving a distinct purpose: stating the action, explaining the motivation, and contrasting with a sibling. It is front-loaded and contains no unnecessary words.

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

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

Given the presence of an output schema and clear input parameter descriptions, the description provides sufficient context for the tool's main function. It explains the problem and distinguishes from a key sibling. Minor gaps exist (e.g., no mention of output handling, but mitigated by 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?

Both parameters are described in the input schema with clear explanations. The overall description does not add meaning beyond what the schema already provides. With 100% schema coverage, the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: reassigning table ownership to the operator's role and re-granting DML. It specifies the resource (tables in operator's tenant schema) and the action (repair ownership), and distinguishes itself from the sibling 'authority_register_operator' by noting what it does NOT do (rotate password, send bootstrap DM).

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: when the provisioning role owns tables and blocks CREATE INDEX. It contrasts with 'authority_register_operator', providing a clear alternative. However, it does not explicitly state when not to use other sibling tools or provide a broader set of usage conditions.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: requires npub as author of record, costs a fee (anti-abuse), the report is public and goes to maintainers, returns issue info or 'not configured' situation without charge. It also details the dpop_token format requirements. No contradictions present.

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

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

The description is about 120 words, every sentence adds value. It is well-structured: purpose sentence, rationale, mechanics, return value. Only minor trimming could be possible, but overall it is concise and informative.

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 explains the return values (repo, number, url) and error handling (not configured scenario). An output schema exists, so return format details are not required. The description covers all key aspects for a reporting tool with moderate 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%, but the description adds significant value beyond the schema. For example, it explains npub as 'author of record', dpop_token as raw JSON with specific constraints (not base64, not NIP-98, etc.), and body as 'details — which tool, what was wrong, what you expected.' This fully clarifies parameter usage.

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 'File a field report about this service as a GitHub issue on the operator's repo.' This clearly specifies the verb (file/report) and resource (field report/GitHub issue), and it distinguishes from sibling tools as the only reporting tool among many authority_* tools.

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

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

The description explicitly states when to use: 'Found a tool's metadata or response wrong or confusing? Report it where the tool lives.' It explains the mechanism and cost but does not explicitly list when not to use. However, the context is clear and no alternative tools are needed.

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

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

With no annotations, the description carries the full burden. It discloses the restricted access, proof requirement, MCP-to-MCP delivery, pending state, and eventual outcome (flip to ready). It does not cover idempotency or error conditions, but the core behavioral traits are 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 six sentences, front-loaded with the core purpose. It efficiently explains restrictions, flow, and next steps without redundancy. Could be slightly tighter, but overall concise and well-structured.

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

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

Given the tool's complexity (4 params, async, polling) and presence of an output schema, the description adequately covers the initiation flow, async nature, and suggests using adoption_status. It omits failure handling but is complete enough for agent selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context like 'RESTRICTED to the operator' and explains the overall flow, but the parameter descriptions in the schema already cover what each parameter is. The description does not significantly enhance understanding beyond what the schema provides.

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 'Ask a chosen Authority to adopt this operator (deferred courtship).' It uses a specific verb ('ask') and resource ('Authority to adopt operator'), distinguishing it from sibling tools like authority_approve_adoption or authority_adoption_status by emphasizing it is the initiation step and restricted to the operator.

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 'RESTRICTED to the operator' and 'requires proof the caller controls this operator's npub.' It also advises polling adoption_status for progress, implying when to use that tool. However, it does not explicitly contrast with alternatives like authority_approve_adoption or authority_reject_adoption, though the context from sibling names provides implicit differentiation.

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