beesknees-mcp

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

No annotations are provided, so the description carries the burden: it discloses that the call is free ('no credits consumed') and that proof of npub ownership is required to prevent scraping arbitrary patrons. This is useful auth and cost context, though it stops short of detailing error behavior or rate limits.

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

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

Front-loaded with the purpose, followed by returned data, a disambiguation clause, and cost/auth notes. Four short sentences, each earning its place, though the return-value enumeration is partly redundant given the output schema 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?

With an output schema present, return values need not be spelled out, and the description still covers cost and the ownership-proof requirement adequately for a read tool. Minor gap: no mention of how the npub-ownership proof failure surfaces.

Complex tools with many parameters or behaviors need more documentation. 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 days, npub, and dpop_token in detail (including the kind-27235 framing). The description adds no parameter-level meaning beyond that, so the baseline 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?

States a specific verb+resource ('Generate a patron's account statement') and immediately disambiguates from the closest sibling by declaring it is the patron's spending account, not the operator's Authority tax balance. An agent can distinguish it from beesknees_check_authority_balance without opening a schema.

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

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

Clear context is given: this tool produces a full statement and requires npub ownership proof, and it is not the Authority tax balance. However, it does not explicitly route to alternatives such as beesknees_check_balance for a lightweight balance check or beesknees_account_statement_infographic for the visual variant, so the when-not is only partially covered.

Agents often have multiple tools that could apply. Explicit usage 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 does meaningful work: it discloses the cost ('1 api_sat per call') and the payment gate ('Proof is verified by debit_or_deny before any cost is incurred'), plus the visual components produced. It does not cover failure/refund behavior, but cost and verification are the operationally important traits here.

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

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

Front-loaded with the purpose, then supporting detail on what is rendered and what it costs. Every sentence contributes; sizing is appropriate for the tool's complexity, with only mild redundancy in enumerating the visual components.

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

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

An output schema exists, so the description needn't explain return values, and it correctly focuses on cost, verification, and the visual nature of the output. Combined with 100% schema coverage, the definition gives an agent everything needed 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 all three parameters (days, npub, dpop_token) are already documented in the schema. The description adds no parameter-level detail beyond what the schema provides, 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?

States a specific verb and resource ('Generate a visual SVG infographic of your account statement') and explicitly names the sibling beesknees_account_statement as the source of the same data, so the agent can distinguish the visual variant from the raw-data one without opening either schema.

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

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

Names the alternative (account_statement) and its differentiator ('rendered as a dark-themed SVG graphic'), which tells the agent to pick this one when a visual is wanted. It stops short of an explicit 'use this when / don't use this when' rule, but the routing signal is clear.

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

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

With no annotations, the description carries the full burden. It does add real traits not present in structured data: the call is free (no cost side effect) and it reaches out MCP-to-MCP to a third party. It omits auth/DPoP requirements (a dpop_token param exists), rate limits, and what happens when no request is on file, leaving significant behavioral gaps.

Agents need to know what a tool does to the 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, purpose front-loaded, no filler; 'Free.' efficiently flags the cost profile. The 'MCP-to-MCP' phrasing is mildly jargon-heavy but still informative.

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

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

An output schema exists, so enumerating pending/approved/rejected/provisioned in the description is redundant and return values need no further explanation. What is missing is the auth expectation for the undocumented dpop_token and the relationship to the adoption-request lifecycle, leaving the definition only minimally complete for a network-polling 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 0% for both parameters. The phrase 'at a chosen Authority' does convey that authority_npub selects which Authority to query, but dpop_token is entirely unexplained in both schema and description, so the description does not compensate for the coverage 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?

States a specific verb and resource ('Check ... adoption-request status') plus scope ('this operator's ... at a chosen Authority'), which separates it from the write-side sibling beesknees_request_adoption. It never names an alternative explicitly, so sibling differentiation is implicit rather than stated.

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

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

'Polls the Authority' and 'Free' imply this is a post-request, repeated-check call rather than a one-time action, which is usable guidance. However, there is no explicit when-to-use statement, no contrast with beesknees_request_adoption or beesknees_get_operator_onboarding_status, and no note on how often to poll.

Agents often have multiple tools that could apply. Explicit usage 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. It does disclose one useful trait — the call is free despite the sibling tools' credit billing — but says nothing about whether it is read-only, what auth is actually needed (the schema's npub note mentions credit billing, which conflicts with 'free'), or any side effects.

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

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

The definition is short and the functional hint ('Free on purpose') is front-loaded, but the second sentence is philosophical rationale rather than information an agent can act on, so roughly half the text does not earn its place.

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

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

An output schema exists, so return values need not be explained, but for a tool in a credit-billing ecosystem the description omits what 'charity share' means, how the destination relates to set_charity, and the auth/cost model. It is too thin for the surrounding 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 only 50%: npub is documented (and oddly labeled 'Required' while the schema lists zero required params) and dpop_token is completely undocumented. The description adds no parameter meaning at all, so it fails to compensate for the coverage 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 phrase 'Who the charity share goes to, and where to check them' conveys the subject matter but uses no clear verb and never says outright that this is a read/query of the current charity destination. It is distinguishable from beesknees_set_charity and beesknees_pay_charity only by inference, not by any explicit statement.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the obvious alternatives (set_charity to change the destination, pay_charity to send funds). The second paragraph discusses cost philosophy but gives the agent nothing actionable about when to invoke this tool.

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

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

No annotations are provided, so the description carries the full burden, and it does well: 'Check' signals a read-only operation, 'Free' discloses cost, and it explains the consequence of a zero balance (top-ups cannot be certified). It does not state auth/permission requirements, but the operational context is otherwise well 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 core purpose is front-loaded in the first sentence, and every following sentence earns its place: the return value, the zero-balance consequence, the disambiguation from patron balance, and the cost. No 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?

For a no-parameter read tool with an output schema, the description supplies everything needed: what it returns, why it matters, what to do at zero, and how it differs from patron balances. Nothing required to call it correctly 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 tool takes zero parameters, so the baseline of 4 applies. There is no parameter surface for the description to add meaning to, and it correctly does not invent any.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Check this operator's tax balance at the Authority') and explicitly scopes it against the closest sibling concept by noting 'This is the operator's own funding — not a patron balance,' which separates it from beesknees_check_balance. An agent can identify the tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 a clear condition and the follow-up action: 'When this balance reaches zero, patron top-ups cannot be certified and the operator must call purchase_credits.' This routes the agent to the right next step. It does not explicitly name the sibling to use for patron balances (beesknees_check_balance), so it stops short of full when/when-not/alternative coverage.

Agents often have multiple tools that could apply. Explicit usage 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 and does well: it discloses that the call is free, that proof of npub ownership is required, and the security rationale (preventing registry-held balance enumeration). It stops short of describing what the returned balance structure contains, but an output schema exists to cover 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 tight paragraphs: identity/scope first, disambiguation second, cost and auth last. Every sentence earns its place and the most important fact is front-loaded.

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

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

An output schema exists, so return values need no prose. The description still supplies everything an agent needs to call this correctly: what is checked, how it differs from the sibling balance tool, that it is free, and the proof requirement.

Complex tools with many parameters or behaviors need more documentation. 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 schema itself is extensively documented (kind-27235, tag rules, freshness, nonce). The description adds no parameter-level meaning beyond the schema, so the baseline 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?

States a specific verb+resource+scope: 'Check a patron's credit balance at this operator.' It then defines what that balance actually is (credits purchased via Lightning for tool calls) and explicitly distinguishes it from the operator's own Authority balance, so an agent can tell it apart from beesknees_check_authority_balance without opening either schema.

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

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

Names the alternative (authority_check_balance) and the exact condition that selects it ('the operator's own balance at the Authority'). It also states cost ('Free — no credits required') and the auth precondition, leaving nothing material to inference.

Agents often have multiple tools that could apply. Explicit usage 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 does a solid job: 'Carries no authority' plus the enumeration of exactly what it can and cannot trigger is a genuine behavioral disclosure an agent could not get from the schema. It omits billing/permission implications (npub is used for credit billing) and any idempotency or side-effect caveats, so it is not a 5.

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

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

Two sentences, front-loaded with the core action and followed by the constraint. Every clause is informative and there is no filler, though the metaphorical phrasing costs a little immediate 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?

An output schema exists, so return values need not be described, and the key behavioral trait (no authority, only advances due work) is covered. But the description omits the billing/auth significance of npub, says nothing about dpop_token, and does not relate the tool to the tick sibling, leaving meaningful gaps for a 2-param, no-annotation 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 50%: npub is documented ('your Nostr public key for credit billing') but dpop_token has no description anywhere. The description text mentions no parameters at all, so it does not compensate for the undocumented dpop_token or explain its role. This leaves a real gap for a tool whose params gate billing and auth.

Input schemas describe structure but not intent. Descriptions should explain 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 (advance work now instead of waiting for the next tick) and clarifies its concrete effect: start a match whose grace has run out or end one whose ceiling has fallen. The metaphor 'ask the hives to advance' is domain jargon, but the second sentence grounds it. It never distinguishes itself from the similarly-named sibling beesknees_tick, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 implies when the tool is applicable by noting it 'can only cause work that was already due', which tells the agent it is useless if nothing is pending. However, it gives no explicit when-to-use/when-not framing and never mentions the obvious alternative, beesknees_tick, leaving the agent to infer the choice.

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

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

With no annotations, the description carries the behavioral burden and does disclose meaningful traits: the operation is free, and it requires proof of npub ownership with the stated security rationale (preventing credit-grant front-running). It does not state read-only/idempotency or failure behavior, but return shape is covered by the output 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?

Four short fragments, front-loaded with the core action, then sequencing, cost, and auth rationale. Every sentence carries information with no filler, though it is slightly terse rather than richly 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?

An output schema exists, so return values need not be explained. The description covers purpose, when to call it, cost, and auth requirements, which is sufficient for an agent to invoke it correctly. Minor gaps (read-only nature, error handling) are not critical here.

Complex tools with many parameters or behaviors need more documentation. 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 fully documents all three parameters (npub, dpop_token, invoice_id). The description adds no parameter syntax or format detail beyond the schema, 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?

States a specific verb+resource: 'Check the payment status of a Lightning invoice.' The resource is distinct from the many sibling check_* tools (check_balance, check_price, check_proof_status). It does not explicitly name a sibling it is not, so it falls short of a 5, but the resource 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?

'Call after paying the invoice from purchase_credits' gives clear sequencing context and ties it to a named sibling tool. It also notes the cost model ('Free — no credits required'). It lacks explicit when-not-use or alternative-tool guidance, so not a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose useful traits — this is a read-only 'preview' that is free and consumes no credits, and that pricing can be affected by discounts, trials, and surge. However it omits auth requirements even though the schema carries npub and dpop_token fields, leaving the caller unsure whether credentials are needed.

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

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

Two short sentences, front-loaded with the purpose before the pricing-detail clause and the free/low-risk note. Every clause earns its place with no 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?

An output schema exists, so return values need not be described, and the cost model is summarized well. But with two undocumented parameters (npub, dpop_token) and no annotations, the auth/identity side of invoking this tool is left to inference, which is a meaningful gap for a 4-param tool.

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

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

Schema coverage is 50%: tool_id and tool_kwargs are documented in-schema (including the UUID-vs-capability resolution and the ad valorem/categorical examples), while npub and dpop_token are undocumented in both schema and description. The description's mention of constraint effects loosely connects to tool_kwargs but adds no new parameter meaning, so it sits at the 3 baseline rather than compensating for the coverage 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?

States a specific verb and resource ('Preview the effective cost of a tool call') and enumerates what the preview contains (base cost plus constraint effects, discounts, free trials, surge pricing). An agent can tell this is a cost-preview tool, though it never names a distinguishing sibling like get_pricing_model to clarify boundaries.

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

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

'Preview the effective cost ... Free — no credits required' implies you call it before a paid invocation to check the price, and the free note is a mild use signal. But there is no explicit when-to-use vs when-not, and no routing to alternatives such as get_pricing_model or the balance-check 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 full behavioral burden, and it does so well: it declares the tool is free, has no side effects, does not evict the cache, and does not touch relays. These are exactly the traits an agent needs before making a paid-call decision. It stops short of 5 only because it says nothing about latency or failure semantics.

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

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

Three tightly packed sentences with zero waste. The core purpose is front-loaded, followed by the usage rationale and the safety profile — a well-ordered structure.

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

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

An output schema exists, so return values need no explanation, and the description covers cost and side effects adequately. It is nearly complete; only minor runtime behavioral details are absent.

Complex tools with many parameters or behaviors need more documentation. 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 both parameters (dpop_token, patron_npub) are documented in the schema itself, so the baseline is 3. The description adds no format or provenance detail 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?

States a specific verb and resource: checking whether a cached dpop_token is still valid. It also situates itself relative to the npub-proof flow and the analogous check_oauth_status, so an agent can distinguish it from request_npub_proof, receive_npub_proof, and the payment/status siblings without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clear when-to-use context: call it before a paid call to confirm the dpop_token will be accepted 'before burning credits on a guaranteed failure.' It names the analogous check_oauth_status pattern but does not give explicit when-not conditions, so it falls just short of a 5.

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

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

With no annotations, the description carries the full behavioral burden for a financial mutation. It discloses the two outcome modes, which is useful, but says nothing about irreversibility, whether the claim can be repeated, authorization requirements, or what happens when the match is unresolved.

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

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

A single front-loaded sentence with zero filler and the two outcomes presented side by side. Nothing in it is 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?

An output schema exists, so return values need not be described, but for a prize-claiming money operation with no annotations and one undocumented parameter the description is too thin. Prerequisites, irreversibility, and failure modes are all absent.

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

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

Schema coverage is 75%, so the schema already documents npub, choice, and match_id. The description reinforces the choice semantics ('credit' vs 'charity' maps to 'keep' vs 'donate') but adds no format or constraint detail, and leaves dpop_token entirely undocumented in both places.

Input schemas describe structure but not intent. Descriptions should explain 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 concrete action ('take the winner's share') with two explicit outcomes (credit or charity), so an agent knows what the tool accomplishes. It does not, however, name or distinguish itself from close siblings such as beesknees_pay_charity or beesknees_payout, so the differentiation burden falls entirely on 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?

Usage is only implied: an agent can infer this applies after winning a match, and the description frames the keep-vs-donate fork. There is no explicit precondition (e.g., the match must be settled), no statement that it is one-shot, and no routing advice against the payout/charity 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 present, the description carries the full burden and does so well: it discloses the cascade to patron redemptions, that referencing chain steps silently become no-ops on unknown ids, and that orphaned references surface as Studio warnings. It stops short of stating reversibility (whether the delete can be undone) or the exact nature of the 'proof' requirement, which would complete the picture.

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

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

Front-loads the action in the first sentence and then layers side effects, restriction, and caveats without padding. The middle sentence is dense with internal mechanics but each clause adds real behavioral information, so it earns its space.

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

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

An output schema exists, so return values needn't be described, and for a no-annotation destructive tool the coverage of cascade effects, orphan handling, and the operator restriction is strong. The one real gap is the undocumented dpop_token parameter, which leaves the invocation contract incomplete.

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

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

Schema description coverage is 0%, so the description must compensate but largely does not. coupon_id appears only incidentally in the chain-step discussion, and dpop_token is never mentioned; the phrase 'requires proof' gestures at it but gives no format or sourcing detail. An agent cannot tell from the text what to supply for the second 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?

States a specific verb+resource ('Delete a coupon') with unusual precision, and the cascade note clarifies the operation's blast radius. It does not, however, differentiate itself from close siblings like beesknees_forget_coupon or beesknees_update_coupon, leaving the agent to infer which edit/removal verb applies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 discloses a critical gating condition ('RESTRICTED to operator — requires proof'), which tells the agent when it is even permitted to call this. But it offers no guidance on when to delete vs. forget or update a coupon, so selection among the sibling removal/edit tools is left to inference.

Agents often have multiple tools that could apply. Explicit usage 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 supplied, the description carries the full burden and does: it discloses idempotency (already-absent fields report removed: false without rewriting the vault), the destructive nature ('as destructive as a write'), and precise auth requirements (nsec-signed kind-27235 or cached dpop_token phrase, patron proofs rejected). This is exactly the behavior an agent needs before invoking a restricted mutation.

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

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

Front-loads the core action, then layers scope, usage, idempotency, and auth in a logical order. Seven sentences is on the long side, but for a restricted destructive tool each sentence adds a distinct, load-bearing fact rather than repeating structured data.

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

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

An output schema exists so return values needn't be documented, yet the description still surfaces the removed: false signal. Combined with auth, idempotency, scope, and the sibling distinction, nothing an agent needs to call this correctly 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%, so the baseline is 3, but the description adds real semantic value by clarifying that 'field' is keyed on what is vaulted rather than what the current template declares, and that it accepts stored-but-untemplated fields. It doesn't add much on dpop_token beyond the schema, keeping it below a 5.

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

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

States a specific verb and resource ('Remove a single operator secret field', 'Deletes one key from the operator's encrypted credential blob') and immediately distinguishes the scope from the row-level sibling forget_credentials. An agent can tell this apart from delete_patron_credential and update_operator_credential from the text alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 names the alternative ('the field-level counterpart to forget_credentials, which wipes the whole row') and gives concrete when-to-use scenarios (retiring a Prefect key after Modal, a stored-but-untemplated orphan like anthropic_api_key). It also states the key benefit of choosing this over a full re-delivery.

Agents often have multiple tools that could apply. Explicit usage 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 does well: it discloses that this is a write to a sensitive credential vault, that it is free, that it touches only one field, and that npub ownership proof is required. It omits reversibility (whether the field can be recovered) and any confirmation/rate-limit behavior, so not a 5.

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

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

Short and front-loaded with the action first, then scope, then cost and auth requirements. Three fragments, each earning its place, though a slightly reformatted single paragraph would be tighter.

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

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

An output schema exists, so return values need not be described. For a 3-param, no-annotation mutation tool the description covers action, scope, cost, and authorization, leaving only reversibility/confirmation gaps. Adequately 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%, so the schema already documents all three parameters in detail (including the dpop_token format requirements). The description only reinforces that a field is removed and proof is needed, adding little syntax or meaning beyond the schema. Baseline 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?

States a specific verb+resource ('Remove a single patron credential field') and clarifies scope by noting it deletes one field 'without affecting other fields,' which implicitly distinguishes it from beesknees_forget_credentials and beesknees_update_patron_credential. No sibling is named explicitly, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 prerequisites (proof of npub ownership required) and a cost note ('Free'), but never states when to choose this over forget_credentials (remove all) or update_patron_credential (modify a field). Usage context is implied rather than spelled out.

Agents often have multiple tools that could apply. Explicit usage 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 behavioral burden. It implies a cutting/mutating action and mentions speed and access, but gives no information about side effects, reversibility, required permissions, billing implications, or state changes. The required npub billing parameter in the schema is not explained behaviorally.

Agents need to know what a tool does to the 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 compact sentence with no filler and front-loads the action. Its brevity is appropriate, though the cryptic phrasing trades clarity for 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?

An output schema exists, so return values need not be described. But for a tool with required billing credentials, no annotations, and a potentially mutating action, the description is far too thin to inform safe and 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 description coverage is 67%, with npub and to_cell described but dpop_token undocumented. The description's 'one fresh cell of comb' loosely maps to to_cell, but it adds no format, range, or semantic detail beyond the schema, and it does not compensate for the undocumented parameter.

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

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

The description states an action and resource: 'Cut one fresh cell of comb.' It also names a comparison to the sibling beesknees_fly via 'slower than flying,' giving some differentiation. However, the metaphor is opaque and does not explain what digging accomplishes, what a cell of comb is, or what the tool returns.

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

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

The only usage guidance is the comparative phrase 'slower than flying, and open to everyone after.' This hints at an alternative and an access condition but does not explicitly say when to use beesknees_dig versus beesknees_fly or other tools, nor does it state prerequisites.

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

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

Annotations are absent, so the description carries the full behavioral burden and does not meet it. It doesn't say whether the move consumes credits (the npub param implies billing), whether it can fail, whether it's reversible, or what the world state looks like after. 'Move' implies mutation but nothing about cost or side effects is 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?

A single tight sentence with no waste. It is front-loaded, but its brevity comes at the cost of the missing detail noted elsewhere rather than being efficiently complete.

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

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

No annotations, undocumented dpop_token, opaque domain vocabulary, and no disclosure of billing or failure behavior. An output schema exists so return values needn't be described, but almost everything an agent needs to invoke this correctly is absent.

Complex tools with many parameters or behaviors need more documentation. 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 nothing about to_cell's validity rules ('neighbouring' appears only in the schema), the required-ish npub billing key, or the undocumented dpop_token. For a tool whose only required param is an ambiguous integer with adjacency semantics, the description should explain the coordinate/adjacency model.

Input schemas describe structure but not intent. Descriptions should explain 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 action ('move one cell') and a constrained context ('open air or an open tunnel'), which is more than a tautology. But 'cell' and 'tunnel' are domain jargon that isn't grounded for an external agent, and nothing distinguishes it from siblings like dig or tick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use guidance, no prerequisites, no alternatives. The phrase 'open air or an open tunnel' hints at a precondition but never states what makes a cell open or what happens if it isn't.

Agents often have multiple tools that could apply. Explicit usage 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 well: it discloses the effect is cosmetic and reversible, that the coupon survives at the operator, that the operation is free, and that it requires proof of npub. It omits idempotency and error/failure behavior, but the mutation's nature and prerequisites are clearly conveyed.

Agents need to know what a tool does to the 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 compact paragraphs with the effect stated first and the caveats second; no filler sentences. Every clause (cosmetic, still exists, re-redeemable, free, npub proof) adds distinct 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?

An output schema exists, so return values need no explanation, and the behavioral effect is well covered. However, with 0% schema description coverage, the description leaves coupon_id and dpop_token entirely undefined, which is a real gap for a 3-parameter mutation tool.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It only touches 'npub' (as a proof requirement) and never explains coupon_id or dpop_token, leaving two of three parameters undocumented anywhere.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Remove a coupon from this patron's redemption list') and immediately qualifies the scope so it is not confused with destructive siblings like beesknees_delete_coupon, noting the coupon still exists at the operator. An agent can distinguish this from deletion or redemption without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clear context for when this applies: purely cosmetic removal, reversible because the patron can re-redeem while the window allows. It does not explicitly name an alternative tool (e.g. use delete_coupon to actually destroy it) or state exclusions, so it falls short of full routing 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 present, the description carries the full burden and does meaningful work: it states the proof-of-npub-ownership auth requirement and explicitly warns that deletion is 'as destructive as a write.' It does not address reversibility, idempotency, or side effects on related data, but the destructive/auth disclosure is solid.

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

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

Three short sentences, front-loaded with the core action, and each sentence adds distinct information (action, npub routing, auth/destructive warning). No 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?

For a destructive mutation with no annotations, the description covers the action, the two npub cases, and the auth/destructive profile, and an output schema exists so return values need not be explained. The remaining gap is sibling disambiguation against the dedicated delete_operator/patron_credential tools.

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

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

Schema coverage is 100% and the dpop_token description is unusually thorough, so the baseline is 3. The description adds real value beyond the schema by explaining the operator-vs-patron semantics of the npub parameter, which the schema alone does not disambiguate.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Delete vaulted credentials') scoped to a service and npub, which is clear on its own. However, it never distinguishes itself from the very similar siblings beesknees_delete_operator_credential and beesknees_delete_patron_credential, which appear to overlap heavily with this tool's operator/patron branches.

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

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

It explains which npub to pass for the operator case versus the patron case, which is useful routing context. But it gives no explicit when-to-use/when-not guidance and never names the near-duplicate delete_* siblings, leaving the agent to guess whether to call this tool or those.

Agents often have multiple tools that could apply. Explicit usage 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 does disclose key traits: it is a read of already-public relay data, costs nothing, and requires no proof. It also states the empty-profile fallback behavior when no metadata is published, which is real behavioral information. Missing only rate-limit/relay-availability nuance.

Agents need to know what a tool does to the 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 tight sentences: the first front-loads the verb, resource, and standard; the second covers cost/auth and the return contract. Every clause earns its place with no 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?

An output schema exists, so the enumerated metadata fields are more bonus than requirement, and the description still covers access cost, proof requirements, and the empty-profile case. The only real omission is the npub input format, which keeps it short of 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?

One parameter (npub) with 0% schema description coverage, so the description must carry it; it says 'an npub's' which identifies the identifier but gives no format guidance (bech32 npub string) or behavior for the default empty value. This is the baseline 'schema does the heavy lifting' level, but the schema here does nothing, leaving a meaningful 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?

States a specific verb and resource: 'Read an npub's public Nostr profile', and names the underlying standard (NIP-01 kind-0 metadata), which pins down exactly what data is fetched. The read/publish split from sibling beesknees_publish_nostr_profile is implicit in the verb but never stated explicitly.

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

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

'Free, no proof — the data is already public on relays' gives useful context for deciding to call it, implying this is a cheap lookup that doesn't require a proof flow. However, no when-to-use or when-to-prefer-an-alternative condition is stated, so the agent must infer the trigger from the name alone.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only derivation but never states whether the call is safe/idempotent, requires authentication as the patron, or has side effects; nothing about the proof being deterministic or tied to an immutable snapshot is made explicit.

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

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

A single front-loaded sentence with no filler; every clause carries meaning about what is generated and over what data.

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

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

An output schema exists, so return values need not be described, and both required params are covered by the schema. However, with no annotations and no usage guidance, an agent still lacks context on when this proof tool is the right choice and what preconditions apply.

Complex tools with many parameters or behaviors need more documentation. 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 both parameters (npub, notarization_id) are documented there, so the baseline is 3. The description only reinforces the relationship between the patron's npub and the snapshot, adding no format, source, or lookup detail 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?

States a specific verb (generate) and resource (Merkle inclusion proof) plus the precise scope of the claim (patron's balance in a Bitcoin-notarized snapshot), which is far more specific than siblings like beesknees_list_notarizations or beesknees_notarize_ledger. It does not explicitly name which sibling to prefer instead, keeping it short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 indication of when to call this versus beesknees_check_proof_status, beesknees_list_notarizations, or beesknees_receive_npub_proof. Prerequisites (e.g. must the notarization already exist and be sealed?) are unstated.

Agents often have multiple tools that could apply. Explicit usage 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 burden. It discloses the shape of the output (configured/missing/delivery) and adds a non-schema behavioral fact ('Free'), which is useful cost context. It doesn't explicitly state read-only/no-side-effects or auth requirements, though the read-only nature is strongly implied by 'Report' and the get_ naming.

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

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

Front-loaded with the core purpose, then detail, then sibling routing, then cost in a single word. Four short sentences with no filler; every sentence adds 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?

An output schema exists, so the description needn't enumerate return fields, and it doesn't. Combined with the clear purpose, sibling routing, and cost note, an agent has everything needed to select and call this zero-arg tool correctly.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter syntax the description could add or omit.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Report') and resource ('this operator's configuration readiness'), then elaborates on exactly what it surfaces: configured settings, missing settings, and delivery instructions. It explicitly distinguishes itself from the patron-level sibling, so an agent can separate the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 an explicit routing rule: 'For patron-level credential status, use get_patron_onboarding_status instead.' That is a clear when-not condition naming the alternative, leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage 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 does well: it discloses that values are never exposed, that timestamps may be null for legacy secrets, that npub ownership proof is required, and why the field list is itself sensitive. It omits rate limits or a safety hint on the mutating siblings, but covers the core behavioral profile.

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

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

Front-loads the key distinction (field names, not values) and proceeds through timestamp semantics, purpose, cost, and auth in a tight sequence. Every sentence earns its place, with only mild redundancy in restating the no-values guarantee.

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

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

An output schema exists, so return values need not be explained, yet the description still clarifies the delivered_at timestamp semantics usefully. Combined with the auth explanation, an agent has what it needs, though a note on fresh-vs-cached dpop_token usage would complete 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 npub and dpop_token parameters are already fully documented in the schema (including the detailed kind-27235 signing requirements). The description adds no parameter-specific syntax beyond that, so the baseline 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?

States a specific verb (List) and resource (stored patron credential field names), and immediately bounds the scope with '(not values)'. This cleanly distinguishes it from sibling mutations like delete_patron_credential, update_patron_credential, and forget_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?

Explicitly states the purpose ('use this to verify which fields are configured and how old each one is') and notes it is free, giving the agent a clear reason to prefer it. It does not name a specific alternative tool or a when-not-to-use condition, so it stops short of a 5.

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

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

With no annotations present the description must carry the full behavioral burden, and it does add real context: the call is 'Free', it requires proof of npub ownership, and it explains why (credential presence is sensitive). It also describes what is reported per service type. It stops short of stating read-only/reversibility or any rate limits, but for a reporting tool this is solid disclosure.

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

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

Front-loaded with the core purpose, then a compact service-type breakdown, then cost and auth in two short sentences. No filler and each sentence contributes distinct 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 two-parameter read tool with an output schema (which covers return values) and no annotations, the description covers purpose, output shape by service type, cost, and the auth requirement. The main gap is explicit routing relative to the operator-side sibling, but otherwise it is complete enough to invoke correctly.

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

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

Schema coverage is 100%, so the schema already defines patron_npub and dpop_token; the baseline would be 3. The description adds meaning beyond the schema by explaining that the proof is required and why (credential presence is sensitive), giving the agent the rationale for supplying dpop_token.

Input schemas describe structure but not intent. Descriptions should explain 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 gives a specific verb and resource ('Report a patron's credential readiness for this operator') and further decomposes the behavior by service type (set-once vs dynamic/OAuth2). It is clearly distinct from the similarly-named get_operator_onboarding_status by scoping to the patron, though it never names that sibling explicitly.

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

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

Usage is implied by the stated purpose: call it when you need to know whether a patron's credentials are configured. There is no explicit when-to-use vs alternatives guidance, e.g. it does not route the agent between this, get_patron_credential_fields, or check_proof_status, nor state prerequisites for obtaining the npub proof.

Agents often have multiple tools that could apply. Explicit usage 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 does disclose a genuinely non-obvious side effect — self-initialization of a 0-sat scaffold when no model exists — which is valuable behavioral context for a read-shaped call. But it omits auth/permission requirements, rate limits, and whether the self-init is persisted. This is a substantial gap given zero annotation coverage, though the side-effect disclosure keeps it above the midpoint.

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

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

Short and front-loaded: the core purpose leads, with the fallback behavior second. 'No economic data from code' is a slightly cryptic trailing clause, but nothing is wasteful.

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

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

An output schema exists, so return values need not be explained, and there are no parameters. The description covers the key non-obvious behavior (self-init scaffold). Missing only the auth/permission context, which leaves a small gap rather than a critical one.

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

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

Zero parameters, and the schema has no properties, so the baseline is 4. There is nothing for the description to clarify beyond what the empty schema already implies.

Input schemas describe structure but not intent. Descriptions should explain 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+resource: 'Get the active pricing model for this operator.' An agent can tell it is a read of pricing config, distinct from set_pricing_model/reset_pricing_model. However, it never names those siblings, so the differentiation is implicit rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use guidance at all. It does not say to call this before set_pricing_model, nor when a fresh scaffold is expected vs. an existing model. 'Free' hints at cost but gives no selection context against the sibling pricing 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 full burden, and it does disclose useful traits: text is returned verbatim, nothing is per-patron, nothing is computed, and two callers get identical bytes (deterministic/idempotent read). However it omits cost, rate limits, and auth behavior, and 'nothing is per-patron' sits oddly against the schema's npub 'for credit billing' requirement.

Agents need to know what a tool does to the 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 purpose is front-loaded in the first sentence, which is good. But the remaining prose about server-side rendering, empty mount divs, and scraping is largely self-justification that does not help an agent select or invoke the 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?

An output schema exists, so return values need no explanation, and the description adequately conveys that this is a static orientation document. The only real gap is the unmentioned billing/npub requirement, which matters for a tool whose schema demands a credential.

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

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

Schema description coverage is 50% (dpop_token undocumented) and the description adds nothing about either parameter. It never mentions npub, even though the schema marks it required for credit billing, and the 'nothing is per-patron' claim arguably conflicts with that requirement.

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

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

The description states a specific verb+resource: it returns prose explaining 'what this service is and how to play it,' and identifies it as the same text as /llms.txt. An agent can tell it apart from siblings like oracle_about or service_status, though it never explicitly contrasts itself with 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?

Usage is implied rather than stated: it is framed as the 'front-door answer' an MCP-arriving agent should read instead of scraping the website. There is no explicit 'use this when X, not Y' guidance and no mention of when the orientation is unnecessary.

Agents often have multiple tools that could apply. Explicit usage 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 behavioral burden. It discloses the seat-allocation rule (fill the fullest hive that still has room) and the purchase nature, but omits auth requirements, cost details (credit billing appears only in the schema), and whether the action is reversible.

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

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

Two sentences with the purpose front-loaded. The second sentence explains the mechanism without excess, though the hive metaphor is somewhat verbose.

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

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

For a mutation tool with no annotations, the description covers the core action and seat-allocation behavior. However, it leaves usage conditions and the dpop_token parameter undocumented; the output schema relieves it of return-value explanation.

Complex tools with many parameters or behaviors need more documentation. 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%, with npub and label documented but dpop_token left undescribed. The description adds no parameter-level meaning, so it fails to compensate for the missing third 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?

States a specific verb and resource: 'Buy a drone a seat in the next match.' The metaphor is clear, though it does not name or contrast with siblings like beesknees_match_list or beesknees_fly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use or when-not-to-use guidance. The phrase 'next match' implies a context but does not tell the agent how this differs from alternatives such as beesknees_fly or beesknees_match_state.

Agents often have multiple tools that could apply. Explicit usage 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 mostly delivers: it declares 'Free, no side effects', explains that unregistered tools appear with registered: false and in a top-level unregistered array, and notes the live-wire vs registry diff for deploy-drift detection. It does not discuss pagination or size limits, but for a no-arg read this is strong disclosure.

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

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

The core purpose is front-loaded and clear, but the deploy-drift/unregistered explanation is stated twice (issue #174 and again for issue #175) in near-identical wording, and the canonical-UUID aside adds length without adding invocation value. The duplication dilutes an otherwise well-structured description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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-shape detail is not required here, and the description still covers purpose, audience, safety, and the edge case of unregistered tools. For a zero-param, read-only tool it is essentially complete, with only pagination/size behavior left unstated.

Complex tools with many parameters or behaviors need more documentation. 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 takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond what the empty schema already states.

Input schemas describe structure but not intent. Descriptions should explain 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 states a specific verb (Return) and resource (canonical (tool_id, mcp_name, ...) for every exposed tool), which no sibling tool provides. An agent can distinguish this registry-identity dump from beesknees_list_constraint_types or beesknees_list_coupons without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 consumers and the reason to call it: 'The authoritative source for any client (Studio, agents, FE)' and 'Reconcile uses this output to UUID-join against the stored pricing model'. That is clear usage context, but no explicit when-not-to-use or named alternative is given.

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

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

Annotations are absent, so the description carries the full burden. It discloses that the operation is free ('No credits required'), which is valuable, but does not state other behavioral traits like read-only nature (implied but not explicit), auth requirements, or rate limits.

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

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

Two sentences, front-loaded with the core action; the additional return fields and cost note are brief and earn their place.

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

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

For a zero-parameter, read-only list tool with an output schema, the description covers purpose, return contents, and cost. It is nearly complete, though without annotations it could state read-only nature more explicitly.

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

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

Zero input parameters, so baseline 4 per rubric. The description does not need to add meaning beyond the empty input 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 ('List') and resource ('constraint types') and scopes it to those used in a pricing pipeline. It does not explicitly mention sibling tools or alternatives, so it meets the 'clear but no sibling differentiation' criterion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use or alternatives are given. The use case is implied by the mention of pricing pipelines, but an agent must infer that this is a discovery call before building or modifying a 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, the description carries the full disclosure burden and does well: it states the ordering (newest first), what each row contains (the current times_redeemed counter), and that operator proof is required. It omits failure behavior when proof is missing and any pagination/limit characteristics.

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

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

Three short sentences, front-loaded with the core action and ordering, with no filler. The 'Studio renders a progress bar' clause is slightly consumer-UI oriented but does explain why times_redeemed matters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 detail is not required. The description still covers ordering, row content, and the operator restriction. Given a single-param list tool, an agent has enough to invoke it correctly, though the sibling-overlap ambiguity is unresolved.

Complex tools with many parameters or behaviors need more documentation. 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 (dpop_token) has 0% schema coverage and is never named in the description, but 'requires proof' does convey its purpose as the operator proof credential. That is partial compensation for a low-coverage schema, landing at a minimal-but-adequate level.

Input schemas describe structure but not intent. Descriptions should explain 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 gives a specific verb and resource with an explicit sort order: 'List every coupon this operator has minted (newest first)'. It is clear what the tool returns, but it never distinguishes itself from the sibling beesknees_list_my_coupons, which an agent could easily confuse it with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 supplies a precondition ('RESTRICTED to operator — requires proof'), which tells the agent who may call it, but gives no guidance on when to prefer this over beesknees_list_my_coupons or beesknees_list_notarizations. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose useful context: the operation is free, requires proof of npub, and returns both active and exhausted redemptions with enumerated per-row status values. It omits any statement about pagination, rate limits, or the role of the second parameter, so the disclosure is partial.

Agents need to know what a tool does to the 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 core purpose, followed by return semantics and a cost/auth note. There is little waste, though the status enumeration is slightly verbose given an output schema already 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?

Because an output schema exists, return-value detail is not required, and the description still adds purpose, cost, and auth context. The gaps are the undocumented dpop_token and absent guidance against the list_coupons sibling, which leave it adequate but not complete.

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

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

Schema description coverage is 0%, so the description must compensate, but it only partially explains 'npub' as a proof of identity and says nothing about the dpop_token parameter (its default, purpose, or when to supply it). One of two parameters is effectively undocumented across both description and 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?

States a specific verb (List) plus resource (coupons) and narrows scope to 'this patron has redeemed on this operator,' which meaningfully distinguishes it from the generic beesknees_list_coupons sibling. It stops short of naming the alternative explicitly, so the differentiation is inferable rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 no when-to-use guidance and never mentions the closely related beesknees_list_coupons, redeem_coupon, or mint_coupon siblings. 'Free — requires proof of npub' is a cost/requirement note, not usage guidance, so the agent must infer when this is the right call.

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

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

No annotations are provided, so the description carries the full disclosure burden. It implies a read-only listing and a recency ordering ('recent'), but says nothing about pagination, ordering guarantees, authentication needs, or rate limits. For a zero-annotation tool this is a significant 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?

A single front-loaded sentence with no filler or redundancy. It is well-sized, though its brevity reflects under-specification rather than tight editing of a rich description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 explanation is not required, and both parameters are fully documented. However, with no annotations, the description should at least clarify the read-only nature, ordering, or what statuses are valid; as written it is minimum-viable but leaves those gaps.

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

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

Schema description coverage is 100%, so both 'limit' and 'status' are already fully documented in the schema. The description's only contribution is the word 'recent', which loosely relates to ordering but adds no syntax or filtering detail beyond what the schema supplies. Baseline 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 gives a specific verb ('List') and resource ('Bitcoin notarization records'), making the tool's function immediately clear. It does not, however, distinguish itself from related siblings like beesknees_get_notarization_proof or beesknees_notarize_ledger, so it falls short of a 5.

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

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

There is no guidance on when to use this tool versus the closely named get_notarization_proof, nor any mention of prerequisites or context. The agent is left to infer usage entirely from the name and one-line description.

Agents often have multiple tools that could apply. Explicit usage 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 behavioral-disclosure burden. It does not state whether the operation is read-only, whether authentication or credits are required, whether there are rate limits, or what side effects might occur. The only implicit signal is that it reports data, but nothing explicit is provided.

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

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

The description is a single short sentence with no wasted words, which is structurally concise. However, it is under-specified rather than appropriately informative for a list tool with many siblings, and it does not front-load a clear verb or scope.

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

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

An output schema exists, so return values need not be explained. But the description omits usage guidance, behavioral traits, authentication/billing context, and any semantic help for the undocumented dpop_token parameter. For a tool in a large sibling set with no annotations and only partial schema coverage, the definition is incomplete.

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

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

Schema description coverage is 50%: npub is documented in the schema as required for credit billing, but dpop_token has no description. The tool description adds no parameter meaning, syntax, or requirements for either parameter, so it fails to compensate for the schema gap.

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

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

The description conveys that the tool returns match information and seat counts, but it lacks a clear action verb like 'List' and uses domain jargon ('hive') that may not be immediately understandable. It does not distinguish this tool from siblings such as beesknees_match_state or beesknees_join_match, leaving the agent to infer the exact 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 gives no guidance on when to use this tool versus alternatives. It mentions matches forming or running, but does not state prerequisites, when-not conditions, or how it differs from related match tools like beesknees_match_state.

Agents often have multiple tools that could apply. Explicit usage 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 carry the behavioral burden, and it does disclose one important trait: the response carries poll_after_ms computed server-side, and there is a server-side throttle valve. It stops short of operational detail — credit billing, rate limits, or what a stale since_seq does — so the disclosure is partial.

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

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

Core intent is front-loaded in the first clause, which is good, but the prose is heavily metaphorical ('every hive, every bee', 'sixty clients throttle themselves and the server keeps a valve it can turn'). The last sentence is evocative rather than informative, costing clarity without adding actionable 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?

An output schema exists so return values needn't be explained, and 80% of parameters are documented in the schema. The description covers the polling contract but leaves the match_id/next_round/since_seq selection logic entirely to the schema, and the opaque vocabulary weakens an otherwise adequate picture.

Complex tools with many parameters or behaviors need more documentation. 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 80%, so the schema already documents npub, match_id, since_seq and next_round. The description adds no per-parameter meaning (its 'when to ask again' refers to the poll_after_ms output, not an input), so it earns the 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?

The name plus 'the live board' imply this returns live match state, and the second sentence frames the action as polling. However, the metaphor ('every hive, every bee') never states the verb/resource plainly, and it doesn't distinguish itself from the sibling beesknees_match_list, so the purpose is inferred rather than declared.

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

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

'Poll this rather than guessing a cadence' gives a clear directive on when to use the tool and why. But it offers no named alternatives or exclusions (e.g. match_list vs this), so an agent still has to infer the boundary between this and other match tools.

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

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

No annotations provided, so the description carries full burden. It does not mention authentication needs, whether the coupon is immediately active, what happens on conflicts (e.g., duplicate name), or any side effects. Just says 'create'.

Agents need to know what a tool does to the 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 short sentence, front-loaded, no waste.

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

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

Given this is a mutation tool with no annotations, no mention of auth or validation, and an output schema exists but the description doesn't indicate what is returned. The description is too sparse to be 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 86%, so schema already documents most parameters. The description adds nothing about parameters. Baseline 3 is appropriate because schema does the heavy lifting.

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

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

States a specific verb (mint/create) and resource (operator-owned discount coupon). Ditinguishes from list/update/delete siblings implicitly, but doesn't explicitly name alternatives like update_coupon or delete_coupon.

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

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

No when-to-use guidance, no mention of prerequisites like authentication, no differentiation from siblings that also deal with coupons (update_coupon, delete_coupon, list_coupons). The description is a bare statement of purpose.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only status check via the cooldown wording, but says nothing about authentication, credit-billing implications (despite the npub param mentioning billing), rate limits, or side effects.

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

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

A single short sentence with no filler. It is appropriately sized, though its brevity comes at the cost of substance rather than through efficient density.

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

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

An output schema exists so return values need not be spelled out, but for a 3-parameter, no-annotation tool the description is too thin. It leaves purpose, usage, auth/billing behavior, and one parameter undocumented.

Complex tools with many parameters or behaviors need more documentation. 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 only 67% and the description adds no parameter meaning whatsoever. It does not explain npub, match_id, or the undocumented dpop_token, so it fails to compensate for the coverage 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 is purely metaphorical ('where your bee stands, what it is carrying, when it may move again') and never states a verb or plainly names the resource, so an agent must infer this is a status/state query for its own bee. It does hint at three data points (position, cargo, cooldown), which is more than a tautology, but it does not clearly distinguish itself from siblings like beesknees_match_state or beesknees_session_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?

There is no statement of when to use this tool, when not to, or which sibling to prefer for related state questions. The agent gets no routing guidance at all.

Agents often have multiple tools that could apply. Explicit usage 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 does disclose valuable traits: it is a background task, Bitcoin confirmation latency is 1-6 hours, and it costs no credits. It does not state idempotency/re-runnability or the exact operator credential requirement beyond 'operator-only', which is a real gap for an irreversible write to Bitcoin.

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

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

Three short sentences, zero filler, with the core action front-loaded ahead of the operational caveats. Every sentence earns its place.

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

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

An output schema exists so return values need not be explained, and the description covers what happens, who may run it, latency, and cost. It stops short of covering the credential prerequisite and whether a repeat call is safe or creates a duplicate notarization.

Complex tools with many parameters or behaviors need more documentation. 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 takes zero parameters, so the baseline is 4; the empty schema is self-explanatory and the description adds no param semantics that could be missing. No syntax or input guidance is needed here.

Input schemas describe structure but not intent. Descriptions should explain 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 precise verb and mechanism: 'Build a Merkle tree of all patron balances and submit the root to Bitcoin via OpenTimestamps.' This is the action tool that creates a notarization, clearly distinguishable from read-side siblings like beesknees_get_notarization_proof, beesknees_list_notarizations and beesknees_check_proof_status.

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

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

'Operator-only background task' states the audience and mode clearly, effectively excluding ordinary patron use. However, it never routes the agent to the alternatives for retrieving or verifying a notarization, so the when-vs-which guidance is partial.

Agents often have multiple tools that could apply. Explicit usage 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 behavioral burden. It does disclose one real trait — that the call is free — which matters in an ecosystem of paid/credit-consuming tools. It says nothing about authentication needs, rate limits, or freshness, leaving an information-only 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?

A single short sentence that front-loads the action and ends with the cost qualifier. Nothing is padded or 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?

With no parameters and an output schema present, the description need not explain return values, so the remaining burden is small. Still, 'DPYC ecosystem' is left undefined and the intended audience/purpose relative to beesknees_guide and the other oracle_* tools is unstated.

Complex tools with many parameters or behaviors need more documentation. 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 takes zero parameters, so the baseline of 4 applies. There is no parameter surface for the description to clarify and nothing is misrepresented.

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

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

It has a clear verb ('Describe') and names a resource ('the DPYC ecosystem'), and it is distinguishable from query-specific siblings like beesknees_oracle_get_tax_rate or beesknees_oracle_lookup_member. However, 'DPYC ecosystem' is unexplained jargon, so the agent cannot predict what content this returns."

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

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

The word 'Free' implies this call is costless compared with paid oracle/settlement siblings, which is a weak signal about when to prefer it. There is no explicit when-to-use, when-not-to-use, or named alternative among the many oracle_* siblings.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that the operation is free and 'Get' implies a read-only action, but it does not state authentication needs, rate limits, or data freshness. The output schema covers return values, so that omission is acceptable.

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

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

The description is two short sentences with no wasted words. The core purpose is front-loaded, and the additional cost note is brief and useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 zero-parameter read operation with an output schema, the description is nearly complete: it states the returned resource and that the call is free. It lacks explicit usage context relative to sibling tools, but nothing essential for invocation 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 tool takes zero parameters, so there is no parameter semantics for the description to clarify. The baseline for a zero-parameter tool is 4, and nothing in the description detracts from that.

Input schemas describe structure but not intent. Descriptions should explain 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 and resource: 'Get the current DPYC certification tax rate.' It clearly identifies what the tool returns. However, it does not distinguish itself from sibling oracle tools such as beesknees_oracle_about or beesknees_oracle_network_advisory, so it falls short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or exclusions. 'Free' is cost information, not usage guidance.

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

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

No annotations, so the description carries the full burden. 'Free' does disclose a meaningful behavioral trait in a payment-heavy toolset (no charge to call), and the zero-parameter read shape makes the safety profile obvious, but nothing else is disclosed about what the instructions contain or whether prior onboarding state is required.

Agents need to know what a tool does to the 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, front-loaded sentences with no filler. It is efficient, though the brevity edges toward under-specification rather than optimal 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?

A zero-param tool with an output schema needs little, and the return value need not be explained. However, the unexplained 'DPYC' term and the absence of any routing versus the many onboarding/guide siblings leaves a real gap for a large toolset.

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

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

Zero parameters, so there is nothing for the description to disambiguate; the schema is trivially complete. Baseline 4 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?

States a clear verb+resource ('Get DPYC onboarding instructions') and the source ('from the Oracle'), but 'DPYC' is undefined jargon and the description never distinguishes this from the many sibling onboarding tools (beesknees_get_operator_onboarding_status, beesknees_get_patron_onboarding_status, beesknees_guide). An agent can guess the general purpose but not why it should pick this over those.

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

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

'Free' hints at a cost dimension but there is no when-to-use guidance, no prerequisites, and no mention of the alternative guide/onboarding-status tools that an agent would plausibly reach for instead.

Agents often have multiple tools that could apply. Explicit usage 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. It discloses only that the call is free; it says nothing about authentication requirements, what happens when the npub is unknown, or whether the lookup is read-only (implied but unstated). An output schema exists, so return values need not be described, but the operational gaps remain.

Agents need to know what a tool does to the 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, front-loaded sentences with no filler; the verb and identifier come first. The trailing 'Free.' fragment is terse but does convey a real constraint, so it earns its place.

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

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

For a one-parameter read tool with an output schema, the description covers purpose and cost, and the schema covers the return shape. What is missing is failure behavior (unknown npub) and any hint of where the member data comes from, which keeps it at minimum-viable rather than 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 0% for the single npub parameter, so the description must compensate. Saying 'by npub' confirms the parameter's role but adds no format detail (bech32 prefix, expected length, whether it accepts hex pubkeys), which is the bare minimum for an identifier field.

Input schemas describe structure but not intent. Descriptions should explain 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 (look up a community member) and the key identifier (npub), which is enough to distinguish it from list_canonical_identities or get_nostr_profile at a glance. It does not explicitly name a sibling or state how it differs from the other identity-lookup tools, so it stops short of a 5.

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

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

'Free' implies there is no payment gate, which is a mild usage signal, but the description never says when to reach for this tool versus get_nostr_profile, list_canonical_identities, or the other oracle endpoints. No prerequisites, no exclusions, no alternative routing.

Agents often have multiple tools that could apply. Explicit usage 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 says 'Free', which is a useful cost signal, but says nothing about authentication requirements, rate limits, or whether 'active' means currently-in-effect versus recently-issued. An output schema exists, so return structure is covered, but the behavioral profile of a read-only Oracle call is left largely implicit.

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

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

Two short sentences, front-loaded with the action and resource, with the cost hint tacked on. Nothing is wasted and nothing is buried.

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

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

For a zero-parameter read tool with an output schema and no annotations, the description is adequate but thin. It omits auth/cost prerequisites (beyond 'Free'), timing semantics of 'active', and any pointer to sibling Oracle tools. An agent could invoke it, but with reduced confidence about when it is the right call.

Complex tools with many parameters or behaviors need more documentation. 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 takes zero parameters, so there is nothing to document and the baseline is 4. The description does not need to compensate for parameter gaps, though 'active' hints at an implicit filter that is not exposed as a 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?

States a specific verb (Get) and resource (network advisories from the Oracle), which is clearer than most siblings in this namespace. It does not differentiate itself from adjacent read-only Oracle siblings like beesknees_oracle_about or beesknees_oracle_get_tax_rate, but the resource is distinct enough that an agent can reasonably distinguish 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?

No when-to-use guidance, no exclusions, no mention of alternatives such as service_status or oracle_about. The word 'active' implies filtering to current advisories but without stating that other advisories (past/archived) exist or where to find them, the agent has no routing signal.

Agents often have multiple tools that could apply. Explicit usage 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 does so well: it discloses the operator/proof authorization requirement, atomic all-or-nothing claim before sats move, idempotency via the shared primary key ('a second press collides on the key'), and failure semantics (legs marked failed, debt returns, attempt stays on record). This is unusually rich behavioral disclosure 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?

The purpose is front-loaded and the atomicity/idempotency content is substantive, but the prose is padded with narrative flourishes ('which is the shape this always needed', 'the two cannot pay the same match twice') that lengthen it without adding callable 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?

An output schema exists so return values need not be described, and the description covers prerequisites, atomicity, idempotency, and failure recovery. Only the undocumented dpop_token parameter leaves a real 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 only 50% (npub documented, dpop_token not), so the description is expected to compensate, but it never mentions either parameter by name or explains their formats. The closest reference is 'the caller to be the operator, proven', which only loosely gestures at the dpop_token's role.

Input schemas describe structure but not intent. Descriptions should explain 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 opening sentence states a specific verb and resource ('pay everything owed to the charity, in one Lightning payment') and implicitly contrasts with per-match `pay_out` later in the description. An agent can distinguish it from `pay_out`/`payout`/`set_charity` from the text, though it never names those siblings as alternatives directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clear context for when the batch form is the right choice ('a single match's share can be smaller than the fee floor ... paying per match can cost more than it delivers') and states the operator-only prerequisite. It stops short of an explicit 'do not use this when X' exclusion.

Agents often have multiple tools that could apply. Explicit usage 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 does so richly: it discloses atomicity (wallet checked for amount plus routing fee, payment claimed in DB before sats leave), idempotency (retries/double presses collide on a primary key; re-calling after success reports the existing payment), and irreversibility. These are exactly the behavioral traits an agent needs for a real-money mutation.

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

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

Front-loads the operator instruction and the core action, then layers atomicity and idempotency detail. Dense and mostly waste-free, though it runs several sentences and could tighten the ledger-integrity exposition.

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

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

An output schema exists so return values need no explanation, and the description fully covers auth (operator proven), mutation semantics, idempotency, and irreversibility. Nothing an agent needs to invoke this correctly 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 75%, so most parameters are documented in the schema itself. The description adds meaning to match_id and kind indirectly (amount is read from the settlement, the charity leg pays the recorded beneficiary), but it never explains npub or dpop_token usage beyond the schema. 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?

States a specific verb and resource (send a settled match's charity or winner share over Lightning) with scope (operator-only). It actively distinguishes itself from siblings like beesknees_pay_charity and beesknees_payout by declaring it is the only tool that moves real sats and cannot be undone by writing another row.

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

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

Frames the caller as the operator and clarifies that nothing is automatic, giving clear context for when it should fire. It does not explicitly name a sibling alternative or state a when-not condition beyond the restricted-operator gate, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, yet it never states whether this is a read or a write, whether it requires credentials, or what it returns. It does add one genuinely useful trait — the default fallback to 'donate' and the distinction between a chosen value and an unset one — but that is about a field, not the operation's 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 prose is not front-loaded with the tool's purpose and instead leads with an oblique phrase, then spends its remaining length on an output field's semantics. It is not verbose, but the space is spent on the wrong thing, leaving the core action unstated.

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

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

An output schema exists so return values need not be re-explained, yet the description references a `set` field with no grounding in the input schema and omits the read/write nature, auth expectations, and sibling differentiation. For a credential-bearing payout tool this leaves the agent materially under-informed.

Complex tools with many parameters or behaviors need more documentation. 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 only 50% (npub documented, dpop_token undocumented), and the description says nothing about either parameter. Worse, it explains a `set` field that does not exist in the input schema, so it neither compensates for the coverage gap nor clarifies what the caller must supply.

Input schemas describe structure but not intent. Descriptions should explain 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 offers a noun-phrase gloss on the resource ('What you have said should happen to your winnings') but never states a verb or operation, so an agent cannot tell whether this reads, sets, or lists the payout preference. It also fails to distinguish itself from the near-identical siblings beesknees_set_payout, beesknees_pay_out, and beesknees_payout_history.

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

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

There is no when-to-use guidance at all — no mention of when to call this versus beesknees_set_payout (which appears to be the write counterpart) or beesknees_payout_history. The only conditional content concerns the value of an output field, not invocation.

Agents often have multiple tools that could apply. Explicit usage 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 carry the behavioral burden. It does disclose two real traits: the result set includes failures (not just successes) and the operation is free/no-cost. It says nothing about authentication requirements, pagination, or result ordering, so coverage is partial.

Agents need to know what a tool does to the 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 purpose is front-loaded in the first line, which is good. However, the second paragraph is largely rhetorical justification ('a payout history that only shows successes is a claim, not a record') that consumes space which could have carried usage or parameter guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 explanation is unnecessary, and the description usefully states what the output contains (attempts, including failures) and that it is free. It still omits auth expectations and routing against closely related siblings, leaving gaps for a 3-param query tool with no annotations.

Complex tools with many parameters or behaviors need more documentation. 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%, and the description adds no parameter-level meaning at all. The npub, limit, and dpop_token semantics come entirely from the schema; the description neither clarifies dpop_token (undocumented) nor explains the required npub beyond the 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 opening line 'Every payment attempted, and how it went' gives a specific verb+resource (a history of all payout attempts) and the closing line clarifies it includes failures, not just successes. It is distinguishable from a success-only listing, but it never names or differentiates against the real siblings such as beesknees_settlement_history or beesknees_check_payment.

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

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

There is no explicit when-to-use guidance or statement of alternatives. 'Free on purpose' hints at the no-cost condition, but nothing tells the agent when to reach for this tool versus beesknees_payout, beesknees_check_payment, or beesknees_settlement_history.

Agents often have multiple tools that could apply. Explicit usage 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 does so well: it discloses the key-custody model ('never holds a patron nsec'), the authorization model ('the signature is the authorization — no proof token'), the server-side verification step (signature must match the npub), and the cost ('Free'). These are exactly the behavioral traits an agent needs before invoking a publish/signing 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?

Front-loaded with the one-line purpose, then a compact paragraph explaining the signing/verification flow. Every sentence carries information, though the prose is slightly denser than strictly necessary.

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

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

An output schema exists, so return values need not be described. Given a no-annotation, free, signature-verified publish tool, the description covers the auth model, custody, verification, and cost — nothing an agent needs in order to call it correctly 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 description coverage is 100%, so the schema already documents both npub and signed_event. The description reinforces their meaning (client-signed event must be signed by the npub) but adds no syntax, format, or validation detail beyond the schema — 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?

Specific verb (Publish) + resource (CLIENT-SIGNED kind-0 profile) + target (relays for an npub). It is clearly distinguishable from the read-side sibling beesknees_get_nostr_profile without opening either schema.

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

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

It explains the calling context precisely: the frontend signs the kind-0 event with a session key or NIP-07 extension and passes the signed JSON here, while the wheel only verifies and relays. It does not explicitly name the alternative (get_nostr_profile) or state when not to use this tool, so it stops short of a 5.

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

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

With no annotations, the description carries the burden and does well: it discloses that this only creates an invoice (not a completed purchase), that payment happens externally in a Lightning wallet, that a separate check_payment call is needed, and that npub ownership proof is required. It omits invoice expiry, failure handling, or rate limits, keeping it below a 5.

Agents need to know what a tool does to the 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 lines, front-loaded with the core action, followed by the workflow and prerequisites. Every sentence earns its place and nothing is 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?

An output schema exists so return values need not be explained, and the description covers the essential multi-step workflow and auth prerequisite. Minor gaps around invoice lifetime and error behavior remain, but the agent has what it needs to invoke the tool correctly.

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

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

Schema description coverage is 100% and the dpop_token/amount_sats fields are documented in detail in the schema itself. The description adds no parameter-level detail beyond what the schema already provides, so the baseline 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?

States a specific verb and resource ('Buy credits via Bitcoin Lightning') and immediately identifies the mechanism (Lightning invoice). It is clearly distinguishable from siblings like check_payment or check_balance, which it names as the follow-up 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?

Gives the full usage flow: create invoice, pay with any Lightning wallet, then call check_payment to confirm. Also states the npub-proof prerequisite and that the call is free. It lacks explicit when-not guidance or a named alternative for other purchase paths, so it stops short of a 5.

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

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

With no annotations, the description carries full behavioral burden and delivers: one-shot deterministic semantics, channel-scoped draining, destructive side effects (wrong-phrase DMs deleted and sender NACK'd), the ACK/stop condition, the failure mode (courier_not_found), and a post-success side effect (payment processor client reinitialized, no restart needed). This is unusually rich disclosure.

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

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

Front-loads the core action, then flow context, then the usage warning, then mechanics. Dense but every sentence carries information; a few parentheticals and the flow aside could be trimmed, which keeps it just short of ideal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 required, yet the description still surfaces the notable result (courier_not_found). Given the multi-step credential-delivery flow and destructive relay behavior, nothing an agent needs to call this correctly 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%, so the schema already documents each field, but the description adds real meaning: the (sender_npub, service, dpop_token) tuple identifies the response, credential_card redemption bypasses the relay and makes dpop_token unnecessary, and dpop_token is characterized as the session phrase from request_credential_channel. It clarifies inter-parameter relationships the schema treats only in isolation.

Input schemas describe structure but not intent. Descriptions should explain 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+resource ('Pick up credentials from the Secure Courier') and names the exact flow it belongs to. It also explicitly distinguishes itself from its counterpart receive_npub_proof, so an agent can tell the two apart without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 an explicit precondition ('Call this only after the user confirms they have replied'), names the predecessor tool request_credential_channel, and delivers a strong exclusion ('Do NOT poll, loop, or retry'). The alternative path (credential_card bypassing the relay) is also described with its own condition.

Agents often have multiple tools that could apply. Explicit usage 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 delivers: one-shot deterministic retrieval, relay-draining scope, mismatch handling (delete + NACK without revealing the phrase), failure mode if called early, the token lifecycle, and that the proof is stored as a hash while the raw token is never stored. This is unusually rich behavioral disclosure.

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

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

Front-loads purpose, then the critical precondition in bold, then mechanics and token lifecycle. It is somewhat long, but nearly every sentence conveys a distinct operational constraint, so little is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool with an output schema, the description covers the flow position, prerequisite, timing constraint, failure behavior, and return-token handling. Nothing an agent needs to call it correctly 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%, so the schema documents both params; the description still adds value by explaining that dpop_token is the value returned by request_npub_proof and must be persisted and re-passed on every subsequent paid call. That lifecycle meaning exceeds the 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?

States a specific verb+resource ('Receive npub ownership confirmation from a patron') and situates it in a named flow, explicitly distinguishing it from its counterpart 'receive_credentials'. An agent can identify the tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 an explicit precondition ('Call this only after the user confirms they have replied') and an explicit anti-pattern ('Do NOT poll, loop, or retry'), and names the prerequisite tool 'request_npub_proof'. The when/when-not conditions are fully spelled out.

Agents often have multiple tools that could apply. Explicit usage 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 does well: it discloses validation of the window and total cap, per-patron redemption recording, automatic discount application on later paid calls until uses_per_patron is exhausted, that it is free, requires proof of npub, and is idempotent. It omits what a failed validation (expired/over-cap) returns, but the behavioral profile is otherwise rich.

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

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

Front-loaded with the purpose, then mechanics, then cost/idempotency notes. Sentences are compact and mostly earn their place, though a few could be tightened.

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

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

An output schema exists, so return values need not be explained. Behavior, cost, auth requirement, and idempotency are all covered; the gaps are the undocumented dpop_token and the absence of failure-mode description.

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

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

Schema coverage is 0%, so the description must compensate. It adds meaning for `code` and `npub` (proof required), but leaves `dpop_token` entirely undocumented and gives no format detail for npub.

Input schemas describe structure but not intent. Descriptions should explain 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+resource ('Claim a coupon') and clarifies the identifier ('by its name, the code the operator shared'), which clearly separates it from mint_coupon, delete_coupon, and list_coupons. However, it never names a sibling explicitly to route the agent between 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?

The context ('the code the operator shared') implies when a patron would call it, but there is no explicit when-to-use/when-not guidance or named alternative. The agent must infer the trigger condition from the phrasing.

Agents often have multiple tools that could apply. Explicit usage 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 does so well: it discloses that a small fee is charged (anti-abuse), that the report is PUBLIC and lands in maintainers' normal triage, that nothing is verified, that the npub is stamped as author of record, and the exact fallback behavior ("issue reporting not configured", no charge). These are real behavioral traits an agent needs before invoking.

Agents need to know what a tool does to the 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 purpose is front-loaded in the first sentence and each subsequent sentence adds a distinct fact (authorship, fee, publicness, return shape, fallback). It is slightly dense with parentheticals, but nothing is 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?

An output schema exists, so return values need not be spelled out, yet the description still names the key return (repo, number, url) plus the non-configured outcome. Combined with the cost, attribution, and publicness disclosures, an agent has everything needed to invoke this external-write tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the npub-as-author-of-record and proof requirements and adds the fee concept, but it does not add format or semantics for any parameter beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain 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 (file/report) and resource (a field report as a GitHub issue on the operator's repo), and the second paragraph makes the intended subject explicit (a tool's wrong or confusing metadata/response). No sibling tool covers this reporting function, so it is trivially distinguishable from the rest of the beesknees_* set.

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

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

"Found a tool's metadata or response wrong or confusing? Report it where the tool lives" gives a clear triggering condition for use. It does not name an alternative or a when-not case, but there is no competing report tool to route against, so the only real gap is the absence of explicit exclusions.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses the authorization requirement (must prove control of the operator's npub), the mechanics (resolves the Authority's MCP endpoint, mints an inline proof with the nsec, delivers MCP-to-MCP), and the async state transition (records as pending, flips to 'ready' on provisioning). This is exactly the behavioral context an agent needs.

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

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

Front-loaded with the action, then the restriction, then the mechanism, then the follow-up, so an agent can stop reading once it has what it needs. Slightly verbose in the middle clauses, but every sentence carries signal.

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

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

An output schema exists, so return values needn't be explained. The description covers prerequisites, delivery mechanics, and the async lifecycle with the correct polling target, leaving nothing essential for correct invocation 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 description coverage is 100%, so the schema already documents all four parameters, making 3 the baseline. The description adds conceptual meaning to the proof (dpop_token) and endpoint (service_url) but does not give parameter-level format or usage detail 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?

States a specific verb and resource ('request adoption' of 'this operator' by a chosen Authority) and distinguishes itself from siblings like adoption_status, which it explicitly frames as the follow-up tool. An agent can tell what this does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clear context: use it to ask an Authority to adopt the operator, and it explicitly routes the agent to 'Poll adoption_status for progress' rather than re-invoking. It also states the operator-only restriction, but there is no explicit when-not-to-use or named alternative beyond the polling follow-up.

Agents often have multiple tools that could apply. Explicit usage 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: it discloses the welcome DM with a credential template, that the flow is human-in-the-loop requiring manual reply, and the critical destructive trait that each receive_credentials call drains the relay mailbox. This is unusually rich disclosure for a mutation-adjacent flow.

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

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

Front-loads purpose, then differentiation, then the operational flow and warnings. Every sentence earns its place — the when-not guidance and the do-not-poll instruction are all actionable, with no 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?

An output schema exists, so return values need not be explained. For a human-in-the-loop tool with no annotations, the description covers prerequisites (check service_status), the required stopping point, and the sequencing to receive_credentials — everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents 'service' and 'sender_npub' including their sources. The description adds no syntax or format detail beyond what the schema provides, so the baseline 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?

States a specific verb and resource ('Open a Secure Courier channel for credential delivery') and immediately scopes it as the CREDENTIAL-DELIVERY flow, distinguishing it from sibling flows. An agent can tell it apart from request_npub_proof and receive_credentials without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 names the condition that selects this tool (handing over a service secret like API keys/tokens) and the alternatives for other cases: request_npub_proof for npub proofs and service_status for dynamic/OAuth2 services that need no couriered secret. It also gives a sequencing rule — stop after calling, wait for user confirmation, do not poll.

Agents often have multiple tools that could apply. Explicit usage 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 does so richly: it discloses that this is a human-in-the-loop flow, that the receive step destructively drains the relay mailbox (hence no polling), that the returned dpop_token must be retained and passed on every subsequent paid call, that the MCP does not persist it across restarts, and that the tool is free. These are exactly the operational traits an agent cannot infer from schema alone.

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

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

Front-loads the purpose and routing rule, then uses bold section headers (Returns, Lifecycle) to organize dense but non-redundant content. Given the multi-step asynchronous human-in-the-loop nature of the flow, every sentence (including the emphasis on MUST/STOP/do-not-poll) earns its place.

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

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

An output schema exists, so return values need not be explained, yet the description still surfaces the critical dpop_token contract and retention requirement. Combined with the lifecycle and pairing with receive_npub_proof, an agent has everything needed to invoke this tool correctly and hand off to the next step.

Complex tools with many parameters or behaviors need more documentation. 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 fully documents reason, verify_at, and patron_npub, establishing the baseline of 3. The main description body does not add parameter-level meaning beyond the schema (it only references the dpop_token return value), so no credit above baseline is warranted.

Input schemas describe structure but not intent. Descriptions should explain 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+resource ('Request npub ownership proof from a patron via Nostr DM') and immediately scopes it against siblings: this is the ownership-proof flow, NOT the secret-delivery flow, and it explicitly names request_credential_channel as the alternative for API keys/OAuth secrets. An agent can distinguish it from receive_npub_proof and request_credential_channel without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the triggering condition ('use it when a call returns proof_required'), names the alternative and its distinct purpose, and provides an explicit operational sequence: STOP, tell the user, wait for confirmation, do NOT poll or retry. It also covers the expiry lifecycle and when to re-invoke. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage 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 behavioral burden. It discloses destructive deletion of every stored model, reinitialization behavior with all tools at 0 sats, the return value, and the nsec-signed operator proof requirement. It does not explicitly state irreversibility or confirmation behavior, but most critical traits are covered.

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