tollbooth-authority-newengland

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 explains that the tool is free, consumes no credits, requires proof of npub ownership, and exists to prevent statement-scraping of arbitrary patrons. It does not explicitly state read-only behavior or rate limits, but the provided context is substantial for a no-annotation tool.

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

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

The description is four short sentences that front-load the purpose, then list the returned data, disambiguate from the tax balance, and state cost and auth requirements. Every sentence earns its place with no redundant filler.

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

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

Given three parameters, 100% schema coverage, and an output schema, the description covers purpose, contents, cost, auth prerequisite, and the tax-balance confusion risk. It could explicitly distinguish itself from the infographic sibling, but for correct invocation it is sufficiently complete.

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

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

Schema description coverage is 100%, and the dpop_token parameter is already described in detail in the schema. The description adds the rationale for the ownership proof requirement but does not add new syntactic meaning to the parameters, so the baseline 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 uses a specific verb ('Generate a patron's account statement') and enumerates the returned contents: purchase history, active credit tranches, per-tool usage breakdown, and daily usage logs. It also distinguishes the patron's spending account from the operator's Authority tax balance, but it does not explicitly differentiate itself from the sibling tool authority_account_statement_infographic.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 gives clear context: use this when you need a patron's spending account statement, not the operator's Authority tax balance. It also states that it is free and that proof of npub ownership is required. However, it does not name an alternative tool or explicitly compare itself with the infographic sibling.

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

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

No annotations are provided, so the description bears the full transparency burden. It discloses the monetary cost (1 api_sat per call), the pre-verification step via debit_or_deny, and the output form (dark-themed SVG with specific visual elements). This goes beyond a minimal description and gives the agent meaningful behavioral expectations.

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

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

Three sentences, all substantive. The first sentence front-loads the core operation, the second explains the output and its relation to the sibling tool, and the third covers cost and verification. No filler or repetition.

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

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

Given an output schema exists, the description does not need to enumerate return values. It covers the essential invocation context: what the output is, how it relates to a sibling, the cost, and the pre-cost verification requirement. An agent has enough information to decide whether and how to call this tool.

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

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

The input schema provides 100% description coverage for all parameters, so the baseline is 3. The description adds no new parameter-level meaning: it only mentions the data source for the statement, while parameter details like days, npub, and dpop_token are already fully documented 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 states a specific verb ('Generate') and a concrete resource ('visual SVG infographic of your account statement'). It explicitly distinguishes itself from the sibling authority_account_statement by saying it returns the same data rendered as an SVG, which makes the tool's purpose unmistakable.

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

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

It names the alternative authority_account_statement directly and clarifies the relationship by noting the same data is returned but rendered as an SVG graphic. It does not state an explicit 'use this instead of X when...' rule, but the visual-vs-data distinction is clear enough for an agent to choose appropriately.

Agents often have multiple tools that could apply. Explicit usage 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?

No annotations are present, so the description carries the full burden; it adds useful behavioral context: the call is free/no credits required, and proof of npub ownership is needed to prevent enumeration of balances. It does not go further into response behavior or error conditions, but the output schema covers return shape.

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

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

The description is front-loaded with the core purpose and keeps related context in short paragraphs. It is efficient overall, though the mistaken same-name alternative and slight repetition of the dpop-token requirement keep it from being perfectly clean.

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

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

With only two parameters, no nesting, and an output schema, this is a low-complexity tool; the description provides purpose, cost, auth requirement, and a sibling distinction. The wrong sibling reference is the main completeness blemish; otherwise an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the description need not add parameter-level detail; both npub and dpop_token are already well documented in the schema. The prose mentions proof of ownership and no-credit cost but adds no new semantic details 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 first sentence names a specific action and resource ('Check a patron's credit balance at this operator'), and the description clearly distinguishes patron balance from the operator's own balance at the Authority. However, the alternative is referenced as 'authority_check_balance instead' — the same tool name as this one — which likely should be authority_check_authority_balance and prevents full sibling 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?

It gives a clear use case and an explicit exclusion ('For the operator's own balance ... use authority_check_balance instead'), plus a prerequisite ('Proof of npub ownership is required'). But the named alternative is identical to this tool's name, making the routing instruction misleading and only recoverable by inferring the intended sibling.

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

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

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?

With no annotations, the description carries the behavioral disclosure burden. It discloses cost, required ownership proof, and the front-running prevention rationale, which implies the credit-granting context behind the tool. While it doesn't enumerate every side effect, the security-sensitive behavior is transparently communicated and nothing contradicts the expected behavior.

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

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

Four short sentences with no fluff. The purpose is front-loded, and each subsequent sentence adds a distinct fact: when to call, cost, and auth requirement. It doesn't restate schema 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?

An output schema is present, so return-value descriptions are unnneeded. The description covers the essential call sequence, cost, auth, and security rationale, while the input schema fully documents parameter formats. An agent has sufficient information to call this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful lifecycle context by stating that the invoice comes from purchase_credits and that npub ownership must be proven, which helps the agent understand the relationship between invoice_id, npub, and dpop_token beyond the raw schema text.

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

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

The description opens with a specific verb and resource: 'Check the payment status of a Lightning invoice.' This clearly distinguishes it from sibling check tools like authority_check_balance and authority_check_proof_status, and ties it to the purchase_credits flow.

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

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

It explicitly tells the agent when to call the tool: 'Call after paying the invoice from purchase_credits.' It also adds cost and auth context ('Free — no credits required', 'Proof of npub ownership is required'), giving clear usage framing even without naming alternatives or explicit when-not-to-use cases.

Agents often have multiple tools that could apply. Explicit usage 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 load and does add useful behavioral context: the operation is free, requires no credits, and reflects constraint effects like discounts and surge pricing. 'Preview' strongly implies it does not execute the underlying tool, though it stops short of explicitly stating that.

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

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

Three sentences, front-loaded with the tool's purpose, then the scope of what it shows, then the free/no-credit footnote. There is no filler or redundant restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 presence of an output schema covers return-value expectations, and the free behavior plus preview purpose are clearly communicated. However, the description omits usage timing relative to pricing-model siblings and leaves npub/dpop_token semantics unresolved, so an agent may not be fully equipped to call it correctly in context.

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

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

The schema covers tool_id and tool_kwargs well, but npub and dpop_token have no descriptions and are not explained in the description. The description does not meaningfully compensate for the 50% schema coverage gap, leaving the optional authentication/context parameters underspecified.

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

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

The description states a specific action and resource: 'Preview the effective cost of a tool call,' including base cost and constraint effects. This clearly distinguishes it from most siblings, though it does not explicitly contrast it with related tools like authority_get_pricing_model.

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

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

The naming and phrasing imply this should be used to check the cost of a tool call before executing it, and 'Free — no credits required' signals safe exploratory use. However, there is no explicit when-to-use guidance or comparison to alternatives such as authority_get_pricing_model.

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

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

With no annotations provided, the description carries the full burden and compensates well: it explicitly states 'Free, no side effects — does not evict the cache or touch relays' and clarifies the token is 'previously-sached.' This goes beyond a plain 'check' by disclosing the non-destructive, cached-read behavior, though it does not detail failure modes or what happens on invalid tokens.

Agents need to know what a tool does to the 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 tight and front-loaded: the first sentence states the exact purpose, the second adds the high-value use case and sibling comparison, and the third discloses cost/side effects. Every sentence earns its place, with no fluff or repetition of schema fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 two-parameter read-only check with an output schema present, the description is largely complete: it explains purpose, usage context, cost, and side-effect absence. It does not describe the output format, but that is covered by the output schema. Minor missing context includes whether the check requires any prior authorization or how staleness/interaction with the cache is handled, but these are not critical for an agent deciding to invoke it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter context beyond the schema: it only reinforces that dpop_token is previously-sached and part of the npub-proof flow, and does not mention patron_npub at all. That is acceptable since the schema already describes both parameters accurately.

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

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

The description opens with a specific verb and resource: 'Check whether a previously-cached dpop_token is still valid.' It clearly distinguishes itself from sibling tools by scoping to the npub-proof flow and explicitly names its sibling analog ('Mirrors check_oauth_status'), so an agent can tell it apart without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 gives a clear usage scenario: an agent can ask if the next paid call will accept this dpop_token before burning credits. It names the alternative flow (check_oauth_status for npub-proof vs OAuth) and states the tool is free, helping with when-to-use decisions. It doesn't enumerate exclusions, but the context is strong.

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

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

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 exist, so the description carries full behavioral disclosure. It reveals idempotency, the `removed: false` response for absent fields, that deletion is keyed on vaulted values rather than template declarations, proof requirements, and that deletion is as destructive as a write. This is substantial and non-redundant 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 dense but every sentence earns its place: scope, use cases, idempotency, keying behavior, auth restrictions, and destructiveness. It is front-loaded with the core action and then layers necessary detail without filler.

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

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

Given the tool's moderate complexity and the presence of an output schema, the description covers everything needed for correct invocation: purpose, use case, semantics, idempotency, auth restrictions, and destructive potential. No critical gap remains.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: `field` may be templated or untemplated and is matched against what is vaulted, while `dpop_token` is framed as operator proof rather than simply a token. This goes beyond the schema's one-line 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 opens with a specific verb and resource: 'Remove a single operator secret field.' It then clarifies scope by naming the field-level counterpart `forget_credentials` and distinguishing it from wiping the whole row, so the agent can disambiguate it from a large sibling list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 use-after-SDK-cutover scenarios are given, along with the contrast to `forget_credentials` for full re-delivery. It also states the operator-only restriction and rejects patron proofs, giving clear when-to and when-not-to guidance.

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

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

With no annotations provided, the description correctly carries the behavioral burden. It discloses the key traits: the operation is narrowly scoped, free, requires proof of npub ownership, and is a write to a sensitve credential vault. It could go further by stating irreversibility or error behavior when the field does not exist, but it clearly surfaces the most important cautions for a destructive sensitive 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?

The description is compact and front-loaded with the essential action. Every sentence earns its place: the first states what it does, the second clarifies scope, and the remaining sentences cover cost, authentication, and sensitivity. No filler or repetition exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 destructive operation with no annotations, the description covers the critical context: target scope, non-destructive impact on other fields, cost, ownership proof, and the sensitive nature of the vault. The detailed schema and presence of an output schema cover the remaining invocation details, so the description is nearly complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context that the `field` parameter refers to a single field and that other stored fields remain unaffected, which is helpful but not required. The `dpop_token` semantics are already fully and precisely documented in the schema, so the description does not need to compensate.

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

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

The description states a specific verb ('Remove'/'Deletes'), a specific resource ('single patron credential field'), and a clear scope ('without affecting other fields'). This distinguishes it from sibling tools like authority_forget_credentials, which implies bulk removal, and authority_delete_operator_credential, which targets operator 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?

The description makes the intended use clear: delete exactly one field from a patron's stored credentials while leaving the rest intact. However, it does not explicitly contrast this with update_patron_credential, forget_credentials, or delete_operator_credential, so an agent must infer when this tool is preferred over 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 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?

With no annotations provided, the description carries the behavioral disclosure burden. It explicitly warns that deletion is 'as destructive as a write' and states that proof of npub ownership is required, which informs the agent about severity and authentication. It could additionally mention irreversibility or side effects, but it already goes well beyond a generic mutation description.

Agents need to know what a tool does to the 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-load the core action and then provide essential usage caveats. Every sentence earns its place with no redundant filler.

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

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

Given the rich dpop_token schema, 100% schema coverage, and an output schema, the description covers the critical destructive nature and operator/patron distinction well. The main gap is not acknowledging the closely related sibling delete tools, which would make the tool selection unambiguous.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds extra meaning by distinguishing operator vs patron npub semantics and by emphasizing the proof requirement tied to the dpop_token. That raises it above baseline.

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

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

The description clearly states the action ('Delete vaulted credentials') and the target ('specific service and npub'), making it a distinctive verb+resource pairing. However, it does not explicitly differentiate itself from the closely named sibling tools authority_delete_operator_credential and authority_delete_patron_credential, so an agent could initially confuse them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 gives concrete usage context: for operator credentials pass the operator's npub, for patron credentials pass the patron's npub, and proof of ownership is always required. But it never names or contrasts with the sibling delete tools, leaving the when-to-use-this-vs-alternative decision implicit.

Agents often have multiple tools that could apply. Explicit usage 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 provided, so the description must carry the full burden of behavioral disclosure. The description states the purpose but does not mention that this is a read-only operation, any required permissions, potential errors, or side effects. It doesn't explicitly state that it does not modify data, which is a significant gap for a tool with zero annotation coverage. The term 'Generate' implies a computation, but the non-destructive nature is not disclosed.

Agents need to know what a tool does to the 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, succinct sentence that front-loads the action 'Generate' and provides the essential context. No redundant information 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?

The tool is relatively simple with two parameters and an output schema. The description covers the core purpose. However, given the tool's domain, it might benefit from mentioning that the proof is cryptographically verifiable or that it does not modify any data. But since the output schema is present, the agent doesn't need return format. The lack of behavioral transparency lowers this slightly, but for the core functionality it is fairly complete.

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

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

Schema coverage is 100%, so both parameters are already described in the schema. The description adds minimal semantic value beyond the schema, linking npub to 'patron's balance' and notarization_id to 'Bitcoin-notarized snapshot', which is a minor clarification. Since the schema already provides these definitions, the description doesn't significantly enhance parameter understanding. 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 uses a specific verb 'Generate' with a precise object 'Merkle inclusion proof' and specifies the domain 'Bitcoin-notarized snapshot'. It clearly differentiates from sibling tools like authority_notarize_ledger (which creates the snapshot) and authority_list_notarizations (which lists). It is not a tautology of the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage context: to prove inclusion of a patron's balance in a notarized snapshot. However, it does not explicitly name alternative tools or state when not to use it. It lacks explicit routing like 'use this when you need a proof, not when checking status.' So implied usage, not explicit.

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

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

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?

With no annotations, the description carries the full burden, and it delivers: values are never exposed, timestamps may be null for older vaulted secrets, proof of npub ownership is required, and the field list itself is sensitive because it reveals integrations. This is rich behavioral context beyond the schema.

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

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

Well front-loaded with the main purpose in the first sentence, followed by logically grouped detail about timestamps, non-exposure, cost, and auth. Slight redundancy exists between '(not values)' and 'Values are never exposed', and 'Free' is minor, but the overall structure is tight and readable.

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

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

The tool has an output schema, so return shape is already covered. The description supplies everything else an agent needs: field-name semantics, timestamp nullarity, secrecy, sensitivity, cost, and authentication expectations. Nothing critical is missing for correct selection and invocation.

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

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

Schema description coverage is 100%, so both parameters are already thoroughly documented, especially dpop_token's Nostr event format and constraints. The description adds only the security nuance that field names are sensitive, which is useful but not essential to understanding either parameter's meaning.

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

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

States a specific verb and resource: 'List stored patron credential field names' with an explicit '(not values)' qualifier. This clearly distinguishes it from the many sibling tools that update, delete, or receive credentials, and from any tool that would return actual secret values.

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

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

Gives concrete guidance on when to use it: 'use this to verify which fields are configured and how old each one is.' It does not explicitly enumerate alternatives or exclusion cases, but the context is unambiguous and sufficient for an agent to select this tool over credential-mutating 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?

With no annotations, the description carries the disclosure burden. It adds valuable behavioral context: the operation is free, requires proof of npub ownership, and explains why (credential presence is sensitive). It does not explicitly state side effects (e.g., read-only) or rate limits, but 'Report' and the getter nature make mutation unlikely.

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

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

Four compact sentences, front-loaded with the main purpose, followed by a concise service-type breakdown and a one-line access requirement. Every sentence earns its place with no redundancy.

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

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

The tool has only two well-documented parameters and an output schema, so the description needn't describe return values. It covers purpose, service-type behavior, cost, auth requirement, and sensitivity rationale, leaving no significant gap for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds only indirect color by stating that proof of npub ownership is required, which reinforces dpop_token's role but does not materially extend 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 opens with a specific verb-resource pair, "Report a patron's credential readiness for this operator," naming the exact resource and scope. It then differentiates by service type (set-once vs dynamic/OAuth2) and names specific services, making it clear this is the patron-side readiness check, distinct from sibling tools like authority_get_operator_onboarding_status.

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

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

It provides clear context on when the tool applies by breaking out set-once services (shows configured/missing secrets) and dynamic/OAuth2 services (reports none needed). It does not explicitly name alternatives or say when not to use the tool, so it falls just short of the 5 threshold.

Agents often have multiple tools that could apply. Explicit usage 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Free, no side effects' at the end, which is exactly the kind of behavioral transparency expected. It also reveals important behavioral details: inclusion of unregistered tools with registered:false flags, drift detection against the live wire surface (issue #175), and the canonical-UUID behavior where mcp_name changes but tool_id stays. It doesn't describe output structure details, but the description covers the meaningful behavioral traits comprehensively.

Agents need to know what a tool does to the 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 thorough but front-loads the core purpose in the first line, then layers detail progressively (authoritative use case, then edge-case behavior, then drift detection). Every paragraph adds distinct value: identity semantics, unregistered handling, mcp_name vs tool_id stability, and wire-surface diffing. It's on the longer side but dense with necessary nuance—the version-reference and issue-number citations slightly inflate length without adding agent-relevant behavioral 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?

This is a zero-parameter read-only introspection tool with an output schema and no annotations. The description covers: what it returns (canonical identities), its purpose (authoritative source), its edge cases (unregistered tools, registered:false), its semantic guarantees (tool_id stability across renames), and its safety profile (free, no side effects). For a tool of this complexity, the description is fully complete—there's nothing an agent would need to know that isn't stated.

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

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

The tool has 0 parameters with 100% schema coverage (an empty object), so the baseline for parameter semantics is 4. The description adds no parameter info because there are none, and that's entirely appropriate—the description isn't expected to document parameters that don't exist. The introduction of 'tool_id, mcp_name' as output concepts adds value by priming the agent on what the return shapes are. Given zero params, this dimension is essentially N/A and deserves full marks.

Input schemas describe structure but not intent. Descriptions should explain 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+resource ('Return canonical (tool_id, mcp_name, …) for every tool the wheel exposes') that precisely states what the tool does. It distinguishes itself from siblings by clearly identifying itself as the authoritative identity source, contrasting with the operational tools in the sibling list (all authority_* operational functions). The 'canonical-UUID design' framing makes its distinct role unmistakable.

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

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

The description explicitly states when to use this tool: 'The authoritative source for any client (Studio, agents, FE) that needs to know how this MCP identifies its tools.' It also names the specific consumer (Reconcile) and explains the exact usage pattern (UUID-join against stored pricing model, with explicit non-usage guidance: 'no name-based UUID derivation, no guessing'). This is exceptional guidance that clearly discriminates against 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, the description must disclose all behavioral traits, but it only says 'List recent records.' It does not state that this is a read-only operation, whether authentication is required, how results are ordered, what response format to expect, or how the 'status' filter behaves. This is a significant disclosure gap.

Agents need to know what a tool does to the 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 that front-loads the action and resource. It wastes no words, though it could include more detail without becoming bloated.

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

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

For a list tool with an output schema, the description is under-specified. It fails to clarify ordering semantics (e.g., newest-first), the definition of 'recent,' whether the status filter is an exact match, and any pagination behavior beyond the limit parameter. While the schema documents parameter syntax, the description does not fill in operational details an agent would need.

Complex tools with many parameters or behaviors need more documentation. 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 provides full descriptions for both parameters (limit and status), including defaults and example values, achieving 100% coverage. The description adds no extra meaning beyond the schema, so it meets the baseline for a high-coverage schema but does not enhance 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 uses a clear verb-resource pair: 'List' ... 'Bitcoin notarization records.' It distinguishes from siblings like authority_get_notarization_proof (singular) and authority_notarize_ledger (create action). However, 'recent' is vague and does not specify ordering or time window, leaving some ambiguity.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention related tools for single-record lookup or ledger creation, nor does it specify any prerequisites or filtering semantics beyond the parameter schema.

Agents often have multiple tools that could apply. Explicit usage 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 of behavioral disclosure. It only states that it creates a coupon, but does not mention side effects (e.g., persistence, uniqueness enforcement), required permissions, or failure modes. The schema notes 'operator-scoped uniqueness' for the name, but this is not surfaced in the description. For a mutating operation, this is insufficient.

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

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

The description is a single, concise sentence without any fluff. It is front-loaded with the action verb and resource, and every word adds meaning. There is no redundancy or unnecessary detail.

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

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

Given the tool's complexity (7 parameters, output schema, many siblings), the description is too sparse. It does not mention the tool's role in the coupon lifecycle (e.g., before redemption), nor any constraints like needing operator credentials. While an output schema exists, the description still omits important context like when to use this versus update, and what happens upon success. More context is needed for an agent to use it correctly.

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

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

Schema coverage is 86%, so the baseline is 3. The description does not add any parameter-specific meaning beyond what the schema already provides. It neither clarifies parameter interactions nor compensates for the small gap (likely dpop_token). Since the schema is highly descriptive, this is acceptable, but the description adds no extra 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 'Create a new operator-owned discount coupon' states a specific action (create) and a well-defined resource (operator-owned discount coupon). It clearly implies a create operation, distinguishing it from sibling tools like authority_update_coupon or authority_delete_coupon. The 'operator-owned' qualifier adds scope clarity, making the purpose unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention conditions for creation, prerequisites (e.g., operator registration), or alternatives like updating or deleting coupons. An agent would have to infer from context that this is the tool for initial coupon creation, which is 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?

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?

Annotations are missing, so the description carries the full burden. It discloses the key behavioral traits: signature verification before relaying, no key custody, signature-as-authorization, and no cost. The side effect of relaying to public relays is explicit. It does not describe error handling or failure validation, but enough behavioral context is provided for an agent to understand what happens.

Agents need to know what a tool does to the 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 but complete: one front-loaded purpose sentence followed by four short sentences that add essential security and usage context. Every sentence serves a purpose, and there is no repetition or filler. The structure is easy to parse and appropriately sized for a security-sensitive publish operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 lack of annotations, the description covers the critical prerequisites, side effects, security model, and cost. The output schema exists, so return-value details need not be in the description. Minor gaps remain such as explicit verification-failure behavior and relay specifics, but overall the description is sufficiently complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful meaning beyond the schema by explaining how the signed_event is produced (frontend signs with session key or NIP-07) and that the npub is used for signature verification. This helps the agent understand the relationship between the two parameters, though per-parameter semantics are still mostly 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?

Opens with a specific action and resource: 'Publish a CLIENT-SIGNED kind-0 profile to relays for an npub.' This clearly distinguishes the tool from siblings like authority_get_nostr_profile by stating the exact operation, target event type, and destination. The purpose is immediate and unambiguous.

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

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

The description gives clear context for when to use the tool: the frontend must produce a signed kind-0 event and pass it here, because the wheel never holds a patron nsec. It implies this is the tool for client-signed publishing but does not explicitly name alternatives or state when not to use it. This is useful context, though not a full when/when-not guide.

Agents often have multiple tools that could apply. Explicit usage 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 burden of behavioral disclosure. It clearly states that the tool creates a Lightning invoice, that payment is external via a wallet, and that confirmation requires a follow-up call to check_payment. It also notes the free-to-call nature, which is useful for agents deciding whether invocation has side effects or cost. It could mention invoice expiry or irreversibility, but the core behavior is well covered.

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

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

The description is compact and front-loaded with the core purpose. Every sentence earns its place: what it does, how to complete payment, why proof is needed, and that it is free to call. There is no fluff or duplication of schema 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?

For a tool with a rich input schema and an output schema, the description provides the essential workflow and prerequisites. It tells the agent to call check_payment afterward and explains why ownership proof matters. It could be more explicit about what the invoice response contains or that credits are only credited after payment, but the description is generally complete for safe invocation.

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

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

Schema coverage is 100%, so the input schema already thoroughly documents all three parameters, especially dpop_token. The description adds modest context by explaining that npub ownership proof is required so credits land in the correct ledger, which reinforces the purpose of npub and dpop_token, but it doesn't add substantial parameter-level meaning beyond that. 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 opens with a specific verb and resource: 'Buy credits via Bitcoin Lightning.' It clearly identifies what the tool does and distinguishes it from related sibling tools like check_payment and restore_credits by focusing on the purchase/invoice-creation step. An agent can immediately understand the tool's 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 gives actionable workflow guidance: create invoice, pay with any Lightning wallet, then call check_payment to confirm. It also explains the prerequisite that proof of npub ownership is required. It doesn't explicitly enumerate when not to use this tool vs alternatives, but the workflow is clear enough for an agent to select it for purchasing credits.

Agents often have multiple tools that could apply. Explicit usage 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?

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses the deterministic one-shot behavior, relay-only drain, deletion/NACK of wrong DMs, ACK/stop on the first match, courier_not_found failure mode, direct credential_card redemption without relay access, and post-success reinitialization of the payment processor client.

Agents need to know what a tool does to the 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 long but every sentence earns its place: call timing, one-shot semantics, side effects, failure behavior, and the alternate redemption path are all operationally relevant. The key constraint is front-loaded with bold text and the structure makes the two paths easy to distinguish.

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

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

Given the tool's complexity, the absence of annotations, and the presence of an output schema that handles return-value documentation, the description covers all essential context: preconditions, exact relay behavior, destructive side effects, failure result, alternative credential_card path, and post-success behavior. Nothing critical is left for the agent to guess.

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

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

Although the schema already documents each parameter, the description adds meaning beyond it by grouping sender_npub, service, and dpop_token as the 'response you want' and clarifying that dpop_token is not required when a credential_card is provided. It also ties service to the value used in request_credential_channel, reinforcing schema intent.

Input schemas describe structure but not intent. Descriptions should explain 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 operation: 'Pick up credentials from the Secure Courier' and identifies the flow it completes (CREDENTIAL-DELIVERY). It also explicitly distinguishes itself from the sibling tool receive_npub_proof, which is called 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?

It provides an explicit call condition: 'Call this only after the user confirms they have replied.' It also gives direct usage prohibitions ('Do NOT poll, loop, or retry'), names the alternative tool for ownership proofs, and explains when the credential_card path should be used instead of the relay-draining path.

Agents often have multiple tools that could apply. Explicit usage 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?

With no annotations provided, the description carries the full behavioral burden and does so extensively: it reveals deterministic one-shot retrieval, relay draining behavior, deletion/NACK of mismatched DMs, non-disclosure of the expected phrase, and the consequence of premature invocation. It also discloses storage behavior (hash-only in vault, raw token never stored), which is material context beyond any schema.

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

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

The description is long but dense and front-loaded: purpose first, then call condition, then exact behavior, then security/storage notes. Every sentence contributes operational or safety information, though some redundancy exists around 'same token' and the token-handling explanation. It earns its length because these details are critical for correct invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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-value documentation is not the description's burden. For a stateful, one-shot, potentially destructive-flow tool, the description covers prerequisites, alternatives, failure modes, retry prohibition, security properties, and cost ('Free'). Nothing critical for correct use is missing.

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

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

The input schema already documents bot parameters at 100% coverage, so the baseline is 3. The description adds real value beyond the schema by specifying that dpop_token is 'the value returned by request_npub_proof', by framing the parameter pair as (patron_npub, dpop_token), and by explaining that the returned dpop_token must be remembered for subsequent paid calls.

Input schemas describe structure but not intent. Descriptions should explain 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 specific action: 'Receive npub ownership confirmation from a patron' and identifies it as completing the npub-OWNERSHIP-PROOF flow. It fs further disambiguates from the sibling receive_credentials by positioning this as the ownership-proof counterpart, so an agent can distinguish it without opening schemas.

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

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

Explicitly states when to call: 'Call this only after the user confirms they have replied.' It names the alternative (receive_credentials), the prerequisite issuer (request_npub_proof), and gives firm anti-pattern guidance: 'Do NOT poll, loop, or retry.' This is unusually clear operational 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?

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?

With no annotations, the description carries full behavioral responsibility, and it delivers: it discloses the fee, public visibility, normal maintainer triage, lack of verification, npub-based author attribution, output on success, and the not-configured/no-charge failure mode. This is unusually transparent.

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

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

The description is longer than minimal, but each section earns its place: use-case framing, behavioral caveats, cost, publicity, and return behavior. A little redundancy exists between 'author of record is your npub' and 'no npub / no proof, no issue,' but overall it is well organized and front-loaded.

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

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

The description is complete for a complex write action: it explains prerequisites, cost, attribution, public exposure, unverified handling, success return values, and the not-configured case. Combined with a 100%-covered input schema and an output schema, nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. 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 itself provides rich descriptions for npub, dpop_token, title, body, and tool_name. The description reinforces npub's role as author of record but does not add substantial meaning beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description opens with a specific action ('File a field report... as a GitHub issue on the operator's repo') and clearly targets tool metadata/response problems. It instantly distinguishes this tool from the many authority_* siblings, none of which file field reports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 gives a clear trigger condition: use this when a tool's metadata or response is wrong or confusing. It also explains the no-npub/no-issue requirement and the not-configured fallback, though it does not explicitly name any alternative tool to use instead.

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