tollbooth-authority

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?

With no annotations, the description carries full burden. It states the tool is free and polls the Authority MCP-to-MCP, suggesting a network call. It does not disclose permissions, side effects, or whether the operation is read-only. The description is basic 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 concise at two sentences, with the purpose front-loaded. Every sentence adds information. It could be slightly more structured by explicitly mapping the authority parameter, but overall it is efficient.

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

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

Given the existence of an output schema, the description need not detail return values. It lists possible statuses. However, missing parameter explanations and no disambiguation from sibling 'authority_get_adoption_status' leave gaps for an agent to fully understand context.

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

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

Schema description coverage is 0%, so the description must add meaning. It mentions 'at a chosen Authority' which hints at authority_npub, but provides no explanation for dpop_token or any parameter details. The description fails to clarify parameter semantics beyond what the schema already shows.

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

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

The description clearly states the tool checks adoption-request status at a chosen authority, listing possible statuses. However, it does not distinguish itself from the sibling tool 'authority_get_adoption_status', which appears to have a nearly identical purpose.

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

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

The description implies the tool is for checking status after requesting adoption, but provides no explicit guidance on when to use it versus alternatives like 'authority_approve_adoption' or 'authority_get_adoption_status'. No usage exclusions or prerequisites are mentioned.

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

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

No annotations are provided, so the description carries the full burden. It mentions the provisioning effect and the deferred nature, but lacks details about side effects, required permissions, or whether the operation is reversible. While not misleading, it could be more transparent about behavioral traits.

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

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

Two sentences, zero wasted words. Front-loaded with the primary action, then concise context. Efficient and well-structured.

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

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

Given the tool's simplicity (2 params, output schema present), the description is complete. It explains what the tool does, its relationship to a sibling, and the parameters are self-explanatory from the schema.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds marginal context about 'authority_proof' being consent from Authority's OWN npub, but the schema already conveys this. 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 approves a pending request and provisions the operator, using strong verb+resource. It also distinguishes itself from register_operator as its deferred counterpart, adding specificity.

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

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

The description explicitly positions this tool as the counterpart to register_operator, indicating when to use it (after review) and when not to (use register_operator instead). This provides clear guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the paid_tool decorator handles the fee debit and stores cost in runtime._last_debit_cost, and that no recomputation is needed. However, it lacks details on side effects, permissions, idempotency, or error behavior.

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

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

The description is 4 sentences, front-loaded with the core purpose, and each sentence adds distinct value: purpose, decorator behavior, and caller context. It is appropriately concise without being under-specified.

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

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

Given the presence of an output schema (implied by the context signal) and the moderate complexity (3 parameters, no nested objects), the description covers the key aspects: return type, decorator role, and usage context. It is adequate for a server-side certification tool.

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

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

Schema description coverage is 67% (2 of 3 parameters described). The dpop_token parameter has no description in the schema, and the tool description adds no parameter details beyond what's in the schema. The description does not compensate for the missing parameter documentation.

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

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

Description clearly states the tool certifies a purchase order and returns a Schnorr-signed Nostr event certificate, providing a specific verb and resource. However, it could more explicitly distinguish itself from sibling tools like authority_purchase_credits by stating that it is invoked after a purchase is initiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 it is called by operator MCP servers when a patron purchases credits, giving context for usage. However, it does not provide explicit when-not-to-use guidance or alternatives, leaving some ambiguity for an AI agent.

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

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

No annotations are provided, so the description bears full burden. It mentions 'activate Authority' but does not disclose side effects, permissions, or idempotency. The behavioral impact is vague.

Agents need to know what a tool does to the 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 (one sentence) and includes crucial sequencing info upfront. However, it could be slightly more informative without losing conciseness.

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

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

Given the tool's simplicity (one parameter, output schema present), the description covers the basic function but lacks detail on the activation process and potential outcomes.

Complex tools with many parameters or behaviors need more documentation. 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% for the single parameter. The description does not add significant meaning beyond the schema's parameter 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 it checks parent approval and activates Authority, with context as step 3/3. It uses specific verbs and resource, but lacks explicit differentiation 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 implies it is part of a sequence (step 3/3), offering some usage context. However, it does not provide explicit when-to-use, when-not-to-use, or alternative tools.

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

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

With no annotations, the description carries the burden. It clearly indicates a read operation with no destructive side effects, and explains the consequence of a zero balance. However, it lacks details on authentication requirements or rate limits, but these are minor given the simplicity.

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

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

The description is extremely concise with three sentences, each adding value. It is front-loaded and contains 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?

For a simple read tool with no parameters and an existing output schema, the description provides all necessary context: what it does, the meaning of the return value, the action on zero balance, and distinction from patron balance. It is fully complete.

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

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

The input schema has no parameters, so schema coverage is 100%. The description adds no parameter details, but none are needed. A score of 4 is appropriate as the description is complete for a parameterless tool.

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

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

The description clearly states the tool checks the operator's tax balance at the Authority, specifies the return value (sats for certifying patron credits), and distinguishes it from patron balances, differentiating it from sibling tools like authority_check_balance.

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

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

The description explains when to use the tool (to check balance) and provides guidance on what to do when balance is zero (call purchase_credits). It also clarifies this is the operator's own funding, not a patron balance, but does not explicitly compare to other similar 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?

With no annotations, the description must fully disclose behavior. It merely says 'look up', implying a read-only operation, but does not confirm side effects, authentication needs, or rate limits. This is insufficient for safe agent invocation.

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

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

The description is extremely short (one sentence) but fails to include essential details. It is not front-loaded with actionable guidance. Every sentence should earn its place; here the sentence is too vague to be valuable.

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

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

Despite having an output schema that could describe return values, the description is incomplete. It omits usage context, parameter details, and behavioral traits, leaving the agent underinformed for a tool with one parameter.

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

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

The schema has 0% description coverage for the single 'npub' parameter, and the description adds no extra meaning. It does not explain what an npub is, expected format, or constraints, forcing the agent to guess.

Input schemas describe structure but not intent. Descriptions should explain 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 looks up an npub in the DPYC community registry, specifying both the verb (look up) and resource (registry). It distinguishes itself from the many sibling tools, which cover different authority-related 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?

No guidelines are provided regarding when to use this tool versus the many similar 'authority' tools. There is no information on prerequisites, context, or exclusions, leaving the agent without decision support.

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

No annotations are provided, so the description must disclose behavioral traits. It describes the verification and escalation process, and explains the resolution of the parent Authority. However, it does not mention what happens on success/failure, side effects (e.g., state changes), or permissions needed. It is adequate but not 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?

Two sentences cover purpose, step context, and resolution logic. The first sentence front-loads the core action, and the second provides necessary detail. No wasted words.

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

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

Given that this is a step in a multi-step process and an output schema exists, the description is fairly complete. It explains the step number, action, escalation, and parent resolution. Missing details on error handling or preconditions, but adequate for the 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 single parameter candidate_npub has 100% schema coverage, but the description adds meaningful context: 'The Nostr npub of the candidate who replied to the DM challenge.' This explains the role of the parameter within the onboarding step, going beyond the schema definition.

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

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

The description clearly states it is 'Step 2/3 of Authority onboarding' and specifies the action: 'verify candidate DM, escalate to parent Authority.' This distinguishes it from sibling tools like authority_register_authority_npub or authority_get_operator_onboarding_status, and provides a specific verb-resource pair.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 places this tool in a sequence ('Step 2/3'), indicating when it should be used. It also explains how the parent Authority is resolved, giving context for usage. However, it does not include explicit when-not to use or alternatives, but the step-based guidance 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?

Without annotations, the description discloses cascading deletions to redemptions and explains that chain steps become no-ops with warnings. It also states the restriction to operators, but does not detail the 'proof' requirement or reversibility.

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

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

The description is concise with three front-loaded sentences, each adding 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?

It covers behavioral aspects like cascading and restrictions, but lacks parameter details, which reduces completeness for a tool with 2 parameters and no schema descriptions.

Complex tools with many parameters or behaviors need more documentation. 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 2 parameters (coupon_id, dpop_token) with 0% schema description coverage, but the description fails to explain these parameters or their roles.

Input schemas describe structure but not intent. Descriptions should explain 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 resource, distinguishing it from sibling tools like authority_mint_coupon and authority_forget_coupon by detailing cascading deletions to redemptions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 mentions the tool is restricted to operators requiring proof, implying who can use it, but provides no guidance on when to use this tool versus alternatives like authority_forget_coupon.

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

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

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?

With no annotations, the description carries the full burden. It discloses that two proofs are required, explains the consequence of missing authority_proof (unauthorized removal), and implies a destructive action. It does not mention reversibility or side effects, but is sufficient.

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

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

The description is concise and front-loaded, with no wasted sentences. It efficiently communicates purpose, prerequisites, and security implications.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 large sibling set, the description provides necessary context: purpose, required proofs, and a security note. Output schema likely covers return values, so completeness is adequate.

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

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

Schema coverage is 67%. The description adds meaning for authority_proof beyond the schema, but does not describe dpop_token. npub's description in schema is sufficient. Overall, the description provides some added value but is not fully comprehensive.

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

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

The description clearly states 'Remove an Operator from the DPYC community registry,' using a specific verb and resource. It distinguishes from siblings like authority_register_operator and authority_update_operator.

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

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

The description explains the required proofs (proof and authority_proof) and their purpose, preventing unauthorized removal. It implicitly advises when to use the tool, though it doesn't explicitly contrast with alternatives.

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

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

With no annotations, the description carries full burden. It discloses the cosmetic nature and re-redeemability, but doesn't detail if it's idempotent, side effects on related data, or permission requirements. Adequate but not thorough.

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

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

Three concise sentences with no redundancy. The most critical information is front-loaded, and every sentence adds value.

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

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

Despite having an output schema, the description ignores return values. With 3 parameters and no annotation guidance, the description leaves gaps (e.g., what happens on failure, how to interpret response). Needs more detail.

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

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

Schema coverage is 0%, so description must explain parameters. It only mentions npub (requires proof) and coupon_id implicitly, but does not explain either parameter's format or role. The dpop_token parameter is completely unmentioned.

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

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

Clearly states it removes a coupon from a patron's redemption list, and adds that it's cosmetic only, distinguishing from full deletion. The verb 'remove' and resource 'patron's redemption list' are specific and unambiguous.

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

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

Gives context that it's cosmetic and free, and requires npub proof. However, it doesn't explicitly state when to prefer this over sibling tools like authority_delete_coupon, though the cosmetic nature implies the distinction.

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

With no annotations, the description must compensate. It notes that status values are 'not sensitive' and implies the operation is free and requires no proof, suggesting no authentication or cost. However, it does not disclose side effects, rate limits, or permissions, leaving gaps. Still provides some behavioral context beyond the tool name.

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

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

Extremely concise: two short, front-loaded sentences. Every word adds value, with no redundancy. The structure efficiently conveys the core purpose and a behavioral note.

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

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

Adequate for a simple read tool with output schema, but missing usage context relative to siblings. The ambiguity about whose status is read (caller vs. other operator) detracts from 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 already has 100% coverage and clearly describes 'operator_npub' as the npub whose status to read. The description adds no extra meaning to this parameter, so it meets the baseline for full schema coverage.

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

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

The description clearly states 'Read an operator's adoption-request status' and lists possible statuses. However, the mention of 'its ``adoption_status`` tool' creates ambiguity about whether this tool reads the caller's own status or another operator's, especially given the sibling tool 'authority_adoption_status'.

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

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

No explicit guidance on when to use this tool versus alternatives like 'authority_adoption_status' or 'authority_list_adoption_requests'. The description vaguely implies this tool is for reading a specific operator's status by npub, but does not clarify use cases or exclusions.

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

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

With no annotations, the description clearly states the tool is read-only, free, and returns specific fields or empty profile. Adequately discloses behavior beyond the bare 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?

Two sentences, front-loaded with core action and standard, followed by important context. No wasted words.

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

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

Given output schema exists, description of return fields is sufficient. Mentions empty profile case. Lacks error handling details but acceptable for simple read tool.

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

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

Schema coverage is 0%, and description only mentions 'npub' in passing without explaining format (e.g., bech32), default behavior, or constraints. Fails to compensate for missing 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?

Clearly states it reads a public Nostr profile for an npub, specifies NIP-01 kind-0 metadata, and lists return fields. Distinguishes from sibling write tool (authority_publish_nostr_profile).

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

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

Indicates it's free, requires no proof, and data is public, giving appropriate context for usage. Does not explicitly mention when not to use or alternatives, but implies read-only nature.

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

No annotations provided, so description carries full burden. It reveals the authentication requirement (Schnorr signature) which is a key behavioral trait. However, it does not state that the operation is read-only, nor does it disclose error handling or performance implications beyond the auth gate.

Agents need to know what a tool does to the 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: first states purpose, second adds critical gating info. No wasted words, front-loaded with essential information.

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

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

Output schema exists, so return values are covered. However, the description lacks guidance on how to obtain the required Schnorr signature or what happens if authentication fails. For a tool requiring cryptographic proof, more context would be beneficial.

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

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

Schema coverage is 50% (only npub has a description). The tool description does not mention either parameter, so it adds no meaning beyond the schema. The dpop_token parameter is 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 tool retrieves 'operator bootstrap configuration' including 'Neon URL, schema'. This is specific and distinct from sibling tools like authority_register_operator or authority_update_operator.

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

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

It mentions the gating condition (Schnorr signature proof of npub ownership) but does not explicitly state when to use this tool versus alternatives like authority_get_operator_onboarding_status or authority_operator_status. Usage context is implied but not contrasted.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains that the tool reports configuration readiness and shows missing items with delivery instructions, but does not explicitly state that it is read-only, any authorization needs, or potential side effects. The term 'Free.' hints at no cost but is insufficient for full transparency.

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

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

The description is three sentences, front-loaded with the primary purpose, and each sentence adds value. No redundant or extraneous information.

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

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

For a simple parameterless tool with an output schema, the description fully explains what the tool does and provides an alternative use case. It is complete for its complexity level.

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

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

The tool has zero parameters, and schema description coverage is 100% (trivially). Following the guidelines, baseline for 0 parameters is 4. The description adds no parameter info, but none is needed.

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

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

The description clearly states the tool reports 'configuration readiness' for an operator, elaborates on what it shows (configured/missing settings and how to deliver missing values), and distinguishes itself from the sibling tool 'get_patron_onboarding_status' which is for patron-level credential status.

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

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

The description provides an explicit alternative: 'For patron-level credential status, use get_patron_onboarding_status instead.' It also implies usage for operator configuration readiness, and the word 'Free.' may indicate cost-free 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, 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?

With no annotations, the description provides useful behavioral context: self-initialization if no model exists, cost ('Free.'), and limitation ('No economic data from code'). This goes 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?

Three concise sentences with no fluff. The purpose is front-loaded, and each sentence adds value (function, cost, behavior, limitation).

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

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

Given the tool's simplicity (no parameters, output schema exists), the description covers the essential behavioral aspects. It could mention what the pricing model contains, but the output schema likely covers that.

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

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

The schema has no parameters (coverage 100% by default). The description adds meaning by explaining the output (active pricing model) and initialization behavior, which is helpful beyond the empty schema.

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

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

The description clearly states 'Get the active pricing model for this operator,' using a specific verb and resource. It distinguishes from siblings like 'set_pricing_model' and 'reset_pricing_model' by focusing on retrieval.

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

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

The description implies usage as a getter, but does not explicitly state when to use it versus alternatives. The mention 'Free.' hints at cost implications, but no direct guidance on 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 are provided, so the description carries the burden of disclosing behavior. It mentions the access restriction (owner consent) but does not explicitly state that the operation is read-only or non-destructive. Given the output schema exists, return format is handled, but behavioral safety beyond the context is not fully addressed.

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

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

The description is two sentences long, with the first sentence immediately stating the purpose. No filler or repetition. Every word contributes to understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 input (one parameter) and presence of output schema, the description provides sufficient context: ownership restriction, queue nature, and the review surface. It does not elaborate on what happens if the caller is not the owner, but that is implied by 'restricted'.

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

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

There is one parameter (authority_proof) with 100% schema coverage. The description adds 'consent proof' context but does not significantly expand on the schema's description. Baseline 3 is appropriate as the schema already explains the parameter well.

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

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

The description clearly states the action ('list pending operator-adoption requests') and identifies the resource ('owner queue'). It differentiates from sibling tools like authority_approve_adoption or authority_receive_adoption_request by specifying it is for the owner and refers to pending requests, setting it apart as a read-only 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?

The description indicates that the tool is restricted to the Authority owner and is used for reviewing requests on your own time, implying it is for inspection rather than action. However, it does not explicitly contrast with alternatives for approval or rejection, though 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 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?

With no annotations, the description carries full burden. It transparently states the tool is free (no credits), lists the returned fields (type, category, description, parameter specs), and implies a read-only operation. It does not disclose caching, authentication needs, or pagination, but for a simple listing tool, this is adequate. No contradictions.

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

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

Two sentences: one clearly states the action and target, the second elaborates on the return value and cost. No filler, every sentence adds value. Front-loaded with the main purpose.

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

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

Given zero parameters and existence of an output schema, the description sufficiently covers what the tool does and returns. It could optionally mention that no context or credentials are needed (given it's free), but the current description is complete enough for an agent to use correctly.

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

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

The input schema has zero parameters, so the description's job is minimal. It does not need to explain parameters, but it usefully describes the output content (type, category, description, parameter specs), adding context beyond the schema. 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 explicitly states the tool lists all constraint types and their parameter schemas for a pricing pipeline. It clearly distinguishes itself from sibling listing tools (e.g., authority_list_coupons, authority_list_notarizations) by specifying the resource (constraint types) and the domain (pricing pipeline).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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,' which implies it's safe to use without cost concerns. However, it does not provide explicit guidance on when to use this tool versus alternatives like other listing tools, nor does it state prerequisites or when not to use it. The pricing pipeline context gives some direction but lacks thoroughness.

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

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

No annotations are provided, so the description carries full burden. It discloses listing behavior, ordering, and progress bar rendering from times_redeemed vs total_uses, and restricted access. However, it does not clarify the proof mechanism or explicitly state it is read-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?

The description is concise (3 sentences), front-loaded with the primary purpose, and adds relevant detail about output fields and restrictions. No unnecessary content though slight restructuring could improve 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 existence of an output schema (not shown), the description partially covers output fields (times_redeemed, total_uses) but lacks explanation of the dpop_token parameter and does not reference the output schema structure. The agent would need to infer the response format.

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

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

The schema has one parameter (dpop_token) with 0% coverage, and the description does not mention or explain it. The vague reference to 'requires proof' links to the token but lacks explicit semantics, adding minimal value beyond the schema.

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

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

The description clearly states the action (list), the resource (coupons), and the scope (operator's minted coupons, newest first). It is specific but does not explicitly distinguish from sibling tools like authority_list_my_coupons, though the scope 'minted' differentiates it.

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

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

The description notes that the tool is 'RESTRICTED to operator — requires proof,' indicating who can use it. However, it does not provide guidance on when to use this tool versus alternatives like authority_list_my_coupons or authority_check_proof_status.

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

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

No annotations are provided, so the description carries the full burden. It explains return content (active and exhausted redemptions with status field listing possible values) and notes the tool is free and requires npub proof. This is good but could mention rate limits or pagination.

Agents need to know what a tool does to the 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: first states purpose, second adds return details and cost/auth. Every part 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?

For a simple list tool with two parameters and an output schema, the description covers purpose, return structure, and auth requirement. It is complete given the tool's complexity.

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

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

Schema description coverage is 0%, and the description does not explain the meaning or format of the parameters (npub, dpop_token). It only mentions npub proof in the auth context, not parameter details. This is insufficient for a 0% coverage scenario.

Input schemas describe structure but not intent. Descriptions should explain 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 the patron on this operator, distinguishing it from general coupon listing (e.g., authority_list_coupons). The verb 'List' and resource 'coupons this patron has redeemed' is specific.

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

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

The description indicates it is 'Free' and requires 'proof of npub,' providing context on cost and authentication. It does not explicitly state when to use alternatives, but the scope is clear enough for selection.

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

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

No annotations, so description carries full burden. It discloses restriction to owner and that it's a list (owner queue), but doesn't explicitly state read-only or behavior on invalid proof. However, it provides meaningful context without contradiction.

Agents need to know what a tool does to the 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-load key info: purpose, restriction, and relationship to sibling. No wasted words.

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

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

Given output schema exists, return values not needed. Description covers purpose, restriction, and usage context with sibling. Complete for a list tool with single parameter.

Complex tools with many parameters or behaviors need more documentation. 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 is described in input schema. Description adds no additional meaning about the parameter beyond what schema provides, so baseline 3.

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

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

Description clearly states it lists operators reporting Neon-402 (specific error). Distinguishes from sibling 'network_persistence_health' by contrasting reactive vs proactive lists.

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

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

Explicitly says 'Restricted to the Authority owner' and positions as companion to network_persistence_health, explaining when to use each (reactive vs proactive).

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

Describes the three layers and their availability (projects conditional, own_store always, operator_alerts reactive). No annotations exist, so description carries full burden; it discloses read-only behavior and 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 detailed but well-structured with bullet points and clear sections. Each sentence adds value, though slightly verbose for a health check tool.

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

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

Given the tool's complexity (three layers, conditional availability) and the presence of an output schema, the description covers the essential functionality and constraints adequately.

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

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

Schema description coverage is 100%, and the schema already documents the single parameter 'authority_proof'. The tool description adds no further meaning for this parameter beyond what the schema provides.

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

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

The description clearly identifies the tool as 'the health of the DPYC economy's accounting store (Neon)' with three distinct layers, making it specific and distinct from the many authority_* sibling tools.

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

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

States restrictions ('Restricted to the Authority owner') and explains the three layers with conditions (e.g., 'configured=false when no key is present'). Does not explicitly compare to alternatives, but usage 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 discloses key behavioral traits: operator-only, background task, long confirmation time (1-6 hours), and no credit cost. This helps the agent understand the tool's non-immediate nature. It could mention error handling or permissions, but overall sufficient.

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

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

Three concise sentences with the main action front-loaded. Every sentence adds essential information: what it does, who can use it, timing, and cost. No redundant words.

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

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

For a no-parameter tool, the description covers the core action, timing, and access restrictions. The output schema likely handles return values. Could mention if it requires specific permissions or state, but overall adequate.

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

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

No parameters exist, so no description needed. The schema coverage is 100%. Baseline score of 4 applies since the description adds no parameter information 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: building a Merkle tree of patron balances and submitting the root to Bitcoin via OpenTimestamps. It distinguishes from sibling tools like authority_list_notarizations and authority_get_notarization_proof by specifying the exact operation.

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

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

The description explicitly notes it is an operator-only background task, indicating who should use it and that it runs asynchronously. It mentions Bitcoin confirmation takes 1-6 hours and is free, providing context for when to invoke. However, it does not compare to alternative tools like authority_check_proof_status.

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

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

No annotations provided, so description carries full burden. It discloses critical behavior: proof of ownership requirement for explicit npub to prevent enumeration, and fallback to self-inspection. Also explains security rationale. No contradictions.

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

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

Description is two sentences with a front-loaded purpose statement followed by concise details. No redundant or extraneous text. 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?

With an output schema present, the lack of return value description is acceptable. However, the description omits any explanation of the dpop_token parameter and does not mention error conditions or prerequisites. Given the low complexity and sibling context, it is mostly complete but has 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?

Schema coverage is 50% (only npub described in schema). Description adds meaning to npub (proof requirement, fallback) but does not mention dpop_token parameter. Baseline for partially covered schema is 3; description compensates slightly but insufficiently for missing dpop_token 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?

Description clearly states the tool's function: 'View registration status, balance summary, and the Authority's Nostr npub.' The verb 'view' and specific resources differentiate it from sibling tools like authority_check_authority_balance.

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

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

Describes two usage scenarios ('When an explicit npub is provided' vs empty) with clear reasoning for each. However, no explicit guidance on when to choose this tool over sibling tools or what prerequisites are needed.

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

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

No annotations are provided, and the description does not disclose any behavioral traits such as read-only nature, output format, or side effects. 'Free' is vague and does not clarify behavior.

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

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

The description is extremely concise (one sentence) but still conveys the core purpose efficiently. It could be slightly more informative without added length.

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

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

Given no parameters and an output schema existing, the description provides minimal context. It explains the tool returns a description of the ecosystem, but 'via the Oracle' is ambiguous and no details on what the output 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?

With zero parameters and 100% schema coverage, the description has no need to elaborate on parameters. The baseline of 4 is appropriate.

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

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

The description clearly states the verb 'describe' and the resource 'DPYC ecosystem', and distinguishes from more specific oracle sibling tools like authority_oracle_get_tax_rate.

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

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

The description implies this tool is for a general overview of the ecosystem, but does not explicitly state when to use it over siblings or provide any when-not guidance.

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

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

No annotations are provided, so the description carries the full burden. It describes the tool as getting a tax rate and being free, but does not disclose behavioral traits such as read-only nature, idempotency, or rate limits. Minimal but adequate for a simple query.

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

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

The description is extremely concise: a single sentence that immediately states the purpose. No wasted words.

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

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

Given that there are no parameters and an output schema exists (though not detailed), the description is mostly complete for a simple query tool. It could mention edge cases or return format, but brevity 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?

There are zero parameters, so baseline is 4 per rubric. The description does not add parameter information because none is needed, and schema coverage is 100%.

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

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

The description clearly states the tool's purpose: 'Get the current DPYC certification tax rate.' It specifies the resource (DPYC certification tax rate) and the action (get), making it distinct from sibling tools. The inclusion of 'Free.' adds helpful context.

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

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

No explicit guidance on when to use this tool versus alternatives is provided. As a simple getter with no parameters, usage is implied but there are no exclusions or alternatives mentioned.

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

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

With no annotations, the description should disclose behavioral traits. It only states 'Get' and 'Free', implying a read-only operation but lacking explicit details on side effects, return behavior, or required permissions.

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

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

The description is very short with two fragments, which is concise. However, the second fragment 'Free.' is not necessary and could be integrated. Front-loaded adequately.

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

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

Given zero parameters and an existing output schema, the description is sufficient for a simple retrieval tool. It could mention what the instructions contain, but the output schema likely covers that.

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

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

No parameters exist, so schema coverage is 100%. The description adds no value beyond the schema, meeting the baseline of 3.

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

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

The description clearly states it retrieves 'DPYC onboarding instructions', specifying the resource. However, it does not explicitly differentiate from sibling oracle tools like 'authority_oracle_about', though the unique action is implied.

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

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

No guidance on when to use this tool versus alternatives. The description only says 'Free', which is not usage advice. No context on prerequisites or scenarios.

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

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

No annotations provided, so description must bear full burden. Only mentions 'Free' but does not disclose other behavioral traits such as rate limits, idempotency, or any side effects. Minimal disclosure for a lookup 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?

Extremely concise with two short sentences. Front-loaded with the core action. Every word is justified; 'Free' may be helpful but is not redundant.

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

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

Given the tool's simplicity (single string parameter, output schema exists), the description is minimally adequate. However, it fails to explain what the output contains (e.g., member details) or any special behavior, leaving some gaps for an AI agent.

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

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

Single parameter 'npub' with 0% schema description coverage. Description only says 'by npub' without explaining format, constraints, or what 'npub' represents (likely a Nostr public key). Adds little value beyond the parameter name.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Look up'), resource ('DPYC community member'), and identifier ('by npub'). It is specific and distinguishes from siblings like authority_get_nostr_profile which likely retrieves a profile rather than a community member lookup.

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

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

No guidance on when to use this tool versus alternatives among many sibling tools. Lacks context such as prerequisites or scenarios where other tools (e.g., authority_check_dpyc_membership) might be more appropriate.

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

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

No annotations are provided, so the description must convey behavioral traits. It mentions 'Free' but does not disclose whether the operation is read-only, idempotent, requires authentication, or has rate limits. The agent lacks key behavioral context.

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

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

The description is extremely concise: one sentence plus the word 'Free' adds a helpful hint. It is front-loaded and wastes no words.

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

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

Given the tool has no parameters and has an output schema (which likely documents return values), the description is adequate for basic understanding but lacks broader context such as what constitutes a 'network advisory' or when to invoke this tool.

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

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

There are zero parameters and 100% schema coverage, so the description does not need to elaborate on parameters. A baseline of 4 is appropriate as no parameter information is missing.

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

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

The description clearly states the verb 'Get' and the resource 'active network advisories' from the Oracle. Among siblings, it is distinct; no other tool appears to fetch network advisories, so its purpose is 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 on when to use this tool versus alternatives. The word 'Free' hints at no cost but does not address prerequisites, typical use cases, or exclusions.

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

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

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?

Describes verification (inline Schnorr bound to sentinel, no relay), durable record (pending row), and side effect (best-effort owner DM). Lacks details on idempotency, duplicates, or error handling, but covers core behavior well given no annotations.

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

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

Three concise sentences front-loaded with purpose. Each sentence adds distinct value (who calls, what it does, what it does not do). No redundant or vague phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (3 params, output schema exists), the description covers key aspects: verification, persistence, notification, and what it does not do. It could mention preconditions (e.g., operator not already adopted) but overall sufficient 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% (all three parameters have schema descriptions). The description adds marginal context (e.g., dpop_token bound to adoption sentinel) but does not significantly augment the schema explanations. 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 clearly states "record an operator's request to be adopted by this Authority" using a specific verb-resource pair. It distinguishes from sibling tools like authority_approve_adoption and authority_request_adoption by noting it is MCP-to-MCP and complements the approval step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 by the operator's request_adoption (MCP-to-MCP), implying not a direct user call. Clearly says "Does NOT provision — provisioning waits for the owner's approve_adoption", giving a when-not-to-use guideline. Context is clear that it is part of a multi-step adoption flow.

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

No annotations provided, so description carries full burden. Discloses key behaviors: verifies npub via inline Schnorr, records a durable state row, and fires a best-effort notification DM. However, does not mention error handling, idempotency, or failure modes (e.g., what happens if verification fails). Adequate but could be more detailed.

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

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

Description is well-structured: opens with a clear purpose, then explains protocol. It is front-loaded with the main action. Slightly verbose with phrases like 'This is how the Authority learns...' but overall efficient and earns its sentences.

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

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

Given the tool's complexity (incoming alert with verification and state recording), the description covers purpose, trigger, verification, and consequences. Output schema exists (not shown) but that's acceptable. Does not mention error responses or idempotency, but overall sufficiently complete for an experienced agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context for 'dpop_token' (kind-27235 proof bound to wire name), which adds value beyond schema, but otherwise repeats schema info. No significant enhancement, so score remains at 3.

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

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

The description clearly states the tool's purpose: handling an inbound alert from an operator reporting a Neon store 402-locked. It specifies the verb 'receives', the resource 'neon_402_alert', and distinguishes it from sibling tools by describing a specific protocol flow (MCP-to-MCP, verification, state recording, notification).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 this tool is used: 'the instant it catches a Neon HTTP 402' and mentions it's called by the operator's runtime. Provides context ('BEFORE a patron files a complaint'), but does not include explicit when-not-to-use or alternatives. Given the tool's specific nature, the guidance is clear.

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

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

With no annotations provided, the description carries 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?

With no annotations provided, the description fully discloses behavior: looks up coupon by code, validates window and cap, records redemption row, auto-applies discount, is free, idempotent, and requires npub. No contradictions or omissions.

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

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

The description is six well-structured sentences, each adding unique value: core action, process, side effect, cost, prerequisite, idempotency. No wasted words.

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

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

With an output schema present, the description does not need to explain return values. It covers input semantics, behavioral details, constraints, and side effects sufficiently for correct tool invocation.

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

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

The description explains two of three parameters (code as coupon name, npub as proof of identity) but does not mention dpop_token. Given zero schema description coverage, the addition is substantial but incomplete for one parameter.

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

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

The description clearly states the tool redeems a coupon by code, explaining the lookup, validation, and recording process. It distinguishes itself from sibling tools like mint, delete, update, and list coupons by focusing on redemption and its side effects (auto-applied discount).

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

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

The description clearly indicates when to use (to claim a coupon) and prerequisites (proof of npub). It does not explicitly mention alternatives or when not to use, but the sibling tool names implicitly cover that ground.

Agents often have multiple tools that could apply. Explicit usage 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 behavior. It states it sends a Nostr DM challenge, but does not mention if the operation is idempotent, what side effects occur, or what permissions are needed. The return value and state changes are not described.

Agents need to know what a tool does to the 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 front-loads the step number and action. Every word contributes to understanding; there is 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?

For a simple tool with one parameter and an output schema, the description covers the basic action but lacks details on return values, preconditions, and whether it can be called multiple times. It is adequate but has gaps.

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

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

Schema coverage is 100% (one parameter fully described in the schema). The description does not add any additional meaning beyond what the schema already provides for 'candidate_npub'. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it is step 1 of 3 in Authority onboarding, sending a Nostr DM challenge to the candidate. This provides a specific verb and resource, but does not explicitly differentiate it from sibling tools like authority_register_operator.

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

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

The description implies it is part of a sequence ('Step 1/3 of Authority onboarding') but offers no explicit guidance on when to use it, when not to, or what alternatives exist. There is no mention of prerequisites or conditions.

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

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

With no annotations provided, the description fully discloses behavioral traits: it is idempotent, requires two independent identity proofs, and explains how each proof is generated. This level of detail is highly transparent for a complex 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 longer than average but well-structured with bullet points and clear sections. Given the complexity of the tool (two proofs, idempotency), the length is justified and not excessive.

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

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

The description covers prerequisites, behavioral details (idempotent), parameter context, and next steps. An output schema exists, so not detailing return values is acceptable. It is 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?

The schema covers 80% of parameters with descriptions. The description adds significant context for authority_proof (explaining its origin and usage) and the two-proof system, going beyond schema. The dpop_token parameter lacks description but is partially explained in 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 the tool provisions an operator in the Authority ledger, explaining it creates a ledger entry for purchasing credits and certifying purchase orders. It distinguishes itself from sibling tools like authority_purchase_credits and authority_deregister_operator by being the provisioning step.

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

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

The description outlines prerequisites (two Schnorr proofs) and mentions the next step (purchase_credits), providing context for when to use the tool. It does not explicitly list when not to use, but the details effectively guide appropriate 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?

No annotations provided, and the description only mentions rejection with no side effects, notifications, or state changes disclosed. Insufficient behavioral information for a mutation 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?

Single sentence of 7 words, no redundancy, front-loaded with action and object.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 but is not described; tool is a mutation with 3 parameters and no context about return values or post-conditions. Incomplete for safe usage.

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

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

Schema coverage is 100%, so baseline applies. Description adds no extra meaning beyond the parameter descriptions already in the schema.

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

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

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

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

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

No guidance on when to use this tool vs alternatives (e.g., approve_adoption, list_adoption_requests). The description lacks context for decision-making.

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

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

With no annotations provided, the description carries full burden. It details the actions (ownership reassignment and grant restoration), what is not done (password rotation, bootstrap DM), and states idempotency. However, it does not explicitly mention potential side effects or prerequisites for the operation, slightly reducing transparency.

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

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

The description is concise and well-structured: a one-line summary of the action, followed by a contextual explanation and differentiation from sibling tools. Every sentence adds value, with no redundancy or fluff.

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

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

Given the complexity of the repair operation, the description adequately explains the problem, solution, and key behavioral properties (idempotency). The return value is covered by the existing output schema. However, it does not clarify whether parameters are required or how to obtain the authority proof, which could be improved.

Complex tools with many parameters or behaviors need more documentation. 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 clear parameter descriptions, so baseline is 3. The tool description does not add further meaning to the parameters beyond what the schema already provides, thus scoring a 3.

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

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

The description clearly states the tool's action: 'reassign every table in an operator's tenant schema to the operator's own role, then re-grant DML.' It also distinguishes itself from the sibling tool 'register_operator' by explicitly stating what it does not do, providing a clear and specific purpose.

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

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

The description explains the problem (operator cannot CREATE INDEX due to ownership issues) and explicitly contrasts with the sibling tool 'register_operator' by noting that this tool does not rotate passwords or send bootstrap DMs. It also states the tool is idempotent, guiding the agent on when to use it and what to expect.

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