tollbooth-authority

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

With no annotations provided, the description discloses that the tool is free (no credits consumed) and requires dpop_token for authentication. However, it does not mention whether the tool is read-only or any potential side effects, nor does it discuss error conditions or latency.

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

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

The description is well-structured with an introductory sentence, a bullet list of return contents, a clarifying note, a requirement line, and an Args block. It is concise but loses a point for minor redundancy (e.g., mentioning 'account statement' twice).

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

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

Given the existence of an output schema, the description adequately covers the tool's purpose, parameters, and key behavioral aspects (free, proof required). It could be more complete by mentioning error handling or edge cases, but it is sufficient for an agent to use effectively.

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

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

Although the input schema itself lacks descriptions (0% coverage), the description provides detailed explanations for all three parameters: npub, dpop_token, and days, including format and default value. This fully compensates for the schema gap.

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

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

The description clearly states it generates a patron's account statement, lists the contents (purchase history, credit tranches, etc.), and distinguishes it from the operator's Authority tax balance, which differentiates it from many sibling 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?

It specifies the prerequisite of proof of npub ownership to prevent scraping, and implies when not to use it (not for operator tax balance). However, it does not explicitly compare with the sibling 'authority_account_statement_infographic' or other 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 burdens behavioral transparency. It explains output structure (SVG graphic components), cost (1 api_sat per call), and proof verification by 'debit_or_deny'. It gives enough detail for an AI agent to understand side effects and prerequisites.

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 concisely structured: a one-sentence purpose, followed by a second paragraph detailing output and cost, and finally a parameter list. No redundant information. Front-loaded with key action 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 existence of an output schema (not shown but indicated), the description need not cover return values. It adequately covers purpose, parameters, cost, output components, and distinguishes from a sibling tool. It is complete for an agent to invoke correctly.

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

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

Schema description coverage is 0%, but the description provides clear, meaningful explanations for all three parameters: npub (Nostr public key), dpop_token (kind-27235 event), and days (default 30). This adds significant value beyond the schema.

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

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

Description clearly states the tool generates a visual SVG infographic of an account statement, with specific components listed (balance hero, metrics cards, etc.). It also distinguishes from sibling tool 'account_statement' by noting it returns the same data but rendered as a graphic.

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

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

Description indicates when to use this tool (for a visual representation) vs the sibling for raw data. It also mentions cost and proof verification, which helps in deciding usage. However, it does not explicitly 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?

With no annotations, the description adequately notes it polls MCP-to-MCP and returns status values. However, it does not disclose side effects, idempotency, or error scenarios.

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 short and to the point, with no redundant information. It lacks structure but is efficient.

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

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

Given the presence of an output schema, return values are covered. However, the description omits prerequisites (e.g., existence of a request) and error handling, leaving gaps for a tool with many 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 coverage is 0%. The description only explains 'authority_npub' indirectly, while 'dpop_token' is not mentioned at all, despite having a default value.

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

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

The description clearly states the tool checks adoption-request status at a chosen Authority and lists possible statuses. However, it does not differentiate from the sibling 'authority_get_adoption_status', which appears to serve the same 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 like 'authority_get_adoption_status'. The mention of 'Free' is not usage guidance.

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

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

No annotations are provided, so the description carries full burden. It discloses the provisioning effect and references _provision_operator. However, it lacks details on side effects, error conditions, or idempotency. The description is adequate but not rich.

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 main action. The second sentence adds valuable context about the relationship to register_operator. While slightly technical, it is efficient and earns its place.

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

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

Given the tool's modest complexity (2 parameters, output schema exists), the description covers the main action and relationship to a sibling. However, it omits prerequisites (e.g., need for an existing pending request) and error handling, making it minimally 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%, so the baseline is 3. The description does not add new meaning beyond the schema; it mentions 'authority_proof consent' but that is already clear from the schema description. No additional parameter insight is provided.

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

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

The first sentence clearly states 'Approve a pending request and provision the operator.' The second sentence distinguishes it from register_operator as its 'deferred-courtship counterpart,' making the purpose specific and differentiating it from a sibling 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 identifies it as the deferred version of register_operator, used after review. This provides clear context for when to use it versus the immediate counterpart. However, it does not explicitly list alternative tools or scenarios where it should not be used.

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. It discloses the use of a decorator for fee debit, storage in runtime._last_debit_cost, and that no recomputation is needed, adding behavioral context beyond the schema. However, it does not explicitly state whether the tool is read-only or mutating, though 'certify' implies a state change.

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 concise sentences: core purpose, technical detail about the decorator, and usage context. 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?

The tool has an output schema (though unknown content) and parameters are partially described. The description explains who calls it and the return type. It is sufficiently complete for a certification step in a payment flow.

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% (npub and amount_sats have descriptions). The description adds no parameter-level meaning beyond the schema, so a 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 certifies a purchase order and returns a Schnorr-signed Nostr event certificate. The verb 'certify' and resource 'purchase order' are specific, and the tool is distinct from siblings like 'authority_purchase_credits' and 'authority_check_payment'.

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

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

The description explicitly states it is called by operator MCP servers (not end users) when a patron purchases credits, providing clear context for when to use it. It does not explicitly mention when not to use or alternatives, but the context is sufficient.

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

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

No annotations are provided, so the description carries full burden. It mentions activation which implies mutation, but lacks details on side effects, required permissions, or behavior on failure. For a tool that modifies state, this is insufficient.

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

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

The description is very short and to the point, but it omits important details. It is concise without being verbose, but could include more context without becoming too long.

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

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

Despite having an output schema and one parameter, the description lacks behavioral details, especially for a tool that is part of a multi-step onboarding process. It does not explain what 'activate Authority' entails or what the output represents.

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 adds no additional meaning beyond the schema's description of 'candidate_npub'. Baseline 3 is appropriate as the schema already documents the parameter.

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

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

The description clearly states it is step 3/3 of Authority onboarding and specifies the actions: check parent approval and activate Authority. This distinguishes it from sibling tools, though 'activate Authority' is somewhat vague.

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 it is the final step in a sequence but does not specify prerequisites or when not to use it. No alternatives are mentioned, but the step context provides minimal 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 description discloses important behavioral traits: it returns available sats, is free, and explains the impact of a zero balance on patron top-ups. It does not mention authentication or side effects, but covers key aspects.

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

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

The description is concise (5 sentences) and front-loaded with the main purpose. Every sentence adds useful information without redundancy.

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

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

Given no parameters and an existing output schema, the description fully explains what the tool returns (sats), its significance, and the next step if balance is zero. It is complete for a check tool.

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

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

There are no parameters, so the baseline for zero params is 4. The description adds value by explaining the return value and its context, which is sufficient.

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

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

The description clearly states the tool checks the operator's tax balance at the Authority and returns sats for certifying patron credit purchases. It distinguishes this from a patron balance and mentions the consequence of a zero balance. This is 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 provides context on when to use the tool (to check operator's own funding) and what to do if balance is zero (call purchase_credits). However, it does not explicitly contrast with sibling tools like authority_check_balance, though the distinction is implied.

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

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

Discloses that the tool is free and describes the authentication requirement and its purpose (preventing enumeration). Without annotations, it provides useful behavioral context, though it doesn't explicitly state it's non-destructive or idempotent.

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?

Relatively concise at about 6 sentences, with purpose front-loaded. Could be slightly tighter by removing redundant phrasing, but generally efficient and readable.

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

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

Explains the context of the tool (patron spending balance, Lighting credits, operator-specific) and why the dpop token is needed. Output exists via schema, so not explaining return values is acceptable. Lacks error handling details but adequate given 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?

Adds full meaning beyond the schema: explains npub is a Nostr public key with format npub1..., and dpop_token is a kind-27235 Nostr event signed by npub. This is essential since schema has zero description coverage.

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

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

Description clearly states it checks a patron's credit balance at an operator, with a specific verb and resource. It attempts to distinguish from the operator's own balance, but contains a confusing self-reference ('use authority_check_balance instead'), which slightly undermines clarity.

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 usage context: it's free, requires proof of npub ownership, and compares to operator balance check. However, it doesn't explicitly state when not to use it or list alternative tools (only hints at one).

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

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

Without annotations, the description carries full burden but only indicates a read operation ('Look up'). It does not disclose potential side effects, authentication needs, rate limits, or behavior on 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 extremely concise at 8 words, but this comes at the cost of missing crucial details. It is appropriately front-loaded but under-specified.

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

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

Given the existence of an output schema and a single parameter, the description is still incomplete. It does not explain what DPYC is, what the output contains, or how the lookup works, leaving significant ambiguity.

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

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

Schema description coverage is 0%, and the description does not explain the 'npub' parameter beyond its name. It fails to clarify format, purpose, or expected values, leaving the agent with no guidance.

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

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

The description clearly states the action ('Look up') and the resource ('an npub in the DPYC community registry'). It distinguishes from sibling tools that perform different actions (e.g., approval, certification, account statements).

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 the many sibling tools. There is no mention of use cases, prerequisites, or contexts where this lookup is appropriate.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool is free and requires authentication (dpop_token) to prevent front-running, but does not elaborate on what happens if the payment is invalid or what the output looks like 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 well-structured with a concise opening sentence, followed by usage context, free status, authentication rationale, and parameter list. It is appropriately sized for the tool's complexity.

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

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

Given the presence of an output schema, the description need not detail return values. It adequately covers the purpose, usage context, and parameter semantics. Minor gaps exist: no mention of error conditions or expected response format, but overall it is complete enough 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 0%, so the description must compensate. It provides clear explanations for all three parameters: invoice_id (returned by purchase_credits), npub (Nostr public key), and dpop_token (signed Nostr event). This adds meaning beyond the bare 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: 'Check the payment status of a Lightning invoice.' It uses a specific verb (check) and resource (payment status of invoice), and distinguishes itself from sibling tools by specifying it's called after purchase_credits.

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

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

The description explicitly says 'Call after paying the invoice from purchase_credits,' providing clear when-to-use guidance. It also notes the tool is free and requires proof of npub ownership. However, it does not mention when not to use or 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?

Description notes the tool is free and shows cost, but with no annotations, it fails to explicitly state that it is a read-only preview without side effects, leaving some behavioral ambiguity.

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

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

Description is well-structured with a clear summary and detailed Args block, though slightly verbose; it could be more concise by omitting the FE caller 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?

The description covers the core purpose and two key parameters, but lacks explanation for npub and dpop_token, and does not discuss prerequisites or usage context; however, an output schema exists so return values are 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?

Description explains tool_id and tool_kwargs with examples, adding value beyond the schema's 0% description coverage, but npub and dpop_token are left unexplained despite having defaults.

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 'Preview the effective cost of a tool call' and explains it shows base cost and constraint effects, which distinctly identifies its purpose among sibling 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 implies usage for cost preview before a tool call but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like authority_get_pricing_model.

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 clearly states 'Free, no side effects — does not evict the cache or touch relays,' disclosing behavioral traits beyond basic 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?

Well-structured with a clear first sentence, then context, then args. Slightly lengthy but each part adds value.

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

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

Given output schema exists (not needed to explain return), the description covers purpose, side effects, and usage constraints adequately for a check tool.

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

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

Schema coverage is 0%; description adds meaning by explaining both parameters, but incorrectly states they are required (schema shows defaults and no required). This contradiction reduces 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?

Describes checking cached dpop_token validity with specific verb+resource, and distinguishes from sibling check_oauth_status by noting this is for npub-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 states use case: check before paid calls to avoid burning credits on failure. Mentions it is free and side-effect-free, but does not explicitly list when not to use or alternatives beyond the mirror reference.

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 mentions verification and escalation but does not disclose side effects, authorization requirements, rate limits, or what happens on success/failure. More behavioral detail is needed for a critical onboarding step.

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

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

The description is two sentences and relatively concise, but the second sentence is somewhat technical and could be streamlined. It effectively front-loads the purpose.

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

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

Given the complexity of the multi-step onboarding and chain resolution, the description covers essential flow and logic. However, it lacks information on return values or error conditions; the presence of an output schema mitigates the need for return value details, but error handling is not addressed.

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

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

The input schema has 100% description coverage for the single parameter. The description adds minimal context beyond the schema's description of 'candidate_npub' as the candidate who replied to the DM challenge, so it does not significantly enhance understanding.

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 is 'Step 2/3 of Authority onboarding' and specifies the action: 'verify candidate DM, escalate to parent Authority.' It also explains how the parent Authority is resolved, making the tool's purpose distinct from sibling 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 implies the tool is used in a specific onboarding workflow (step 2/3), but it does not explicitly state when to use it versus alternatives or provide exclusions. There is no direct comparison to 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 carries transparency. It discloses cascading deletion to redemptions, no-op behavior for orphan references, and warnings from the Studio. It lacks details on reversibility or return status, but overall informative.

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

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

Three concise sentences, no wasted words. Front-loaded with the primary action, then cascading behavior, then access restriction. Efficient and clear.

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

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

The description covers main behavior and restrictions but omits parameter details for dpop_token and does not describe the return value or output schema (which exists). For a delete operation with 2 params, it's partially complete but has 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 0%, so description must explain parameters. It fails to describe coupon_id beyond the name and does not explain dpop_token at all. The 'requires proof' mention doesn't map clearly to dpop_token, leaving significant 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 'Delete a coupon', specifying the verb and resource, and mentions cascading effects. This distinguishes it from siblings like authority_forget_coupon or authority_mint_coupon.

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

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

The description explicitly states 'RESTRICTED to operator — requires proof', providing a clear usage condition. It implies when to use (only as operator) and hints at restricted access, though it does not compare with alternatives.

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

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

No annotations are provided, so the description carries full burden. It correctly labels the operation as a write to a sensitive credential vault, requires dpop_token for authentication, and states it's free. It also notes it deletes only one field without affecting others, which is important 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 front-loaded with the purpose and then provides parameter details in a structured list. There is minimal waste, though the 'Free.' sentence could be integrated. Overall, it efficiently conveys the necessary information.

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

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

Given the output schema exists, return value details are not needed. The description covers the tool's purpose, parameters, authentication requirement, and cost. It is complete for a delete operation with three parameters, though it could mention error handling or field existence checks.

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%, meaning no parameter descriptions in schema. The description provides clear, detailed explanations for all three parameters: npub as Nostr public key, dpop_token as a kind-27235 event signed by npub, and field as the credential field name. This adds significant value beyond the schema.

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

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

The description clearly states the tool removes a single patron credential field, with the verb 'Remove' and the resource 'patron credential field.' It distinguishes from sibling tools like authority_update_patron_credential and authority_get_patron_credential_fields by focusing on deletion.

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 that it deletes one field without affecting others and requires proof of npub ownership, implying it's for targeted deletion. While it doesn't explicitly say when not to use, the context of sibling tools (update vs delete) provides clear guidance. A slight improvement would be to 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 provided, the description carries the full burden. It discloses that the tool requires specific proofs and warns about unauthorized removal risk. It does not detail irreversibility or side effects, but the core behavioral trait (removal requiring consent) is well explained.

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

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

The description is two paragraphs containing essential information without extraneous details. It is front-loaded with the main action and then elaborates on proof requirements. Could be slightly more terse but overall efficient.

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

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

The tool has 3 parameters, no annotations, and an output schema (not shown). The description does not mention the output or post-removal state. While the action is clear, missing details about success/failure behavior and dpop_token parameter make it somewhat incomplete.

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

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

Schema coverage is 67% (2 of 3 parameters documented). The description adds context about the proofs' purposes but does not explain the 'dpop_token' parameter, which has no schema description. Thus, the description only partially adds meaning beyond the schema.

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

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

The description clearly states the action: 'Remove an Operator from the DPYC community registry.' It uses a specific verb and resource, and distinguishes from siblings like 'register_operator' by referencing similar proof requirements.

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 that it requires two proofs and warns about the consequence of missing the authority proof, providing clear context on when to use and the security implications. However, it does not explicitly state when not to use or mention 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?

With no annotations, the description discloses that the operation is cosmetic, the coupon still exists, and re-redeem is possible. It also mentions 'free' and npub requirement. No adverse effects or contradictions are 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?

Two sentences with no redundancy. The first sentence captures the core action, the second adds essential nuance. Very 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?

Describes the purpose and cosmetic nature, but lacks explanation for the optional dpop_token parameter and does not cover prerequisites beyond npub. Since output schema exists, return value explanation is not needed, but parameter documentation is incomplete.

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

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

Schema description coverage is 0%, so the description must explain parameters. It only clarifies that npub is a proof requirement, but does not explain coupon_id or dpop_token at all. This leaves two parameters ambiguous.

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 'Remove a coupon from this patron's redemption list' with verb and resource. The phrase 'Cosmetic only' distinguishes it from permanent deletion, which is critical given the sibling tool authority_delete_coupon.

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

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

Explicitly mentions that the action is cosmetic and the coupon can be re-redeemed later, guiding when to use this over delete. It also states it requires proof of npub. However, it does not explicitly list alternative tools or 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?

Discloses that the operation is destructive ('as destructive as a write') and requires proof of npub ownership via a kind-27235 event. No annotations are present, so the description carries the full burden and does so well, though it could mention idempotency or response behavior.

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

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

The description is efficiently structured with a clear action statement first, followed by usage details. The final 'Free.' is slightly extraneous but short. Overall, it is concise without unnecessary repetition.

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

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

Covers the core purpose, parameter usage, and behavioral context. An output schema exists, so return value details are not necessary. Could mention success/confirmation behavior, but overall completeness is adequate given the tool's complexity.

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

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

Schema description coverage is 0%, but the description provides clear explanations for all three parameters: service (which credential service), npub (the public key format and ownership), and dpop_token (the specific Nostr event required). This fully compensates for the 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?

The description clearly states the verb 'Delete' and the resource 'vaulted credentials', with scope defined by service and npub. It distinguishes this tool from siblings by focusing on forgetting credentials, which is 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?

Provides clear guidance on which npub to pass for operator vs. patron credentials, and emphasizes the need for proof of ownership via dpop_token. However, it does not explicitly compare to sibling tools or state when to use alternatives.

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

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

No annotations are provided, so the description must carry full weight. It correctly identifies the operation as a read (safe, no side effects) and notes there is no proof required. However, it does not disclose any additional behavioral traits like rate limits or idempotency.

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

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

The description is concise with two sentences. The first sentence front-loads the purpose, and the second provides useful context about sensitivity and an alternative tool. It is efficient but could be more 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?

For a simple read tool with an output schema, the description covers purpose and some context. However, it lacks clarity on when to use this tool versus similar siblings (e.g., authority_list_adoption_requests), leaving gaps for an agent.

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

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

Schema coverage is 100% with a clear parameter description. The tool description adds no extra meaning beyond what is already in the schema, so baseline score applies.

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

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

The description clearly states it reads an operator's adoption-request status (verb+resource). It is distinct from other tools by emphasizing it is free and no proof is needed, but does not explicitly differentiate from similar siblings like 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 mentions the operator can poll via another tool, but it does not clearly specify when to use this tool versus alternatives. The context about sensitivity is useful, but guidance on appropriate use cases is lacking.

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

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

Discloses that operation is free, requires no proof, data is public, returns latest metadata fields or empty profile. No annotations provided, so description carries full burden and does so thoroughly.

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

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

Two sentences, front-loaded with action, no filler. Efficiently communicates key info.

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 return fields and empty profile case. Output schema exists, so return details are not needed. Could mention npub format for completeness, but overall adequate for a simple read tool.

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

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

Schema has one parameter 'npub' with 0% coverage; description only mentions 'an npub' without explaining format (e.g., bech32, hex) or that default empty might imply current user. Insufficient addition beyond schema.

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

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

Clearly states it reads a public Nostr profile for a given npub, specifying NIP-01 kind-0 metadata. Distinguishes from sibling tool authority_publish_nostr_profile as read-only.

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

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

States 'Free, no proof' indicating no authentication needed and data is public. Implies when to use but does not explicitly compare to alternatives or mention 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?

No annotations are provided, so the description carries the full burden. It states the tool generates a proof (read-like operation), but does not disclose error handling, authorization needs, or whether the tool is destructive. The description is adequate but lacks important 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 extremely concise: a single sentence for purpose followed by a two-line parameter list. Every word earns its place, and the key 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?

Given the tool has only two parameters and an output schema exists (so return values need not be described), the description is fairly complete. It lacks broader context about Bitcoin-notarized snapshots or typical invocation scenarios, but is adequate for its purpose.

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 the description must define parameters. It explains notarization_id as 'the notarization record ID' and npub as 'the patron's Nostr public key', adding meaning beyond the raw schema. However, it does not specify exact formats or length constraints.

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

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

The description clearly states the tool generates a Merkle inclusion proof for a patron's balance in a Bitcoin-notarized snapshot. The verb 'Generate' and resource 'Merkle inclusion proof' are specific, and the tool is distinct from siblings which perform different actions like checking balance or listing notarizations.

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?

Usage is implied by the description (you need a notarization_id and npub), but there is no explicit guidance on when to use this tool vs alternatives, no prerequisites mentioned, and no exclusion criteria. The sibling tools differ, but the description does not help an agent choose among them.

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

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

With no annotations provided, the description carries the full burden. It discloses the gating condition (Schnorr signature), which is a key behavioral trait. However, it does not explain what happens on failure or other 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 extremely concise with two sentences: first states the purpose, second explains the gating. No redundant information, and it 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 retrieval tool with an output schema (presumably covering return fields), the description adequately covers purpose and access control. It could mention that it is a read-only operation, but the output schema likely fills that gap. Given the complexity and sibling tools, this is nearly 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 50% (npub has a description, dpop_token does not). The description adds context by linking npub ownership to the gating mechanism, implying dpop_token may carry the signature, but does not fully clarify dpop_token's 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 clearly states the verb 'Retrieve' and the resource 'operator bootstrap configuration' with specifics (Neon URL, schema), making the tool's purpose unambiguous. It distinguishes itself from sibling tools by focusing on configuration 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 indicates that the tool is gated by Schnorr signature proof of ownership, providing clear context on when to use it (when you have the npub and can prove ownership). 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?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It states the tool 'reports' and is 'free', implying no side effects and no cost, but does not detail permissions, rate limits, or any other behavioral aspects. It is adequate but not thorough.

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

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

The description is extremely concise with three sentences covering purpose, behavior, and alternative usage. Every sentence adds value; no wasted words. Front-loaded with the main 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 the tool has no parameters and an output schema exists (though not shown), the description adequately covers what the tool returns (configured/missing values and delivery instructions). It is complete for a reporting tool of this simplicity.

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

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

The input schema has zero parameters, so schema description coverage is 100%. With no parameters, the description does not need to add parameter semantics; a baseline score of 4 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 reports operator configuration readiness, specifying what it shows (configured/missing settings and how to deliver missing values). It also distinguishes from the sibling tool 'get_patron_onboarding_status' by explicitly mentioning the alternative for patron-level queries.

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

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

The description provides explicit guidance on when to use this tool (operator configuration readiness) and when not to (patron-level credential status), directing the user to a specific alternative tool. This helps the agent choose correctly among siblings.

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

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

Discloses that values are never exposed, that it's free, that ownership proof is required, and that the list itself is sensitive. No annotations provided, so description carries full burden and does so thoroughly.

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

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

Concise at 6 lines, clear structure with description followed by Args. Minor wordiness could be trimmed, but overall 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 output schema exists, description doesn't need to detail return values. Covers purpose, usage, behavior, and parameters comprehensively for a simple 2-param 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?

With 0% schema coverage, description provides essential meaning for both parameters: npub as patron's Nostr public key, dpop_token as a signed Nostr event. This fully compensates for lack of schema descriptions.

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

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

Clearly states the tool lists stored patron credential field names, not values. Distinguishes from siblings like update/delete credential 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?

Explicitly says to use to 'verify which fields are configured' and notes that proof of npub ownership is required. Does not explicitly state when not to use, but context is clear.

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

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

No annotations provided, so description carries full burden. It discloses the requirement for a dpop_token and the sensitive nature, but does not explicitly state whether the tool is read-only or have side effects. Adequate but could be more explicit.

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

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

Well-structured: one-line purpose, then contextual details, then parameter list. Every sentence adds value, no fluff.

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

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

Covers the two main service types and prerequisites. With an output schema present, the description does not need to detail return values. Could mention error cases, but overall complete for its complexity.

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

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

Schema description coverage is 0%, but the description explains both parameters in the Args section, including the dpop_token being a kind-27235 Nostr event, adding significant meaning beyond the schema.

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

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

The description clearly states it reports a patron's credential readiness for an operator, with specific examples (eXcalibur, TheBrain, Schwab) that distinguish it from sibling tools like authority_get_patron_credential_fields.

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

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

Provides clear context: it's free, requires proof of npub ownership, and explains different service types. Does not explicitly contrast with siblings but implies when this tool is appropriate (onboarding status vs credential fields).

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

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

No annotations are provided, so the description carries full burden. It transparently discloses that if no model exists, it self-initializes a scaffold with all tools at 0 sats, and that no economic data comes from code. This reveals side effects and data source.

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 purpose, no wasted words. Each sentence adds distinct value.

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

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

The tool has no parameters and an output schema exists (so return format is covered). The description covers behavior, edge case (no model), and data source, making it fully 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?

The tool has no parameters, so the baseline is 4. The description adds no parameter info (none needed), and schema coverage is 100%.

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 gets the active pricing model for the operator, and distinguishes it from siblings by mentioning self-initialization and data origin ('No economic data from code'). Verb 'Get' + resource 'pricing model' is specific.

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

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

The description implies usage for checking pricing and mentions self-initialization behavior. It could explicitly state alternatives like `authority_set_pricing_model` for changes, but the context of read-only getter is clear.

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

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

No annotations provided, so description carries full burden. It discloses owner-only access and consent proof requirement, but does not explicitly state read-only nature or other behavioral traits. 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?

Two concise sentences with no filler. Front-loaded with purpose and context. Every word earns its place.

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

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

Given the output schema exists and the tool is simple, the description provides essential context (owner queue, consent proof, review surface). Slightly lacking in describing the list's content or behavior, but sufficient with output schema.

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

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

Schema has 100% coverage for the single parameter authority_proof, which is already documented in the schema. Description adds no additional parameter meaning beyond what 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?

Description clearly states the tool lists pending operator-adoption requests and identifies it as the 'Owner queue'. It is distinct from siblings like authority_approve_adoption and authority_reject_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 explicitly restricts usage to the Authority owner with consent proof, and frames it as a review surface for Pricing Studio. It provides clear context but lacks explicit '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 description carries full burden. It states 'Free, no side effects,' covering readOnly/destructive aspects. It explains that mcp_name changes but tool_id stays, providing key 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-structured with brief paragraphs and bullet points. It is informative yet concise, though a few phrases could be streamlined. Overall, it effectively uses space.

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 existing output schema (not shown), the description is complete. It explains the output's purpose and behavior, leaving no gaps about what the tool returns or why it exists.

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 does not need to add parameter meaning. The baseline score of 4 is appropriate as there is no parameter information to add.

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

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

The description clearly states the tool returns canonical (tool_id, mcp_name, …) for every registered tool. It specifies the purpose as an authoritative source for clients to identify tools, distinguishing it from sibling authority tools by focusing on identity rather than 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 explicitly states when to use: 'The authoritative source for any client (Studio, agents, FE) that needs to know how this MCP identifies its tools.' It also hints at not guessing UUIDs. However, it could be improved by explicitly stating when not to use it or what alternatives exist.

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 only mentions it is free with no credits required, but does not disclose whether the tool is read-only, requires authentication, or has side effects. The behavioral context is insufficient.

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

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

The description is three concise sentences: first states purpose, second details output, third notes cost. No filler, front-loaded with key information.

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

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

For a tool with no parameters and an output schema, the description covers what it returns and its context (pricing pipeline). Missing details about pagination or dynamism, but acceptable for this simple listing 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 input schema has no parameters, and schema coverage is 100%, so the description needs no additional parameter meaning. Baseline score 3 is appropriate.

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

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

The description clearly states the tool lists all available constraint types and their parameter schemas, using a specific verb ('List') and resource ('constraint types'), and distinguishes it from sibling authority tools which focus on other 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 notes the tool is free and provides constraint information for pricing pipelines, but does not explicitly state when to use it versus alternatives or provide any exclusion criteria.

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 describes the output schema (times_redeemed, total_uses) and ordering, but does not disclose if the operation is read-only, any side effects, or details about the required proof.

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 with an additional restriction line, all front-loaded and no redundant words.

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

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

For a list tool with an output schema, the description covers purpose and restrictions but fails to explain the sole parameter, which is a notable omission. The output schema mitigates return value explanation needs.

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

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

The schema has 0% coverage and one parameter (dpop_token) with no description. The description does not explain the parameter's purpose or usage, leaving a significant gap for an 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 states 'List every coupon this operator has minted (newest first)', which is a specific verb and resource with ordering. It distinguishes from siblings like 'authority_list_my_coupons' by specifying operator 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?

The description explicitly restricts usage to operators ('RESTRICTED to operator — requires proof'), giving clear context on who should use it. It doesn't mention alternatives or when not to use, but the restriction is clear.

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

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

With no annotations, the description takes full burden and explains that the tool lists redeemed coupons, returns status values, is free, and requires npub proof. It covers the read-only nature and return fields well, though it does not mention if any mutations occur (likely none).

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 immediate purpose, followed by concise details on return status and free requirement. No wasted words; front-loaded and efficient.

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

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

Given output schema existence, the description covers core functionality and return values. However, it omits explanation for 'dpop_token' and could elaborate on the meaning of each status field, leaving gaps for an agent.

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

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

Schema description coverage is 0%, so description should explain parameters. It partially covers 'npub' as proof, but does not mention 'dpop_token' at all, leaving one of two parameters undocumented.

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

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

The description clearly states it lists coupons redeemed by a patron on this operator, and distinguishes itself from siblings like authority_list_coupons by specifying 'this patron' and 'this operator'. It also details that it returns both active and exhausted redemptions with specific status values.

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

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

The description implies usage for coupon redemption listing but provides no explicit guidance on when to use vs. alternatives. It mentions 'requires proof of npub' as a condition but does not exclude other scenarios or mention sibling tools for comparison.

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 is the sole source for behavioral traits. It mentions 'recent' but does not define recency, ordering, pagination, or error behavior. The default limit of 20 is noted but not explained as a maximum or throttle, and status filter examples are incomplete. This is insufficient for fully predictable tool behavior.

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

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

The description is concise, with a one-line purpose followed by structured parameter definitions. Every sentence is useful, though the formatting could be improved for readability (e.g., bullet points). There is no unnecessary text.

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

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

Given the output schema exists, return values are covered. However, critical aspects for a listing tool are missing: pagination, sorting order, definition of 'recent', and whether status accepts multiple values. Sibling tools with similar list functions make this lack of detail a significant gap.

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

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

Despite 0% schema description coverage, the description adds meaning to both parameters: limit is defined as 'Maximum records to return' with a default, and status is explained as an optional filter with examples. This goes beyond the schema's type/default information, compensating well for the lack of schema descriptions.

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

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

Description explicitly states 'List recent Bitcoin notarization records', clearly identifying the verb (list) and resource (notarization records). This distinguishes it from sibling tools like authority_get_notarization_proof (retrieve) and authority_notarize_ledger (create), achieving high specificity.

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

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

No guidance on when to use this tool versus alternatives such as authority_list_adoption_requests or authority_get_notarization_proof. The description lacks explicit context or exclusions, leaving the agent to infer usage solely from the tool name.

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

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

Since no annotations are provided, the description carries the full burden for behavioral transparency. It discloses that the tool creates a coupon, returns the new row, and requires operator authentication. It does not discuss side effects like overwrite behavior on duplicate names, but the uniqueness constraint is noted in parameter semantics.

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

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

The description is concise and well-structured: a brief one-sentence purpose, followed by a bulleted Args list, and a final sentence on returns and restrictions. Every sentence adds value, and the most critical info is front-loaded.

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

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

Given the complexity (7 parameters, 4 required) and the presence of an output schema, the description covers all key aspects: parameters, defaults, auth requirements. It does not mention error conditions or idempotency, but for a creation tool, the provided information is sufficient for an agent to use correctly.

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

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

With 0% schema description coverage, the description fully compensates by explaining each parameter in detail: name (unique per operator), discount_percent (0-100), valid_from/valid_until (ISO-8601), uses_per_patron (default 1, null for unlimited), total_uses (default null=unlimited). It also mentions the dpop_token indirectly in the auth requirement.

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

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

The description clearly states the verb (Create) and resource (operator-owned discount coupon). It distinguishes from siblings like authority_redeem_coupon, authority_update_coupon, and authority_delete_coupon by specifying that it creates a coupon.

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

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

The description explicitly states that the tool is restricted to operators and requires proof (nsec-signed kind-27235 or cached dpop_token). It does not explicitly say when not to use it or mention alternatives for non-operators, but the context implies that only operators can create coupons.

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

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

With no annotations, the description carries full burden. It discloses operator-only access, async nature, Bitcoin confirmation delay, and no credit cost. It lacks details on idempotency or potential side effects, but the key behaviors are covered.

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

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

Three concise sentences, front-loaded with the primary action. No filler or redundancy; every sentence provides value.

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

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

Given zero parameters and an output schema (not shown), the description covers the main action, constraints, timing, and cost. It could mention repeatability or prerequisites, but is largely complete for a parameterless background task.

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

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

No parameters exist in the schema, so baseline is 4. The description adds context about what the tool accomplishes, which is sufficient for a parameterless tool.

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

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

The description explicitly states the tool's action: building a Merkle tree of patron balances and submitting the root to Bitcoin via OpenTimestamps. It clearly distinguishes from sibling tools by specifying the core notarization function.

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

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

The description notes it is an operator-only background task and provides timing (1-6 hours) and cost (free) context. However, it does not specify when to use this tool versus alternatives like authority_get_notarization_proof or authority_list_notarizations.

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 carries behavioral disclosure. It explains the authentication requirement for external npub and the permissive self-inspection fallback. The 'view' action implies non-destructive behavior.

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

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

The description is extremely concise: two short paragraphs. The first sentence front-loads the purpose, and the second adds essential conditional behavior. Every sentence adds value with 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 tool's low complexity (2 params, 0 required) and the presence of an output schema, the description adequately covers purpose and behavioral nuances. It could mention the output schema for completeness, but the provided details are sufficient.

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

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

Schema coverage is 50% (only npub has a schema description). The description adds nuance about proof requirements but does not explicitly link to the dpop_token parameter, leaving its semantics unclear. The description fails to fully compensate for the undocumented parameter.

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

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

The description clearly states the tool views registration status, balance summary, and the Authority's Nostr npub. It is distinct from sibling tools like authority_check_balance, but does not explicitly differentiate from all siblings.

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

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

The description provides clear conditional usage: requires Schnorr proof when an explicit npub is provided, but falls back to self-inspection without proof when npub is empty. This guides appropriate invocation, though alternatives are not discussed.

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

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

No annotations are provided, so the description must convey behavioral traits. It only states 'Free,' implying no monetary cost, but does not disclose read-only nature, authentication needs, rate limits, or any side effects. The description is insufficient for safe invocation.

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

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

The description is extremely concise with only two short sentences: 'Describe the DPYC ecosystem via the Oracle. Free.' Every word serves a purpose, avoiding fluff. The purpose is front-loaded and immediately clear.

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

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

Given the tool has no parameters and an output schema exists, the description is minimally adequate for a simple informational tool. However, it does not clarify that this is a high-level overview compared to specific oracle queries, and the word 'Free' could be more contextually placed.

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 is empty (0 parameters), and schema coverage is 100%. According to guidelines, 0 parameters set a baseline of 4. The description adds no parameter semantics because none are needed. It appropriately leaves parameter details to 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: 'Describe the DPYC ecosystem via the Oracle.' It uses a specific verb ('describe') and resource ('DPYC ecosystem / Oracle'), distinguishing it from sibling tools that focus on specific queries like tax rate or membership lookup.

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

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

No guidance is provided on when to use this tool versus its siblings (e.g., authority_oracle_get_tax_rate). The word 'Free' hints at no cost but does not clarify if this is a starting point for general ecosystem overview or a redundant call.

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 only states 'Get' (implying read-only) but omits details like authentication requirements, rate limits, or what happens if the rate is unavailable.

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

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

Extremely concise at two brief statements. The word 'Free' might be extraneous but is short. No redundancy, but could add a bit more operational detail without losing conciseness.

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

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

Given no parameters and an output schema, the description is minimal but adequate for a straightforward getter. Lacks context about the rate's meaning or variability.

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

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

The tool has no parameters, and schema coverage is 100%. As per guidelines, zero params yields a baseline of 4; the description adds no param info, but none is needed.

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

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

Description clearly states 'Get the current DPYC certification tax rate' – a specific verb and resource. Sibling tools like authority_oracle_lookup_member have different purposes, so it is well-distinguished.

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

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

No guidance on when to use this tool versus alternatives. The word 'Free' indicates no cost but does not clarify context 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?

With no annotations, the description should disclose behavioral traits. It only states the action and 'Free', omitting side effects, authentication requirements, rate limits, or output behavior. Insufficient for an agent to understand implications.

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

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

Extremely concise at two sentences. Front-loaded with purpose. Minor improvement could be combining into one coherent sentence, but effective for a simple tool.

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

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

Given no input parameters and an output schema (unseen), the description minimally captures the return concept (onboarding instructions). However, with many siblings, more context about what the instructions include 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?

There are zero parameters, so schema coverage is 100%. The description naturally adds no parameter info, but with 0 params baseline 4 is appropriate. No additional value 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 'Get DPYC onboarding instructions from the Oracle' clearly states the verb (Get) and resource (DPYC onboarding instructions). It distinguishes from siblings by the specific purpose of 'how to join', but lacks explicit differentiation from other oracle 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?

No guidance on when to use this tool versus alternatives like authority_oracle_about or authority_oracle_lookup_member. The mention of 'Free' hints at no cost but does not provide actionable 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 only adds 'Free' beyond the action. It doesn't disclose whether this is a read-only operation, any side effects, permissions, or rate limits. A simple lookup might be assumed safe, but the description should explicitly state behavioral traits.

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

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

The description is extremely concise with zero wasted words. Two sentences: one for purpose, one for a notable attribute (free). No unnecessary 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 that the tool takes only one parameter and has an output schema (not shown), the description is minimal but may cover the basic case. However, it lacks information about error handling, what happens if npub is not found, or any prerequisites. For a simple lookup, it's adequate but not complete.

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

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

The only parameter 'npub' has schema description coverage at 0%, meaning no explanation in schema. The description does not elaborate on what npub is (e.g., format, length, or that it's a Nostr public key). This leaves the agent guessing about valid inputs.

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 'DPYC community member by npub', with a bonus note that it's free. This distinguishes it from sibling tools like authority_check_dpyc_membership and authority_get_nostr_profile.

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

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

No guidance on when to use this tool versus alternatives (e.g., authority_check_dpyc_membership for membership status, authority_get_nostr_profile for profile details). No when-not or context provided.

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

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

With no annotations, the description must disclose behavioral traits but only mentions 'Free' and a simple read operation. It does not cover rate limits, data freshness, or authentication requirements.

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

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

The description is very concise (8 words) and front-loaded. While efficient, it could add slight context like 'no authentication required' 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?

Given the tool has no parameters and an output schema exists, the description is minimally adequate. However, it lacks context on output format, usage frequency, or whether it requires authorization, 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?

The input schema has no parameters, so schema coverage is 100%. The description adds no parameter info (none needed) but clearly states the tool's function. Baseline of 4 is appropriate for zero-parameter tools.

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

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

The description 'Get active network advisories from the Oracle. Free.' clearly states a specific verb ('Get') and resource ('active network advisories'), distinguishing it from sibling oracle tools like 'authority_oracle_about' and '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?

No guidance on when to use this tool versus alternatives (e.g., other oracle tools). The description lacks context on prerequisites 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?

With no annotations, description fully discloses the verification step, relay publishing, and lack of key custody. Missing details on error handling or success/failure feedback, but covers primary 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?

Concise yet comprehensive; first sentence states purpose, followed by clear background and parameter list. Every sentence adds unique value without redundancy.

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

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

Covers all key aspects of a non-trivial tool (signature verification, relay publishing, security model). Output schema exists, so not needing to detail returns is acceptable. Slight gap on potential failure modes.

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 (npub, signed_event) are explained in the description with their roles and constraints (must match signature). Schema has 0% coverage, so description fully compensates.

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

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

Clearly states it publishes a client-signed kind-0 profile to relays for an npub, using specific verb 'publish' and resource 'kind-0 profile'. Distinguishes from siblings like authority_get_nostr_profile which retrieves instead.

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?

Explains prerequisite (client-signed event) and emphasizes that the wheel never holds the nsec, guiding appropriate use. Does not explicitly mention when not to use or name alternatives like authority_get_nostr_profile, but context is clear.

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

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

No annotations are provided, so the description carries full burden. It discloses side effects (creates Lightning invoice), required proof of ownership, and that it's free to call. This is sufficient behavioral context beyond the input schema.

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

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

The description is concise with 5 short sentences plus a parameter list. Every sentence adds value, and the structure is easy to parse.

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 payment flow complexity, the description covers the essential steps and confirms that check_payment should be called next. An output schema exists, so return values are documented. Missing error handling details, but adequate for core use.

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

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

Schema description coverage is 0%, but the description explains all three parameters: npub, dpop_token, and amount_sats (with default). This fully compensates for the lack of schema descriptions.

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

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

The description clearly states the tool buys credits via Bitcoin Lightning, specifying the action and method. It distinguishes from siblings through context, but doesn't explicitly differentiate from other purchase-related sibling 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 explains the flow: creates invoice, pay with Lightning wallet, then call check_payment. It also notes that calling is free and requires proof of npub ownership. However, it does not provide exclusions or alternatives.

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

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

With no annotations provided, the description fully discloses behavioral traits: it describes the inline Schnorr verification, the recording of a durable 'pending' row, and the best-effort owner-notification DM. It also clarifies what does NOT happen (provisioning). No contradictions exist.

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

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

The description is concise and front-loaded with the core purpose. Each sentence provides essential information without redundancy. It uses clear sectioning (purpose, verification, storage, side-effect, exclusion) in a compact form.

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

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

Given the tool's complexity and the presence of an output schema, the description covers all necessary aspects: purpose, workflow integration, verification mechanics, persistence, side-effects, and what the tool does not do. It is sufficient for an agent to correctly select and invoke this tool.

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

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

The schema coverage is 100%, so the description adds value by explaining the relationship between parameters and the workflow. For example, it notes that 'dpop_token' is automatically minted by 'request_adoption' and that verification is inline. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose as recording an operator's adoption request. It uses specific verbs ('record', 'verify', 'fire') and distinctly identifies the resource. It differentiates from siblings by explicitly mentioning that it does NOT provision and that provisioning waits for 'approve_adoption', and it identifies the caller as 'request_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?

The description provides context on when to use the tool: it is called MCP-to-MCP by 'request_adoption' and is part of a workflow leading to 'approve_adoption'. It also states what the tool does not do (provision). However, it does not explicitly list alternative tools or conditions for not using 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?

Despite no annotations, the description thoroughly details behavior: deterministic one-shot retrieval, relay draining, DM handling (ACK/NACK), credential_card direct redemption, and post-success reinitialization.

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 sections, bullet points for args. Every sentence adds value without unnecessary fluff. Concise for the complexity.

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

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

Covers all aspects: flow completion, preconditions, behavior, parameter details, return outcomes. Output schema exists but no further details needed; the description stands alone.

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

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

All four parameters are clearly explained in the description, including the relationship between dpop_token and credential_card. Schema has no descriptions, so the description fully compensates.

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

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

The description clearly states the tool picks up credentials and completes the CREDENTIAL-DELIVERY flow, distinguishing it from the sibling receive_npub_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?

Explicitly states to call only after user confirms reply, and warns not to poll/loop/retry. Mentions prerequisite of request_credential_channel via session phrase. Lacks explicit alternatives among many siblings, but the core usage guidance is strong.

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 carries the burden and discloses critical behavioral traits: one-shot retrieval, draining only the pinned relay, deletion of mismatched DMs, NACK without revealing phrase, and token handling (hash stored, raw token forgotten).

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

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

The description is lengthy but every sentence serves a purpose, with clear sections. It could be slightly more concise, but the detail is justified by the tool's complexity.

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

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

Given the output schema exists, the description adequately explains the return value (dpop_token), covers edge cases (user hasn't replied, mismatched DMs), and provides complete guidance for usage. No gaps remain.

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

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

Schema coverage is 0% (default empty strings), but the description provides full semantics: 'patron_npub' as the patron's npub, and 'dpop_token' as the token returned by request_npub_proof that must be remembered. It adds essential 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 verb 'Receive' and resource 'npub ownership confirmation', and explicitly distinguishes from sibling 'authority_receive_credentials'. It specifies the context of completing the npub-OWNERSHIP-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?

The description explicitly says 'Call this only after the user confirms they have replied.' and 'Do NOT poll, loop, or retry.' It also provides clear context about when to use versus alternatives like 'receive_credentials'.

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 carries the burden. It explains the internal validation steps (window, total cap), the effect on future calls (auto-apply discount until uses exhausted), cost (free), auth requirement (npub), and idempotency (same code returns existing redemption). This is comprehensive behavioral disclosure.

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

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

The description is extremely concise, using multiple short sentences that each add essential information. It front-loads the purpose ('Claim a coupon') and efficiently packs validation, effect, cost, auth, and idempotency without any redundant words. Ideal structure for an AI agent.

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

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

The description covers purpose, behavior, prerequisites, cost, and idempotency. It also mentions the output schema indirectly (redemption row). However, it lacks explanation for the dpop_token parameter and does not describe error scenarios. Given the presence of an output schema, the gaps are minor, but not negligible.

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

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

The description explains the 'code' and 'npub' parameters clearly, but does not mention the optional 'dpop_token' parameter at all. With 0% schema description coverage, the description needed to cover all parameters, and the omission of dpop_token leaves a gap. It adds value for two of three parameters, earning a middle 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 begins with a clear verb 'Claim' and resource 'coupon', specifying the input is the code shared by the operator. It distinguishes itself from sibling tools like authority_list_coupons or authority_mint_coupon by focusing on redemption, and explains the effect on subsequent paid tool calls, leaving no ambiguity about its role.

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

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

The description states when to use the tool: to claim a coupon. It provides context such as being free, requiring proof of npub, and being idempotent. However, it does not explicitly compare to alternatives or state when not to use it, though the unique redemption function is clear among siblings.

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

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

No annotations are provided, and the description only states that a DM challenge is sent. It does not disclose side effects, prerequisites, or whether the action is reversible. For a mutation tool, more transparency 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, concise sentence that efficiently conveys the core purpose. It is front-loaded with important context (step number) and avoids unnecessary 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?

The description gives the step number but lacks context about the overall onboarding process, what the challenge entails, or what happens after. An output schema exists but is not shown, so completeness is adequate but not thorough.

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

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

The schema already provides a description for the single parameter. The tool description adds no additional meaning beyond what the schema offers, 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 action ('send a Nostr DM challenge') and the context ('Step 1/3 of Authority onboarding'). It distinguishes itself from sibling tools by specifying it's a specific step in a multi-step process.

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 it's the first step in onboarding, but does not explicitly state when to use it versus alternative tools or any conditions for use. No exclusions or alternatives are mentioned.

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

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

No annotations exist, so the description carries full disclosure. It reveals idempotency, required proofs, and origin of those proofs. It does not cover error handling or authorization failure responses, 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 efficiently structured: a lead sentence, idempotency note, bullet-like explanation of the two proofs, and a next-step callout. Every sentence adds unique 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 the absence of annotations and the presence of an output schema, the description adequately covers the workflow, prerequisites, idempotency, and next actions. It could be slightly more complete by noting what response to expect (though the output schema handles that), but overall it is solid.

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 75%; the description adds significant context for npub (prerequisite from how_to_join) and authority_proof (how apps generate it). However, dpop_token lacks a schema description and is only briefly mentioned in the prose. The description partially compensates for the missing schema entry.

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

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

The description opens with a clear verb-resource statement: 'Provision an operator in the Authority ledger.' It expands on what that means (create ledger entry, enable credit purchases and order certification) and identifies it as idempotent. This clearly differentiates from sibling tools like authority_deregister_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 prerequisites (two identity proofs) and a next step (purchase_credits), giving context for when this tool fits. It does not explicitly state when to avoid using it (e.g., if already registered), but the idempotency hint implies safety on repeat calls. An explicit exclusion would elevate this to a 5.

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

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

No annotations are provided, so the description bears full responsibility for disclosing behavior. It only mentions 'owner consent' but fails to describe side effects (e.g., whether the request is deleted, if the action is reversible, or any authorization requirements beyond the proof 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?

The description is a single sentence of 8 words, conveying the essential purpose without any redundant or extraneous information. It is optimally 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 tool has an output schema, so return values need not be explained. However, the description lacks context about the state transition (e.g., what happens to the adoption request after rejection) and does not provide usage context within the large family of siblings. Given the complexity of the surrounding toolset, more guidance would be helpful.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema's parameter descriptions; it does not explain the reason parameter's role or how the authority_proof relates to owner consent beyond what is in the schema.

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

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

The description clearly states the action 'Reject', the resource 'pending operator-adoption request', and the condition 'owner consent'. It distinguishes this tool from siblings like authority_approve_adoption and authority_request_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?

The description implies usage through the phrase 'owner consent', but lacks explicit guidance on when to use versus alternatives like authority_approve_adoption or when to avoid. No exclusions or context about prerequisites are given.

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

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

No annotations are provided, so the description carries full responsibility. It discloses that the tool is idempotent, only fixes ownership and grants, and does not perform password rotation or DM re-sending. However, it does not mention potential failure cases or required 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?

Three sentences, front-loaded with the main action, followed by context and what the tool does not do. Every sentence contributes essential information without 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 low parameter count, full schema coverage, and presence of an output schema, the description sufficiently explains the tool's role and when to use it. It could mention return values or postconditions, but the output schema likely 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?

Input schema coverage is 100% with parameter descriptions already explaining 'operator_npub' and 'authority_proof'. The description does not add any new information about the parameters 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?

Description clearly states the tool's purpose ('reassign every table... to operator's own role, then re-grant DML') and distinguishes it from the sibling tool 'register_operator' by explicitly 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?

Describes the specific scenario where this tool is needed (tables owned by provisioning role causing CREATE INDEX failure) and contrasts with a sibling tool. However, it does not explicitly list when not to use it or mention other alternatives beyond register_operator.

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 details the process: resolves MCP endpoint, mints ownership proof, delivers request, and records as pending. However, it omits potential side effects or failure modes.

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

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

The description is well-structured with a summary one-liner, a detailed paragraph, and an Args list. It is informative without being overly verbose.

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

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

Given the output schema exists, the description covers input, preconditions, process, and post-conditions (pending, poll for ready). 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?

Despite 0% schema description coverage, the description explains each parameter's role and format (e.g., dpop_token as 'operator-npub ownership proof (inline kind-27235 or cached token)'), providing 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 action ('Ask a chosen Authority to adopt this operator') and resource, distinguishing it from siblings like authority_adoption_status and authority_approve_adoption. The context of 'deferred courtship' adds clarity.

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 the tool is restricted to the operator and requires proof of npub control. Mentions polling adoption_status for progress, but does not explicitly compare with other tools like authority_register_operator.

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

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

No annotations provided, so description carries full burden. It discloses the human-in-the-loop flow, that it sends a welcome DM requiring manual reply, and explains destructive behavior of receive_credentials (drains relay mailbox).

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, usage, flow, and params. Every sentence adds value, though slightly verbose in parts.

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

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

With only 2 parameters and an output schema, the description covers the flow, prerequisites (check service_status), and interaction with receive_credentials. Adequately complete for an experienced developer.

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 0%, so description must compensate. It lists both parameters with brief context (sender_npub: npub to send to; service: credential service name from specific tools). Adds some meaning but lacks detailed constraints or formats.

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 opens a Secure Courier channel for credential delivery, distinguishes it from request_npub_proof (for npub control), and notes exceptions for dynamic/OAuth2 services.

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 (credential delivery) and when not (npub proof, dynamic services). Provides step-by-step instructions: call, then stop and inform user, wait for confirmation before calling receive_credentials, and warns against polling.

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

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

With no annotations, the description fully discloses behavioral traits: human-in-the-loop, need to instruct user, destructive nature of receive_npub_proof, return of dpop_token that must be remembered, MCP does not retain across restarts, and expiration lifecycle. No contradictions.

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

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

The description is well-structured with sections and front-loads the purpose. While somewhat lengthy, each sentence adds necessary context for a complex flow. Slightly verbose but justified.

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 multi-step flow, return value, and lifecycle, the description covers all aspects: how to use, what to expect, what to do next, and output semantics. An output schema exists but the description already explains the return value (dpop_token).

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%, but the description explains the sole parameter 'patron_npub' as 'Required. The patron's npub to request proof from', adding meaning beyond the schema's type and default.

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 'Request npub ownership proof from a patron via Nostr DM' with a clear verb and resource. It distinguishes from the sibling 'request_credential_channel' by explaining that this tool proves npub ownership, not delivers service secrets.

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 'use it when a call returns proof_required' and contrasts with request_credential_channel. Provides lifecycle instructions: call this, wait for user, call receive_npub_proof. Warns against polling and retries.

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

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

With no annotations provided, the description carries full burden. It discloses destructive action, deletion and re-initialization, restricted access, and return value. Could mention side effects like temporary pricing unavailability, but is generally transparent.

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