tollbooth-authority-newengland

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

With no annotations, the description fully informs behavior: it's free, requires proof of npub ownership, and returns specific data. It also clarifies it's the patron's spending account, not the operator's tax balance, adding critical operational context.

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

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

The description is concise with only four sentences, front-loading the main purpose and then adding key details. Every sentence adds value without redundancy.

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

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

Given the tool's moderate complexity, the description is complete. It covers purpose, output, cost, authentication requirements, and parameter semantics. The presence of an output schema complements the description, making for a fully informative tool definition.

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%, yet the description adds meaningful detail beyond the schema, especially for the complex 'dpop_token' parameter, explaining its format and constraints. The 'days' parameter's default is reiterated.

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 patron's account statement and lists specific outputs (purchase history, credit tranches, etc.). It also distinguishes it from the operator's tax balance, making the purpose unambiguous and differentiating it 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 explains the tool returns the patron's spending account and mentions proof of npub ownership is required. It implies usage when needing a patron's statement, but lacks explicit 'when not to use' or alternatives. However, the context of its unique purpose among many sibling tools provides sufficient guidance.

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

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

No annotations exist, so the description carries the burden. It discloses the cost (1 api_sat per call) and proof verification before cost. However, it does not state whether the tool is read-only, modifies state, or requires specific 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?

The description is concise (two sentences plus a summary) and front-loaded with the main purpose. No superfluous words; all details (cost, proof) earn their place.

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

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

Given an output schema exists, the description need not detail return values. It covers what the SVG contains, cost, and proof verification. Missing error conditions or rate limits, but overall adequate for the complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no extra parameter meaning; the schema already describes 'days', 'npub', and 'dpop_token' adequately.

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

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

The description clearly states the tool generates a visual SVG infographic of an account statement. It specifies the elements included (balance hero, metrics cards, health gauge, etc.) and distinguishes it from the sibling 'authority_account_statement' by mentioning it returns the same data but rendered as an SVG.

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 use for visual representation versus raw data from authority_account_statement, but does not explicitly state when to use this tool or when to avoid it. It mentions cost and proof verification but lacks direct alternatives or exclusions.

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

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

No annotations provided. Description says 'Polls the Authority MCP-to-MCP' implying external query but doesn't disclose side effects, permissions, rate limits, or idempotency. Lacks transparency for a read-like operation.

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

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

Very short description with line breaks for readability. No unnecessary words, but could be more structured (e.g., separate lines for parameters).

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

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

Output schema exists so return values need not be detailed. However, lacks context on polling behavior, potential latency, or how statuses map to actions. Adequate but not comprehensive.

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

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

Schema description coverage is 0%. Description explains 'authority_npub' identifies the authority but completely omits explanation of 'dpop_token', leaving its purpose unclear.

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

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

Description states verb 'Check' and resource 'adoption-request status' with a specific authority, listing possible statuses. However, sibling tool 'authority_get_adoption_status' likely performs a similar function, and description does not differentiate.

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_get_adoption_status' or other adoption-related siblings. Only mentions 'Free' but not context for choice.

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

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

With no annotations, the description carries full burden. It discloses the provisioning effect and that it is supplied later, but lacks details on permissions, reversibility, or side effects beyond stating it provisions.

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, but the second sentence is dense with technical references. It is concise overall but could be slightly more streamlined.

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

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

Given that an output schema exists and the tool has moderate complexity, the description adequately explains the tool's purpose and relationship to siblings. It does not cover prerequisites or error scenarios, but is sufficient for an approved request.

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

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

Schema coverage is 100%, and parameter descriptions in the schema are already detailed. The description adds minimal extra meaning, only contextualizing both parameters together as part of approval.

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 ('Approve a pending request and provision the operator') and distinguishes it from the sibling 'register_operator' by noting it is the deferred-courtship counterpart. This provides a specific verb and resource with differentiation.

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

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

The description explains when to use this tool (for later approval after review) and contrasts it with register_operator, providing contextual guidance. However, it does not explicitly state when not to use it or list alternatives.

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

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

With no annotations, the description carries the full burden. It discloses that the paid_tool decorator handles fee debit and stores cost, and that no recomputation is needed. It does not mention side effects or idempotency, but it provides meaningful behavioral insight.

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, front-loaded with the core purpose. Every sentence adds value: purpose, behavioral note, and usage context. No redundancy or wasted words.

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

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

Given the presence of an output schema and the tool's specific role, the description covers the return value (Schnorr-signed certificate), the calling context, and key behavioral traits. It does not mention error conditions or prerequisites, but overall is complete enough for an agent with access to the output schema.

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

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

Schema description coverage is 67% (below 80%), so the description should compensate for the missing parameter semantics. However, the description adds no information about parameters; it relies on the schema descriptions already provided. This is insufficient to fully guide parameter usage.

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

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

The description clearly states the tool's purpose: 'Certify a purchase order: return a Schnorr-signed Nostr event certificate.' It uses a specific verb and resource, and the context that it is called when a patron purchases credits differentiates it from sibling tools like authority_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 states usage context: 'Called by operator MCP servers (not end users) when a patron purchases credits.' It also notes 'No recomputation needed.' However, it does not explicitly state when not to use it or compare to alternatives, leaving some guidance gaps.

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

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

No annotations provided, and description only states 'check parent approval, activate Authority'. It does not disclose whether activation is destructive, permissions needed, or any side effects. Minimal 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?

Description is single sentence, front-loads 'Step 3/3', and is efficient with no waste.

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

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

Output schema exists, so return values are covered. However, missing context about prerequisites, error scenarios (e.g., parent approval failure), and relationship to other onboarding steps. Adequate but incomplete.

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

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

Schema coverage is 100% with one parameter described. Description does not add meaning beyond the schema description of candidate_npub. Baseline 3 is appropriate.

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

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

Description states it is 'Step 3/3 of Authority onboarding' and specifies two actions: 'check parent approval' and 'activate Authority'. The verb+resource is clear, but it does not differentiate from sibling tools like authority_get_operator_onboarding_status or authority_register_operator.

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

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

Implied by 'Step 3/3' that it is used after prior steps, but no explicit guidance on when to use vs alternatives or exclusions.

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

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

No annotations provided, so description carries full burden. Describes return value (sats available) and consequence of zero balance. Does not mention auth or rate limits, but appropriate for a simple read operation.

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

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

Five short sentences, each providing essential information. Purpose, return, consequence, and ownership are front-loaded and 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?

Completes its purpose with minimal info: tells what it returns, what happens when balance is zero, and that it's free. Output schema exists, so return details 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?

Tool has zero parameters; baseline is 4. Description adds no param info because none needed.

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

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

States clearly: 'Check this operator's tax balance at the Authority.' Distinguishes from sibling tools like 'authority_check_balance' by specifying 'tax balance' and linking to patron credit certification.

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 when balance is zero, the operator must call 'purchase_credits' on the Authority. Also clarifies it is not a patron balance. Lacks explicit when-not-to-use or comparison to other balance tools.

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

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

With no annotations, the description carries full burden. It discloses that the tool is free (no credits required), requires proof of npub ownership via dpop_token, and prevents enumeration. This adds useful behavioral context, though it does not detail error scenarios or rate limits.

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

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

The description is three paragraphs; the first sentence is concise, but the second paragraph contains a confusing self-reference and could be merged. The third paragraph adds valuable info, but overall it could be more streamlined.

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

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

An output schema exists, so return values need not be explained. However, the description omits error handling and does not fully cover the behavioral context for a balance check tool, making it moderately 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 baseline is 3. The description adds little beyond what the schema already provides for parameters; the dpop_token requirement is reinforced but not elaborated further.

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 a patron's credit balance at the operator. It distinguishes the patron's spending balance from the operator's own balance, though the reference to 'use authority_check_balance instead' is confusingly self-referential and may mislead.

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

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

The description indicates when to use this tool (check patron balance) and mentions it's free and requires proof of ownership. However, it does not explicitly state when not to use it, and the attempt to differentiate from another tool is unclear due to the self-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, and the description only says 'look up', which implies a read operation. It does not disclose error behavior, authentication needs, or what happens if the npub is not found.

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

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

The description is a single, concise sentence that is front-loaded with the key action and resource. No unnecessary words.

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

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

Given the simple nature of the tool and the existence of an output schema, the description is too brief. It fails to differentiate from similar tools like authority_oracle_lookup_member and does not mention any prerequisites or scope.

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

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

Schema description coverage is 0%, and the description does not mention the single parameter 'npub' at all. No additional context is provided beyond the parameter name and type 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 ('look up') and the specific resource ('npub in the DPYC community registry'), making it distinct from sibling tools like authority_check_balance or authority_oracle_lookup_member.

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

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

No guidance is provided on when to use this tool versus alternatives such as authority_oracle_lookup_member or authority_check_authority_approval. The context of use is entirely 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?

No annotations provided; description adds context (free, security rationale for npub) but doesn't mention if the call is idempotent, possible error conditions, or explicit read-only nature (though implied by 'check').

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?

Short, front-loaded purpose, no fluff. Every sentence is informative 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?

Output schema exists so return values are covered, but description lacks info on what status values mean (e.g., settled/pending) or error handling for invalid invoice_ids.

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

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

Schema description coverage is 100%; main description reinforces workflow (invoice_id from purchase_credits) and explains dpop_token creation, but doesn't add new semantic meaning beyond the schema.

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

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

The description clearly states 'Check the payment status of a Lightning invoice.' It uses a specific verb and resource, and the context of paying after 'purchase_credits' distinguishes it from sibling tools like 'authority_check_balance'.

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

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

Explicitly says 'Call after paying the invoice from purchase_credits.' and notes prerequisites: free, proof of npub ownership required. No when-not-to-use needed as no sibling tool overlaps.

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

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

No annotations provided; description covers cost preview and free usage but does not explicitly confirm it is read-only or describe error handling. 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?

Extremely concise; two sentences plus a short note. No fluff, front-loaded, each sentence is informative.

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

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

Given output schema exists and tool has 4 params, description covers core purpose and flexibility of kwargs. Lacks notes on error cases but overall sufficient.

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

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

Parameter descriptions in schema for tool_id and tool_kwargs are detailed; description adds examples and context for kwargs. With 50% schema coverage, this adds meaningful value.

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

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

Description starts with a specific verb 'Preview' and resource 'effective cost of a tool call', clearly distinguishing its function from sibling tools like pricing model getters.

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 shows cost details and is free, implying use when cost estimation is needed. Lacks explicit when-not-to-use or alternatives, but 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 discloses that the tool is free, has no side effects, does not evict the cache, and does not touch relays. This transparently communicates the tool's read-only, safe nature.

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 exceptionally concise: three sentences that front-load the main purpose, include usage guidance, and note safety. Every sentence adds value without unnecessary detail.

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

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

The description explains the tool's role in the npub-proof flow and mentions the output schema exists. Given the tool is a simple check with only two well-documented parameters and an output schema, the description adequately covers the required context.

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

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

Schema coverage is 100% with adequate descriptions for both parameters. The description adds minimal extra value beyond the schema, only hinting at the token's origin. With high coverage, 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 explicitly states the tool's purpose: 'Check whether a previously-cached dpop_token is still valid.' It distinguishes from siblings by noting it mirrors `check_oauth_status` for the npub-proof flow, making the tool's role clear.

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

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

The description provides clear guidance on when to use the tool: before a paid call to verify token validity, preventing credit waste. It also notes it is free and has no side effects. While it does not explicitly list alternatives or when not to use, 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?

Discloses the verification and escalation behavior and parent resolution logic, but lacks details on side effects, authentication requirements, or return behavior. No annotations provided.

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 concisely convey purpose and key logic with no wasted words; front-loaded with step identification.

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 step and parent resolution, and output schema exists. Slightly incomplete by not mentioning prerequisites or connecting to other steps explicitly.

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?

Single parameter 'candidate_npub' has complete schema description; the tool description does not add extra meaning beyond the schema, making baseline 3 appropriate.

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

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

Explicitly states it is Step 2/3 of Authority onboarding, with verb 'verify candidate DM, escalate to parent Authority,' clearly distinguishing it from sibling tools that handle other authority operations.

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

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

Provides context as step 2 of a 3-step process and explains parent Authority resolution, but does not explicitly state when to use vs. alternatives or when not to use.

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

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

Despite no annotations, the description discloses important behavioral traits: cascading deletion, no-op for chain steps, and warnings. It also notes access restriction, which adds transparency.

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

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

Three sentences with no wasted words. The first sentence gives the core action and immediate consequence, the second explains the side effect on references, and the third specifies access control. Very 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 existence of an output schema, the description covers all necessary aspects: action, side effects, error behavior (warnings), and access restrictions. It is complete for a delete operation.

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

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

Schema coverage is 0% and the description adds no information about the parameters (coupon_id, dpop_token). The schema is simple, but the description fails to provide any parameter context, which is needed given low coverage.

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

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

The description clearly states the action ('Delete a coupon') and the resource. It distinguishes from siblings by noting the cascading deletion to all patron redemptions, which is specific to this 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?

It provides clear context by stating 'RESTRICTED to operator — requires proof,' indicating who can use it and what is required. However, it does not explicitly mention alternatives or when not to use, but this is sufficient given the sibling list.

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

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

No annotations provided, so description carries full burden. It states it's a write operation, requires dpop_token, and is free. Does not disclose error handling or side effects of deleting a non-existent field, but basic behavior is clear.

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

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

Two short paragraphs with no fluff. Purpose is front-loaded, and every sentence adds value.

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

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

Given an output schema exists, description does not need return details. It covers purpose, usage, and parameter semantics well. Could mention idempotency or error cases, but overall sufficient.

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

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

Schema coverage is 100%, baseline 3. Description adds significant detail for dpop_token (raw JSON, not base64, requirements), which exceeds schema. For npub and field, it aligns with 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 removes a single credential field, using verbs 'remove' and 'deletes' with the specific resource. It distinguishes from sibling tools like authority_update_patron_credential and authority_receive_credentials.

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

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

Indicates that proof of npub ownership is required and that it's a write to a sensitive vault. Does not explicitly mention when not to use or name alternatives, but context implies it's for field deletion.

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

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

No annotations provided, so description carries the burden. It discloses the need for two proofs and the security risk of missing authority_proof. Does not detail side effects, idempotency, or rate limits, but covers the essential behavioral trait for a removal tool.

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

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

Two well-structured paragraphs with the purpose stated first. Every sentence adds value, no redundancy. Efficient use of space to convey 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?

Given the tool's complexity and the presence of an output schema, the description covers the essential context: what the tool does, required proofs, and security rationale. Lacks details on error handling or post-removal state, but is sufficient 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 covers 2 of 3 parameters (npub, authority_proof) with descriptions; dpop_token is undocumented. The description adds context for authority_proof by explaining its role and necessity, but does not explain dpop_token or provide additional guidance beyond schema.

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

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

The description starts with 'Remove an Operator from the DPYC community registry', which is a clear verb+resource statement. It distinguishes itself from sibling `authority_register_operator` by being the inverse operation.

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

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

Explicitly states required proofs and the consequence of lacking authority_proof. Implies when to use (with required proofs) and warns against unauthorized removal. Could mention alternatives like `authority_register_operator` for the opposite action, but the context is clear.

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

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

With no annotations, the description carries full burden. It discloses that removal is cosmetic, coupon still exists at operator, and patron can re-redeem later. It also states it is free. This provides useful behavioral traits beyond the name.

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

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

The description is two sentences, front-loaded with the main action. Every sentence adds value with no waste.

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

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

Given the tool's simplicity (removing a coupon from list) and presence of output schema, the description covers the key behavioral aspects. However, it neglects to mention dpop_token parameter, which might be important for usage.

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

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

Schema description coverage is 0%, so description should compensate. However, it only mentions 'requires proof of npub' but does not explain npub, coupon_id, or dpop_token parameters. It adds minimal semantic value beyond the schema structure.

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 removes a coupon from the patron's redemption list, using specific verb 'Remove' and resource 'coupon from redemption list'. It distinguishes from siblings like authority_delete_coupon by noting it is cosmetic 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?

The description provides usage context: 'cosmetic only' indicates when not to use (when permanent deletion is needed), and mentions re-redeem possibility. It also states it requires proof of npub. However, it does not explicitly name alternative tools (e.g., authority_delete_coupon) though sibling list gives that context.

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

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

No annotations are provided, so the description carries full burden. It discloses that deletion is as destructive as a write, which implies irreversibility. However, it omits details about idempotency, error responses, or behavior when credentials don't exist. The transparency is adequate but not comprehensive.

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

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

The description is concise with three sentences covering purpose, parameter usage, and destructiveness. Each sentence is necessary and contributes to understanding. No redundant or filler content.

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

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

Given the presence of an output schema (not shown but stated), return values do not need explanation. The description covers the tool's core functionality, parameter distinctions, and critical behavioral trait (destructiveness), making it complete for the agent to decide and invoke correctly.

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

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

The input schema has 100% coverage with detailed descriptions, especially for dpop_token. The tool description adds value by explaining how to use npub (operator vs patron) beyond the schema's basic type description. This distinction is critical for correct usage.

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

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

The description explicitly states it deletes vaulted credentials for a specific service and npub, distinguishing between operator and patron credentials. The verb 'Delete' and resource 'vaulted credentials' are clear, and the tool differentiates itself from similar tools like authority_delete_patron_credential by focusing on service+npub combination.

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 guidance on when to pass operator vs patron npub and emphasizes proof of ownership. However, it lacks explicit comparison to sibling tools like authority_delete_patron_credential, and does not state when not to use this tool.

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

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

In the absence of annotations, the description adequately discloses the read-only nature and that no authentication or payment is needed. It also notes that the status is not sensitive. However, it does not explicitly mention idempotency or lack of side effects beyond what is implied by 'Read'.

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

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

The description is only two sentences, front-loads the core purpose, and contains no unnecessary words. It is highly efficient.

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

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

Given the presence of an output schema, the description does not need to cover return values. It covers the key behavioral aspects for a simple read tool. The only minor gap is the lack of differentiation from the similarly named sibling tool.

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

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

Schema coverage is 100%, and the schema already describes the single parameter. The description adds little beyond what the schema provides, meeting the baseline but not exceeding it.

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 ('Read') and the resource ('operator's adoption-request status'), and adds detail about the status values and their non-sensitive nature. It effectively distinguishes from other tools by naming the status types and stating it is free and requires no 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?

The description implies the operator uses this to poll their own status, but it does not explicitly clarify when to use this tool versus the sibling 'authority_adoption_status' tool, which appears to have the same purpose. No exclusions or alternative guidance are provided.

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

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

No annotations are provided, so the description carries the full burden. It states that the tool is free, requires no proof, and returns public data. It also mentions that it returns the latest metadata fields or an empty profile if none is published. These are important behavioral traits. However, it does not explicitly state that it is read-only (though implied by 'Read') or discuss rate limits.

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

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

The description is three sentences, front-loaded with the main purpose. It efficiently conveys purpose, cost, and return fields without any wasted words. Every 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?

An output schema exists, so the description need not detail return values, but it does list the metadata fields, which adds clarity. It covers the core behavior (reading public profile, free, no proof) and edge case (empty profile). It does not mention error conditions for invalid npub, but for a simple tool this is acceptable.

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

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

Schema description coverage is 0%, so the description must compensate. The description mentions 'npub' in the first sentence, indicating the parameter's purpose (the Nostr public key). However, it does not explain the expected format (e.g., bech32 or hex) or provide examples. Given only one parameter and partial description coverage, a 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 reads a public Nostr profile (NIP-01 kind-0 metadata). It specifies the action ('Read an npub's public Nostr profile') and the resource (Nostr profile). However, it does not explicitly distinguish itself from the sibling tool 'authority_publish_nostr_profile' (write counterpart), though the verb 'Read' inherently implies the distinction.

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

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

The description provides clear usage context: 'Free, no proof — the data is already public on relays.' This tells the agent that the tool requires no authentication and has no cost, and is suitable for retrieving public data. It does not explicitly state when not to use it or mention alternatives, but the context is sufficient for a simple read operation.

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

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

No annotations are present, so the description must fully disclose behavior. It only mentions generation of a proof, but does not explain whether it is read-only, requires authentication, or has any side effects. Insufficient for a tool with no annotations.

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

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

Single sentence, concise, no redundant information. Every word contributes to understanding the tool's 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?

With an output schema present, the description need not explain return values, but it lacks any mention of prerequisites or related tools. Acceptable but minimal for a specialized cryptographic tool.

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

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

Schema description coverage is 100%, so the description adds no additional meaning beyond the schema's parameter descriptions. The tool description does not elaborate on parameter usage or constraints.

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

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

The description clearly states the tool generates a Merkle inclusion proof for a patron's balance in a Bitcoin-notarized snapshot, using specific verb ('generate') and resource. It is distinct from siblings like authority_list_notarizations or authority_check_proof_status.

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

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

No guidance on when to use this tool versus alternatives, such as needing a notarization ID from authority_list_notarizations first. No prerequisites 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?

The description discloses the authentication requirement (Schnorr signature) and implies the tool is read-only via 'Retrieve'. Since no annotations are provided, this is sufficient behavioral context, though it could mention that it does not modify state.

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, minimal waste, front-loaded with the core action. Every word serves a purpose.

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

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

The tool has an output schema, so return values need not be described. The description covers the gating condition and the core retrieval. However, the missing explanation for dpop_token slightly reduces 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 covers only 50% of parameters with descriptions (npub has a description, dpop_token does not). The main description adds no extra parameter information; it only implies npub's role. The dpop_token parameter remains unexplained, a significant gap.

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

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

The description clearly states 'Retrieve operator bootstrap configuration (Neon URL, schema)', specifying both the action and resource. It distinguishes from sibling tools like authority_operator_status or authority_get_operator_onboarding_status by targeting the bootstrap config specifically.

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 gating condition ('Gated by Schnorr signature proving ownership of the requested npub'), which implicitly guides when to use the tool. However, it does not explicitly state when not to use it or suggest alternatives among the many sibling tools.

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

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

No annotations provided, so the description carries full burden. It explains what the tool shows (configured/missing settings and delivery guidance) without contradicting any annotations. Additional context like authentication is not stated but assumed for the domain.

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

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

Three succinct sentences: purpose, details, and alternative. No wasted words; 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?

With no parameters and an output schema, the description fully informs about the tool's function and output. It covers what the tool does, what it shows, and how it differs from a sibling.

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

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

No parameters exist, so there is no ambiguity. The schema coverage is 100%, and the description adds no misleading parameter info. With 0 parameters, the baseline is 4, but perfection warrants 5.

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

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

The description clearly states the tool's purpose with a specific verb ('Report') and resource ('operator's configuration readiness'). It also distinguishes itself from sibling tool 'get_patron_onboarding_status'.

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

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

Explicitly tells when to use this tool (for operator readiness) and when to use an alternative (for patron-level credentials). The phrase 'Free' hints at no cost barrier.

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 thoroughly discloses: returns field names with timestamps (null for old ones), never exposes values, free, requires dpop_token authorization, and the list's sensitivity. 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?

Two well-structured paragraphs. Front-loaded with purpose. Every sentence adds value. Uses formatting (backticks for field names) for readability. No fluff.

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

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

Given the complexity (custom authorization format, sensitive data), description covers purpose, return format, authorization, and sensitivity. Output schema exists, so return values are documented elsewhere. Complete.

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

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

Schema coverage is 100%, but description adds significant detail beyond schema: dpop_token must be raw JSON of kind-27235 event with specific constraints (not base64, not NIP-98 framing, exact u tag, content, timeliness). npub required for ownership proof.

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

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

Clearly states it lists stored patron credential field names (not values), and explains what each field includes (delivered_at timestamp). Distinguishes from sibling credential tools like authority_update_patron_credential and authority_delete_patron_credential.

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 cases: verify configured fields and their age. Notes that proof of npub ownership is required because the list itself is sensitive. Does not explicitly list when not to use but context is clear.

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

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

No annotations are provided, so the description carries full burden. It discloses that proof of npub ownership is required and that the tool is free, but does not mention read-only behavior, side effects, permissions, or error handling. Some behavioral context is given for different service types.

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 4 sentences, each adding value. It is front-loaded with the purpose, then explains behavior for different services, and ends with requirements. 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 has an output schema (so return values are covered) and no nested objects, the description is fairly complete. It covers purpose, service types, cost, and authentication. However, it does not mention potential errors or edge cases (e.g., patron not found).

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 what the schema already provides for the parameters. It mentions 'Proof of npub ownership' which relates to dpop_token, but that is already 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 tool 'Report a patron's credential readiness for this operator,' using a specific verb and resource. It distinguishes between set-once and dynamic services, making it distinct from siblings 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?

The description provides context (checking credential readiness, free, requires proof) but does not explicitly state when to use this tool versus alternatives or provide exclusions. No mention of 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 side effect: self-initializes a scaffold if no model exists. Also notes 'No economic data from code', indicating data source limitation.

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

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

Three short sentences, front-loaded with purpose. 'Free' is a bit redundant but acceptable. Overall 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?

Simple tool with no parameters and output schema present. Description covers purpose and notable behavior (self-initialization). 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?

No parameters (0 params), so baseline 4. Description adds no extra info but none needed.

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

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

Clearly states verb 'Get' and resource 'active pricing model for this operator'. Differentiates from siblings like 'authority_set_pricing_model' and 'authority_reset_pricing_model'.

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

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

Mentions 'Free' but does not explicitly guide when to use vs alternatives like 'authority_set_pricing_model'. No explicit when-not 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, the description carries full burden. It mentions access restriction and suggests non-destructive intent ('review-on-your-own-time'), but does not explicitly state read-only or safety traits. Partial coverage only.

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

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

Two concise sentences, front-loaded with key information, no verbosity.

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

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

Given an output schema exists, the description adequately covers purpose, audience, and constraint. Slightly more detail on output nature or behavior could push to 5, but it's largely sufficient.

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

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

Schema coverage is 100%, and the description adds no new meaning beyond the schema's parameter description. Baseline score of 3 applies.

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

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

The description clearly states the tool lists pending operator-adoption requests for the owner queue, distinguishing it from action-oriented sibling tools like authority_approve_adoption or authority_receive_adoption_request.

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

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

It explicitly restricts usage to the Authority owner with consent proof and frames it as a review surface for the Pricing Studio, implying when to use. Could mention alternatives more explicitly, but context from siblings provides enough differentiation.

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

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

No annotations provided, so the description carries the full burden. It explicitly declares 'Free, no side effects,' states it diffs the live wire surface against the registry (revealing internal behavior), and discloses the unregistered flag semantics and what gets reported. This is strong behavioral disclosure for a read-only listing tool, though it lacks explicit pushback against mutation assumptions beyond 'no 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 fairly long for a zero-parameter tool and contains some redundancy — both the paragraph about tool_id staying stable and the paragraph about wire-surface diffing reiterate the 'unregistered array for deploy drift' concept. Some content (issue #174, #175 references) is arguably internal-facing. However, the first sentence front-loads the purpose clearly.

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, no annotations, and a presence of an output schema, this description is exceptionally complete. It explains the output semantics (canonical UUID design, registered:false for drift), the consumers, the reconciliation use case, the rename-vs-remap behavior, and the wire-surface diffing. Nothing essential is left unexplained for a catalog/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 tool has 0 parameters and 100% schema coverage, so the baseline is 4 per the rubric. There are no parameters to document, and the description appropriately explains what the output contains rather than repeating empty schema fields. The description adds rich detail about the output structure (canonical UUIDs, unregistered array, registered flag) that is genuinely useful.

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?

Very specific verb+resource: 'Return canonical (tool_id, mcp_name, …) for every tool the wheel exposes.' Clearly states the authoritative-source purpose and distinguishes it from the many sibling tools by positioning itself as the registry/canonical listing. The tool name is descriptive but the description adds precise scope and intent beyond it.

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 who the consumer is ('Studio, agents, FE') and why: 'Reconcile uses this output to UUID-join against the stored pricing model'. Also states when NOT to guess ('no name-based UUID derivation, no guessing'). Clearly frames this as the authoritative source versus 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, but the description fully covers behavior: it returns data (type, category, description, parameter specs) and states it is free with no credits required. No side effects are expected for a read-only list.

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

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

The description is three sentences: action, return fields, cost. No wasted words. Information is front-loaded and well-structured.

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

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

Given no parameters and the presence of an output schema, the description provides everything needed: purpose, return details, and cost. No gaps.

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

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

The tool has no parameters, and the schema coverage is 100%. The description does not need to add parameter info, but it compensates by describing output fields. Baseline for 0 params is 4.

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

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

The description clearly states it lists available constraint types and their parameter schemas, specifying the return fields (type, category, description, parameter specs). This distinguishes it from sibling list tools like authority_list_coupons.

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

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

The description mentions 'Free — no credits required,' providing usage context. It does not explicitly state when to use vs alternatives, but the tool's purpose is self-explanatory for exploring constraints in a pricing pipeline.

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 must fully disclose behavior. It indicates this is a read operation (list) and provides ordering and a note about the times_redeemed counter. However, it lacks details on authentication (beyond 'proof'), pagination, rate limits, or any side effects. The behavioral disclosure is incomplete.

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

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

The description is brief, using two short sentences plus a note. Every sentence adds value, and the key information is front-loaded. It is appropriately sized 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?

Although an output schema exists (not shown), the description is missing critical context such as pagination, limits, and how to obtain the required proof. For a list tool that may return many items, this is a notable gap.

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

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

The only parameter (dpop_token) is not mentioned in the description. The schema has 0% description coverage, and the description adds no context about what this parameter does or when it should be provided.

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

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

The description clearly states the tool lists every coupon minted by the operator, sorted newest first. It specifies the verb 'list' and the resource 'coupons' with a clear scope. However, it does not explicitly differentiate from the sibling tool 'authority_list_my_coupons', which might have a different 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 mentions 'RESTRICTED to operator — requires proof', providing a clear condition for usage. It does not specify when not to use or suggest alternative tools among the many 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, so the description must fully disclose behavioral traits. It adds context about the return statuses and mentions 'Free' and 'requires proof of npub', but lacks details on side effects, authentication requirements, rate limits, or whether the operation is read-only. This is insufficient for a tool without annotation support.

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, consisting of two sentences. The first sentence states the core purpose, and the second adds key return details. Every word contributes value without redundancy.

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

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

Given the tool has an output schema (covering return format) and a relatively simple input schema, the description provides a minimal but functional overview. However, it does not explain the status meanings or the required 'proof of npub' in detail, leaving some gaps for a complete understanding.

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%, meaning the schema has no parameter descriptions. The tool's description does not explain what 'npub' or 'dpop_token' are or their expected formats, providing no additional meaning beyond the parameter names. This fails to compensate for the lack of schema descriptions.

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

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

The description clearly states the tool lists coupons redeemed by a patron on this operator, specifying it returns both active and exhausted redemptions with status values. This distinguishes it from sibling tools like authority_list_coupons.

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

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

The description mentions 'requires proof of npub' giving some usage context, but it does not provide explicit guidance on when to use this tool versus its numerous siblings (e.g., authority_list_coupons). No when-not-to-use or alternatives are 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 implies a read operation (listing) and restricts access to the owner, but doesn't explicitly state it's read-only or describe side effects/authorization failures. Slightly vague but generally adequate.

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

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

Three tightly-written sentences with no filler. The core purpose is front-loaded in the first sentence, followed by usage restrictions and sibling comparison. Each sentence adds unique 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 that an output schema exists, the description doesn't need to detail return values. It provides essential context (owner queue, proactive vs reactive). Minor gap: no mention of handling empty results or pagination, but still mostly complete for a list 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 description coverage is 100%, meaning the input schema already documents the parameter (authority_proof). The tool's description adds no further detail about the parameter, so baseline score of 3 applies.

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

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

The description clearly states it lists operators reporting Neon-402 errors, differentiating it from the sibling tool authority_network_persistence_health with a specific contrast (reactive vs. proactive). The verb 'list' is implied and the resource is 'neon alerts' (operators reporting store locked).

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 notes the tool is restricted to the Authority owner and provides a clear comparison with authority_network_persistence_health, guiding when to use each. It doesn't explicitly state when not to use, but the differentiation is sufficient.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It fails to mention that the tool is read-only, whether sorting or pagination occurs beyond the 'recent' hint, or how the status filter behaves. This is insufficient for an agent to anticipate behavior accurately.

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, efficient sentence with no wasted words. However, it could add a brief behavioral note without becoming verbose, which prevents a perfect score.

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 need not be explained. However, the description lacks details on ordering, error handling, and the interpretation of 'recent'. It is barely adequate for a tool with two optional parameters.

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

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

Schema documentation covers both parameters fully (100% coverage), so the description adds no new meaning beyond 'recent'. The baseline of 3 is appropriate as the schema already does the heavy lifting.

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

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

The description clearly states the verb 'List' and the resource 'Bitcoin notarization records', with the scope 'recent', which distinguishes it from sibling tools like 'authority_get_notarization_proof' (get a specific record) and 'authority_notarize_ledger' (create a record).

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 viewing recent notarizations but provides no explicit when-to-use or when-not-to-use guidance, nor mentions alternatives. For a straightforward list tool this is adequate but lacks the proactive guidance that would warrant a higher score.

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 convey behavioral traits, but it only states the action. It omits key details like authentication requirements, idempotency, uniqueness constraints (though hinted in schema), or side effects. The brief description leaves the agent uninformed about important behaviors.

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, front-loaded with the key action and resource, containing no extraneous words. Every word earns its place, making it highly concise and 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?

The description is adequate for a simple creation tool. It notes that the coupon is operator-owned, which is helpful context. However, it does not connect to related lifecycle operations (e.g., redemption, updates) or mention the output schema. Given that an output schema exists, the description could be slightly more complete without being overly verbose.

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

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

Schema description coverage is 86%, so the baseline is 3. The description itself adds no parameter-specific information, but the schema already documents parameters with clear descriptions. The description does not detract but does not enhance understanding of parameters.

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

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

The description uses a specific verb ('Create') and clearly identifies the resource as 'a new operator-owned discount coupon.' Among siblings like authority_update_coupon and authority_delete_coupon, this unambiguously distinguishes the creation action.

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

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

The description offers no guidance on when to use this tool versus alternatives. It does not mention that updates should go to authority_update_coupon, nor does it provide prerequisites (e.g., being an operator). This lack of context reduces its usefulness for an AI agent deciding between tools.

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

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

No annotations provided, so description carries full burden. It describes the three layers and their behavior in detail, including conditions like 'configured=false' when no key. However, it does not mention side effects or authentication requirements beyond the owner restriction.

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 clear hierarchy (layers listed with bullet points) and front-loaded with the purpose. Although somewhat lengthy, every part adds value. Could be slightly more concise but maintains clarity.

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

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

Given the complexity and the presence of an output schema (not shown), the description adequately explains what each layer returns (e.g., per-project quota posture). It covers the main use cases and data availability, making it largely complete for a health-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 100% with a single parameter 'authority_proof' documented. Description does not add significant meaning beyond the schema, as it only reiterates that the proof is for owner consent. Baseline 3 is appropriate.

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

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

The description clearly states the tool provides 'the health of the DPYC economy's accounting store (Neon)' and breaks down three distinct layers (projects, own_store, operator_alerts) with specific behaviors. It distinguishes itself from sibling tools focused on other authority 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?

It explicitly states 'Restricted to the Authority owner' and explains when each layer is available (e.g., projects only if NEON_API_KEY is configured, own_store always available). It doesn't explicitly state when not to use the tool, but the context is clear.

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

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

No annotations provided, but description covers key behaviors: operator-only background task, Bitcoin confirmation time, no credit cost. Could elaborate on idempotency or side effects, but sufficient for a zero-param tool.

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

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

Two sentences, front-loaded with the primary action. Every word 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?

Complete for the tool's complexity. Covers purpose, target user, timing, cost. Output schema exists and handles return value documentation.

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 defined; schema coverage is 100% with zero params. Baseline score of 4 is appropriate as description adds no needed parameter info.

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 action: building a Merkle tree of patron balances and submitting root to Bitcoin. It distinguishes itself from sibling tools by specifying the operator-only nature and the background task.

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 operator-only context and background execution. Provides time estimate (1-6 hours) and cost (free). Does not explicitly exclude other user roles or mention alternatives, but the context is clear.

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

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

With no annotations, the description carries full burden. It discloses important behavioral traits: the requirement of Schnorr proof for external npub and the fallback to self-inspection without proof. This goes beyond the basic function and adds security context.

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

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

The description is concise with two short paragraphs. The first sentence front-loads the purpose. Every sentence adds value with no redundant or unnecessary text.

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

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

For a tool with low complexity (2 optional params, output schema present), the description covers core behavior and security. However, the dpop_token parameter is unexplained, which is a notable gap. Overall adequate but not perfect.

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

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

Schema covers 50% of parameters (only npub has a description). The description adds meaning for npub by explaining the proof requirement and fallback, but the dpop_token parameter is entirely undocumented in both schema and description, leaving a gap.

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

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

The description clearly states the verb 'View' and specifies the resources: 'registration status, balance summary, and the Authority's Nostr npub.' This directly indicates the tool's function and distinguishes it from numerous sibling tools that deal with other aspects of authority operations.

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

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

The description implies usage scenarios by explaining the npub parameter behavior (requires proof for external npub, self-inspection for empty). However, it does not explicitly state when to avoid this tool or mention alternative sibling tools, leaving some ambiguity about context.

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

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

No annotations provided. The description only mentions 'Free' but does not disclose behavioral traits such as side effects, required permissions, or data returned. For a tool with zero annotations, 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?

Extremely short but effective. The purpose is front-loaded. However, it is borderline 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 no parameters and the presence of an output schema, the description is adequate but lacks additional context about typical usage or what the description covers.

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 (empty schema, 100% coverage). The description does not need to add parameter info. Baseline for 0 parameters is 4.

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

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

The description clearly states the tool's purpose: 'Describe the DPYC ecosystem via the Oracle.' It is specific and distinguishes from many sibling tools focused on actions like checking status, minting, etc.

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

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

No explicit guidance on when to use this tool vs alternatives. The phrase 'Free' hints at no cost, but there is no clarification of context 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?

No annotations are provided, so the description carries full burden. It only mentions 'Free', implying no cost, but lacks details on side effects, permissions, or reliability. Minimal disclosure.

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

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

Two short sentences, front-loaded, no wasted words. Every word serves a purpose.

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

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

Low complexity tool with output schema present. Description succinctly states what it does; no additional context needed for this simple getter.

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

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

Tool has zero parameters; baseline for 0 params is 4. Description adds nothing about parameters because none exist, which is appropriate.

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

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

The description explicitly states the verb 'Get' and the resource 'current DPYC certification tax rate', which is specific and distinct among sibling tools. No other sibling mentions tax rate.

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

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

No guidance on when to use this tool versus alternatives. It simply states the function without context for selection.

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

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

With no annotations, the description adds 'free' as a behavioral trait but does not explicitly state read-only nature or lack of side effects. Adequate for a simple query tool.

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

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

Extremely concise: two short phrases that convey purpose and an important note ('Free'). 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 zero parameters and a likely simple return, the description is mostly complete. It implies the output will contain instructions, and an output schema exists. Minor missing: what 'Oracle' refers to.

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% (no parameters). Description adds no parameter info, but baseline for zero parameters is 4.

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

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

The description clearly states the action ('Get'), the resource ('DPYC onboarding instructions'), and the source ('the Oracle'), differentiating it from sibling oracle tools like authority_oracle_about.

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

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

No guidance on when to use this tool versus alternatives, such as authority_oracle_about or authority_oracle_lookup_member. The description only states function without usage context.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It only mentions 'Free', but fails to describe side effects, authorization needs, rate limits, or return behavior. The description is insufficient for understanding the tool's operational impact.

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 efficient, using two concise clauses. Every word adds value, and there is no extraneous information. However, it is slightly too minimal for the required coverage.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description is minimally adequate but lacks important context such as what output to expect, whether the member must exist, or any preconditions. It is functional but not comprehensive.

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

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

The input schema has 0% description coverage for the 'npub' parameter. The description adds 'by npub' but does not define or explain the parameter format, constraints, or expected values, leaving the agent with minimal extra 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 ('look up') and the resource ('DPYC community member') via 'npub'. It is specific and distinct from other authority tools, though it does not explicitly differentiate from siblings like '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 other lookup tools or under what conditions. The description lacks context about prerequisites or alternatives, leaving the agent to infer usage.

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 only mentions 'Free', which hints at no cost, but does not disclose whether the tool is read-only, whether it requires authentication, or any side effects. For a simple 'get' operation, this is minimal but not misleading.

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

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

The description is very concise with two short sentences. It front-loads the key action and adds the 'Free' note. While efficient, it could be slightly more structured or combined, but overall well-sized.

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

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

Given the tool has an output schema and zero parameters, the description is adequate. It explains the core purpose and a notable feature (free). There is no missing information that would hinder usage for a simple query tool.

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

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

The tool has zero parameters and the schema coverage is 100%, so the description adds no parameter details. Per the baseline for 0 params, a score of 4 is appropriate as no additional information is needed.

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

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

The description clearly states the tool retrieves 'active network advisories' from the Oracle, specifying both the action and the resource. It distinguishes itself from sibling tools like 'authority_oracle_about' and 'authority_oracle_get_tax_rate' by focusing on advisories.

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 for fetching advisories and adds 'Free' to suggest no cost, but it provides no explicit guidance on when to use it versus alternatives (e.g., other oracle tools). The context of sibling tools suggests it's specialized, but not explicitly stated.

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

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

With no annotations, the description bears full responsibility. It discloses that the tool does not hold private keys, verifies the signature, relays to public relays, and is free. Behavioral traits like key custody and authorization mechanism are well explained. Minor gap: no mention of failure modes or rate limits.

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

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

The description is extremely concise: two short paragraphs that front-load the key action ('Publish a CLIENT-SIGNED kind-0 profile...'). Every sentence adds value, with bold for emphasis and no redundancy.

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

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

Given the tool's complexity (cryptographic verification, relaying), the description covers the essential aspects: what it does, authorization model, and cost. An output schema exists to describe return values, so omitting return details is acceptable. Slight gap: no mention of typical error conditions.

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 descriptions. The description adds meaning beyond the schema by explaining that signed_event must be client-signed and that npub is the public key for signature verification. It also clarifies the cryptographic flow, which is not evident from the schema alone.

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

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

The description clearly states the tool publishes a client-signed kind-0 profile to relays for an npub. It explains the flow and emphasizes that it's free. However, it does not explicitly distinguish from siblings like authority_get_nostr_profile. The purpose is specific and actionable.

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 context for use is clear: when a client-signed kind-0 event is available, the tool verifies and relays it. It mentions 'no proof token, no key custody,' guiding agents not to expect additional authorization. However, it does not explicitly state when not to use it or name alternatives.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool creates a Lightning invoice, requires proof of npub ownership, and is free. It does not detail rate limits, error states, or the exact response after payment, but the existence of an output schema partially compensates.

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: three sentences and a one-liner about cost. It front-loads the primary action and steps, with no wasted words. Every sentence adds essential information.

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

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

Given that an output schema exists, the description does not need to explain return values. It covers the main workflow, prerequisites (npub proof), and cost. It could mention invoice expiry or error handling, but it is sufficiently complete for a purchase tool.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds value by explaining why npub proof is needed ('so credits land in the correct ledger'), which provides context beyond the schema's description of the npub 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 buys credits via Bitcoin Lightning and outlines the workflow (create invoice, pay, call check_payment). It identifies the specific resource (credits) and the action (buy), distinguishing it from siblings like authority_check_balance or authority_check_payment which handle other aspects.

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

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

The description provides clear context for when to use the tool (to purchase credits) and notes that it is free to call. It does not explicitly state when not to use or mention alternatives, but given the unique nature of this tool among siblings, the guidance is adequate.

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

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

No annotations exist, so the description fully bears the burden. It details the verification of operator control via Schnorr bound, recording a pending row, and a best-effort DM. It also states non-provisioning, making behavior fully transparent.

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

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

Concise three-sentence structure with no waste. First sentence states purpose, second adds detail, third clarifies what it does not do. Front-loaded and well-organized.

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

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

Given the tool's complexity (MCP-to-MCP, cryptographic verification), the description covers the entire behavior: inbound call, verification, state change, notification, and exclusion of provisioning. With output schema present, this is complete.

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

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

Schema coverage is 100% with descriptions. The description adds context by explaining the dpop_token as an inline Schnorr proof bound to the sentinel, which goes beyond the schema. Could briefly mention the other parameters but still adds value.

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

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

The description clearly states the tool records an operator's adoption request. It uses specific verbs (record, verifies, fires) and explicitly distinguishes from subsequent steps like approval (approve_adoption) and provisioning.

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

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

Explicitly states it is called MCP-to-MCP by the operator's request_adoption. Describes what it does (verify, record, notify) and what it does NOT do (provisioning), providing clear context for when to use this tool versus others.

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 fully discloses behavior: one-shot retrieval, draining relay, deletion of wrong DMs, ACK/NACK, courier_not_found return, credential_card bypass, reinitialization. Very transparent.

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

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

Well-structured with clear sections, bold emphasis, and a 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?

Output schema exists, description mentions return results and reinitialization. Covers all major behaviors. Complete for a tool with this complexity.

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

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

Schema coverage is 100% (baseline 3). Description adds meaning: dpop_token explained as 'session phrase', credential_card as 'ncred1... card', and service must match request_credential_channel. Adds value beyond schema.

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

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

Description clearly states it picks up credentials from Secure Courier and completes CREDENTIAL-DELIVERY flow. It distinguishes from the sibling receive_npub_proof by specifying it's the ownership-proof counterpart.

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

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

Explicitly says 'Call this only after the user confirms they have replied' and 'Do NOT poll, loop, or retry'. Mentions conditions for credential_card path. Does not extensively compare to other siblings besides one mention.

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 bears the burden of behavioral disclosure. It details verification of npub via inline Schnorr bound to wire name, durable recording of state, and best-effort owner notification. It transparently mentions the 'best-effort' nature of the notification.

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 short paragraphs, front-loading the core purpose. Every sentence provides essential information without redundancy or fluff.

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

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

Given the tool has an output schema and the description covers the full flow, from trigger to side effects, it is contextually complete. It explains the MCP-to-MCP invocation context and the strategic value (learning before complaint).

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

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

The input schema has 100% coverage, providing descriptions for all three parameters. The description adds meaning to the dpop_token parameter, explaining it is an inline kind-27235 proof signed by the operator's nsec and automatically minted, which goes beyond the schema description.

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

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

The description clearly states what the tool does: it receives an operator's report of a Neon 402-locked store, verifies the operator's control over npub, records a latest-state row, and notifies the owner. It uniquely distinguishes itself among siblings by its specific inbound alert 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 explains the trigger condition (operator's runtime catches a Neon HTTP 402 and calls this tool MCP-to-MCP) and the purpose (Authority learns before complaint). However, it does not explicitly state when to avoid using this tool or list alternatives, though no direct alternatives exist 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?

Comprehensive disclosure: deterministic one-shot retrieval, drains only pinned rendezvous relay, matching logic, NACK behavior for mismatched DMs without revealing phrase, and consequence of early calls. Also explains token storage and usage. Since no annotations exist, description carries full burden and excels.

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, but slightly verbose. Every sentence adds value, but could be trimmed without loss. Still very effective.

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 tool complexity (multi-step flow, token handling, relay draining) and existence of output schema, description fully covers behavior, success return, and required follow-up actions. No gaps.

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

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

Adds significant context beyond schema: clarifies that both parameters are required (even though schema lacks required array), explains dpop_token's origin from request_npub_proof, and states patron_npub is the patron's npub. This helps the agent use parameters correctly.

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

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

Clear verb+resource: 'Receive npub ownership confirmation from a patron.' Explicitly distinguishes from sibling tools like request_npub_proof and receive_credentials by naming the flow and counterpart.

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

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

Explicit guidance: 'Call this only after the user confirms they have replied.' Also warns against polling, looping, or retrying, and clarifies when not to call (before user reply). References the counterpart tool for context.

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

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

Discloses key traits: free (no credits required), idempotent (same code twice returns existing redemption), requires npub proof, and explains side effects (records redemption row, auto-applies discount). No annotations to contradict.

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 five-sentence paragraph, front-loaded with main action, no unnecessary words. Every sentence adds value.

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

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

Covers purpose, behavior, prerequisites, side effects, and idempotency. Output schema exists, so return values need not be explained. Complete for the tool's complexity.

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

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

Explains 'code' as operator-shared code and mentions 'npub' requirement, but does not detail 'dpop_token' (0% schema coverage). Adds some meaning but incomplete.

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 'Claim a coupon by its name', specifying the action (redeem) and resource (coupon). It distinguishes from siblings like authority_mint_coupon and authority_list_coupons by focusing on redemption and detailing the effect on subsequent calls.

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

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

Implicitly guides usage by describing the redemption process and prerequisites (npub, code), but does not explicitly compare to alternative coupon tools or state when not to use it.

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

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

No annotations are provided. The description indicates it sends a DM challenge but does not disclose side effects, error conditions, prerequisites, or whether the operation is reversible. For a write operation, more behavioral context is needed.

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

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

The description is a single, front-loaded sentence that efficiently communicates the tool's role and action. Every word is necessary and informative.

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

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

As part of a multi-step onboarding process, the description lacks critical context: what happens after sending the challenge, how to verify success, relationship to subsequent steps. Given the complexity, more completeness is expected.

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 for the single parameter is 100% with a clear field description. The tool description adds the context that the parameter is for the candidate who wants to become curator, but does not add further meaning beyond the schema.

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

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

The description clearly states the tool is Step 1/3 of Authority onboarding and sends a Nostr DM challenge to the candidate. The verb 'send' and resource 'Nostr DM challenge' are specific. It is distinguished from sibling tools by its role 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 an ordered process ('Step 1/3') but provides no explicit guidance on when to use this tool vs. alternatives like authority_register_operator. There is no mention of prerequisites 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?

With no annotations, description details effects: creates ledger entry, idempotent, requires two proofs. Lacks explicit side effects but covers key 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?

Well-structured, front-loaded purpose, bullet-style proofs, efficient sentences. Every sentence adds value without redundancy.

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

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

Covers purpose, prerequisites (two proofs), idempotency, next steps, and parameter origins. Complete for an agent given complexity and output schema 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?

Schema covers 80% of parameters. Description adds value for dpop_token (origin from other tools) and explains proofs beyond schema. Adds workflow context.

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

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

The description clearly states it provisions an operator in the Authority ledger, enabling credit purchases and order certification. It distinguishes from siblings like deregister and adoption 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?

Provides when to use: after operator proofs. Explains idempotency and next step (purchase_credits). Could 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 are provided, so the description must convey behavioral traits. It only says 'Reject' (implies mutation) but omits effects, idempotency, or error conditions.

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

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

The description is a single, focused sentence that efficiently communicates the core purpose 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?

Despite an output schema, the description lacks context on prerequisites, state requirements, or outcome details, making it incomplete for a mutation tool.

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

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

Schema coverage is 100% with parameter descriptions; the tool description adds no extra semantics beyond what the schema already provides, meeting the baseline.

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

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

The description clearly states the action (reject), the resource (pending operator-adoption request), and notes owner consent, distinguishing it from sibling tools like authority_approve_adoption.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as when to reject vs approve, or prerequisites like having an active request.

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

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

The description discloses the actions (ownership reassignment, DML re-grant), idempotency, and what it does not do (password rotation, DM sending). Since no annotations exist, the description carries the full burden and fulfills it adequately, though it could mention potential 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 concise and front-loaded with the core action. Every sentence adds value, providing context, differentiation, and idempotency guarantee 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 the tool's complexity (ownership repair in a multi-tenant schema), the description covers the problem it solves, the specific error, idempotency, and differentiation from a similar tool. An output schema exists, so return values need not be explained. The description is self-contained for an agent to decide when to invoke.

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

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

Schema coverage is 100% so the description adds no extra meaning beyond the schema. The parameters are simply referenced by name in the description; no additional clarification on format or constraints is given. Baseline of 3 is appropriate given complete schema coverage.

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

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

The description clearly states the tool's purpose: reassign table ownership to the operator's role and re-grant DML to fix a specific problem (inability to CREATE INDEX). It also distinguishes itself from the sibling tool register_operator by explicitly stating what it does NOT do.

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

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

The description provides explicit usage context: it should be used when operator schema tables are owned by the provisioning role, leading to the 'must be owner' error. It also contrasts with register_operator, which rotates passwords and sends bootstrap DMs, making it clear when to use each.

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 thoroughly discloses behaviors: requires npub, costs a fee, report is public, returns issue details, and handles the not-configured case. The dpop_token format is explained in detail.

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

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

The description is well-structured with paragraphs, and each sentence adds value. It is slightly lengthy but remains clear and informative 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 5 parameters and the existence of an output schema, the description covers purpose, parameter meanings, behavioral context, and return values. It is complete and leaves no major gaps.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: explains npub as author of record, title as one-line summary, body as details, tool_name as optional, and dpop_token format with specific 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 files a field report as a GitHub issue on the operator's repo. The verb 'file' and resource 'field report/GitHub issue' are specific, and the tool is clearly distinguished from the many 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 explains when to use: when a tool's metadata or response is wrong or confusing. It provides important context (npub required, fee, public report). It does not explicitly state alternatives or when not to use, but the purpose is clear.

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

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

With no annotations, the description carries full burden. It discloses side effects (minting proof, delivering MCP-to-MCP, pending state) and asynchronous nature, providing comprehensive behavioral insight.

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 a single paragraph that is front-loaded with the core action. It is fairly concise given the complexity, though slightly verbose with process details.

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

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

Given the tool's complexity (auth, MCP interaction, asynchronous result), the description covers prerequisites, mechanism, result state, and follow-up actions. Output schema exists for return values, so completeness is high.

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

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

Schema coverage is 100%, so baseline 3. Description does not add parameter-specific details beyond the schema, but the schema already provides adequate descriptions for each 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 uses a specific verb ('Ask') and resource ('Authority to adopt this operator'), clearly distinguishing from siblings like authority_adoption_status (poll progress) and authority_approve_adoption (Authority owner approval).

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

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

Explicitly states it is restricted to the operator and requires proof of npub control. Mentions polling adoption_status for progress, providing clear usage context. Does not explicitly compare to alternatives, but the intent is clear.

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