tollbooth-authority-northamerica

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

With no annotations provided, the description adequately discloses key behaviors: it is free (no credits consumed), requires a proof-of-ownership token (dpop_token), and returns a specific set of data. This gives the agent a good understanding of the tool's effects and prerequisites.

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

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

The description is concise, well-structured, and front-loaded with the core purpose. Every sentence provides useful information without redundancy.

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

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

The description lists all major components of the output (purchase history, credit tranches, usage breakdown, daily logs), and the context indicates an output schema exists. For a tool with 3 parameters and an output schema, this is complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds that dpop_token is for proof of ownership, and mentions the default for days (30), but does not significantly enrich the schema documentation.

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

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

The description clearly states the tool generates a patron's account statement, listing specific returned data (purchase history, credit tranches, usage breakdown, daily logs) and distinguishes it from the operator's tax balance. Sibling tool names like authority_check_balance and authority_account_statement_infographic reinforce this differentiation.

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

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

The description explicitly mentions the tool is free and requires proof of npub ownership, which helps the agent understand when to use it. However, it does not provide direct comparison to alternatives or state when not to use it, only implying it is not for operator tax balance.

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

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

With no annotations, the description takes on the burden and discloses the cost (1 api_sat per call) and verification process (debit_or_deny). It also describes the output components but doesn't mention potential side effects or state changes, though likely none exist.

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

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

Two sentences with no waste: the first states the tool's action, the second details output, cost, and verification. Information is front-loaded.

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

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

Given the presence of an output schema, the description adequately covers return behavior. It also adds cost and verification context, making it largely complete for this generation tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by specifying that dpop_token must be a kind-27235 Nostr event, which is not in the schema.

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

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

The description clearly states the tool generates a visual SVG infographic of an account statement, distinguishing it from the sibling tool authority_account_statement by noting it returns the same data but in a visual format.

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

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

The description implies when to use this tool (when a visual infographic is desired) and includes cost and verification details, but lacks explicit when-not-to-use guidance or alternative recommendations.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool is free and polls the Authority, implying a read operation, but does not explicitly state non-destructiveness, authentication requirements, or rate limits. The behavioral context is minimal.

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

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

The description is very short and front-loaded with the core purpose. Every sentence adds value, though the line breaks are unnecessary. It earns its place but could benefit from more structured presentation.

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

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

Despite having an output schema (not shown), the description lacks parameter explanations, usage guidelines, and behavioral details. For a tool with 2 parameters and many siblings, this is incomplete and leaves gaps for the agent.

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

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

Schema description coverage is 0%. The description does not explain either parameter. 'authority_npub' is implied but not defined, and 'dpop_token' is completely absent. For a required parameter, this is a significant gap.

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

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

The description clearly identifies the verb 'check' and the resource 'adoption-request status'. It specifies the scope ('at a chosen Authority') and adds context ('Free', 'Polls the Authority MCP-to-MCP'). However, it does not differentiate from the sibling tool 'authority_get_adoption_status', which may cause confusion.

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

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

No explicit guidance on when to use this tool versus alternatives. The description only states it is 'Free' and 'Polls', but does not mention prerequisites, limitations, or when not to use it. Given the large number of sibling tools, usage guidance would be valuable.

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

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

The description mentions the same consent and provisioning effect as register_operator, giving some behavioral context. However, with no annotations, it lacks details on side effects, prerequisites, or edge cases.

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

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

The description is two sentences, front-loads the main action, and uses a comparative example efficiently. No unnecessary words.

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

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

Given the presence of an output schema and 100% parameter coverage, the description is largely complete. It could elaborate on when the request is considered pending, but it sufficiently covers the core function.

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

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

Schema coverage is 100%, but the description adds value by explaining that authority_proof is the same consent as in register_operator and that operator_npub is the operator to approve. This adds meaning beyond the schema.

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

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

The description clearly states the action ('Approve a pending request and provision the operator') and distinguishes it from the sibling tool 'register_operator' as its deferred counterpart. It uses specific verbs and resources.

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

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

The description provides context by positioning the tool as the deferred-courtship counterpart to register_operator, indicating it is used for later approval. This implies when to use but does not explicitly state when not to use or provide alternative tools.

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

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

No annotations exist, so the description must carry the burden. It discloses that the paid_tool decorator handles fee debit and stores cost, and that no recomputation is needed. However, it lacks details on authorization requirements, idempotency, or failure behavior, leaving gaps in safety understanding.

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

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

The description is concise with three short sentences, each serving a distinct purpose: stating the main function, detailing internal behavior, and specifying the caller. No wasted words.

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

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

The description provides adequate context for usage but leaves gaps: one parameter is undocumented, and safety/authorization details are missing. The existence of an output schema reduces burden, but the description does not fully compensate for missing 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?

The description does not add meaning beyond the input schema. One parameter (dpop_token) is undocumented in both schema and description, and the description does not clarify the format or constraints for npub or amount_sats beyond what the schema provides.

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

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

The description clearly states the tool certifies a purchase order and returns a Schnorr-signed Nostr event certificate. It specifies it is called by operator MCP servers when a patron purchases credits, distinguishing it from sibling tools like authority_purchase_credits.

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

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

The description explicitly states this tool is called by operator MCP servers, not end users, when a patron purchases credits. It provides clear context but does not mention when not to use it or alternatives like authority_purchase_credits for end users.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It mentions checking and activation but does not describe side effects (e.g., state changes, idempotency, failure behavior, authorization needs). For a mutation action, this is insufficient.

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

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

The description is extremely concise, using a single sentence with no redundant words. It front-loads the step number and clearly states the action. Every part is meaningful and efficiently conveys the tool's role.

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

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

Given the tool's simplicity (one parameter, clear action), the description provides adequate high-level context. However, it lacks details about the activation process, error conditions, and expected output. The existence of an output schema partially mitigates this, but behavioral completeness is still lacking.

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

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

The schema already describes the parameter (candidate_npub) with 100% coverage. The description adds minimal value beyond the schema, essentially restating the purpose. The baseline of 3 is appropriate as the description does not hinder understanding.

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

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

The description clearly states the tool's purpose: 'check parent approval, activate Authority' and identifies it as Step 3/3 of Authority onboarding. This differentiates it from sibling tools like authority_approve_adoption (approval only) or authority_check_authority_balance (balance check). However, the exact meaning of 'activate Authority' could be clearer.

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

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

The description implies usage context by naming it Step 3/3 of Authority onboarding, but it does not explicitly state prerequisites, when not to use, or provide alternatives. The step number gives implied guidance on ordering but lacks explicit usage boundaries.

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

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

Despite no annotations, description discloses that the tool returns sats available for certification, behavior when zero, and that it is free. Adds decision-relevant behavioral context beyond mere existence.

Agents need to know what a tool does to the 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 concise sentences, front-loaded with purpose, then details, then distinction. No extraneous information.

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

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

For a zero-parameter tool with output schema, description provides sufficient context: what it returns, consequence of zero balance, next steps, and clarification of scope.

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

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

No parameters exist in schema; description need not add parameter info. Baseline 4 applies as schema coverage is complete.

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

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

Description clearly states verb 'Check' and resource 'this operator's tax balance at the Authority', distinguishing it from siblings like authority_check_balance by specifying it's the operator's own funding for patron credit certification.

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

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

Provides usage context: when balance is zero, patron top-ups fail and operator must call purchase_credits. Clarifies it's not a patron balance, but does not explicitly exclude alternative sibling tools.

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

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

With no annotations, description fully shoulders behavioral info: free operation, requires dpop_token proof, prevents enumeration. Lacks detail on error handling but covers key constraints.

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

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

Concise, front-loaded purpose, every sentence adds essential info, 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?

Given output schema existence, no need to detail returns. Covers purpose, usage conditions, proof requirement, and sibling differentiation. Complete for a balance check tool.

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

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

Schema has 100% coverage so baseline is 3. Description adds value by explaining dpop_token is a kind-27235 Nostr event, beyond schema description.

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

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

States specific verb 'Check' and resource 'patron's credit balance at this operator'. Differentiates from sibling for operator balance with explicit reference.

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

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

Explicitly says when to use (check patron balance) and when not (use authority_check_balance for operator balance). Mentions prerequisites: proof of npub ownership, free no credits.

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

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

No annotations are provided, and the description only says 'look up', which implies a read-only operation, but it does not disclose safety, side effects, authorization, or rate limits. The description carries the full burden and fails to provide sufficient behavioral detail.

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

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

The description is a single sentence with no fluff, but it could be slightly more informative without becoming verbose. It achieves conciseness but at the cost of missing parameter and usage details.

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

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

Given the low complexity (1 param, output schema exists), the description is somewhat complete for a simple lookup, but gaps in parameter semantics and usage guidelines reduce its overall completeness.

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

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

Schema description coverage is 0%, and the description does not explain what an npub is or its format/length. The description adds no meaning beyond the parameter name, which is insufficient for a single required parameter.

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

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

The description clearly states the verb 'look up' and the resource 'npub in the DPYC community registry', making it specific and distinct from sibling tools like authority_check_balance or authority_check_payment.

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

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

The description implies usage when checking DPYC membership but does not explicitly guide when to use this tool over others, nor does it mention any prerequisites or exclusions.

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

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

No annotations provided, so description bears full burden. Discloses free usage, no credit consumption, and security rationale (front-running prevention). Does not detail error cases or response format, but output schema exists.

Agents need to know what a tool does to the 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 focused sentences, front-loaded with purpose, no filler. Every sentence adds necessary context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 status-check tool, description covers prerequisites, cost, security, and sequencing. Output schema handles return value documentation.

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

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

Schema covers all three parameters with 100% description coverage. Description adds only a usage note on invoice_id ('returned by purchase_credits'), which is helpful but not essential.

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

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

Description clearly states 'Check the payment status of a Lightning invoice' and ties it to a specific predecessor tool (purchase_credits), distinguishing it from over 60 sibling tools.

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

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

Explicitly says 'Call after paying the invoice from purchase_credits' and notes prerequisites (npub ownership proof). Does not list alternatives, but context is sufficient for correct 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?

The description discloses that the tool is free ('no credits required') and implies it does not execute the tool call, as it previews cost. However, with no annotations, the description does not cover authentication, rate limits, or error conditions. The information adds moderate value beyond the tool name.

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

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

The description is three sentences, with the first sentence clearly stating the purpose. It contains no filler or repetition, and every sentence adds information about the tool's function and cost.

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

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

The description explains the tool's core purpose and cost behavior but lacks usage guidelines and parameter explanations. Given the tool has an output schema and four parameters, the description provides adequate but not complete context for effective use.

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

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

Schema coverage is 50%, with npub and dpop_token lacking descriptions. The tool description does not explain any parameters or provide context beyond the schema. It fails to compensate for the missing parameter documentation, leaving ambiguity about their purpose.

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

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

The description clearly states the tool previews the effective cost of a tool call and specifies it shows base cost and constraint effects like discounts and surge pricing. The verb 'preview' and resource 'cost of a tool call' are specific, and the name authority_check_price distinguishes it from sibling check tools that check balances or payments.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, required context, or when not to use it. For example, it does not differentiate use cases from authority_check_balance or other check 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?

The description explicitly states the tool is free, has no side effects, does not evict the cache, and does not touch relays. Since no annotations are provided, this fully informs the agent of behavioral traits.

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

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

The description is three sentences, front-loads the purpose, and contains no redundant information. Every sentence adds value.

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

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

Given the tool is a simple status check with an output schema, the description covers the essential context: purpose, when to use, and lack of side effects. It is complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema; it mentions that dpop_token is returned by other tools, but does not significantly augment parameter understanding.

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

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

The description clearly states the tool checks the validity of a cached dpop_token, using specific verb and resource. It distinguishes itself from the sibling check_oauth_status by noting it mirrors that flow for the npub-proof path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 advises using this tool before paid calls to avoid burning credits on guaranteed failure. It implies appropriate context but does not explicitly state when not to use or list alternatives.

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

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

No annotations are provided, so the description carries full burden for behavior disclosure. It mentions verifying a DM and escalating to a parent authority, but does not disclose side effects (e.g., state changes, permissions needed, destructive actions like rejecting if verification fails). The explanation of parent resolution is a positive, but overall transparency is insufficient for a mutation tool in a multi-step process.

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

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

The description is three sentences and front-loads the essential context ('Step 2/3 of Authority onboarding'). The examples provided add specificity but are somewhat verbose. Every sentence contributes value, though the last sentence on chain depth could be condensed.

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

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

Given the tool is part of a critical multi-step onboarding process, the description lacks important information such as prerequisites (what must have happened in step 1), expected outcomes, return values (output schema exists but not described), and error conditions. Without annotations, this leaves the agent underinformed for correct invocation.

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

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

The input schema has 100% description coverage for the sole parameter `candidate_npub`, describing it as 'The Nostr npub of the candidate who replied to the DM challenge.' The tool description adds context about the verification step but does not enhance parameter meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as 'Step 2/3 of Authority onboarding' with specific actions 'verify candidate DM' and 'escalate to parent Authority'. This provides a clear verb+resource combination and distinguishes it from sibling tools by placing it in a multi-step process. However, the term 'DM' is ambiguous without context, slightly reducing clarity.

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

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

The description implies usage context by stating it is step 2 of a three-step onboarding flow. However, it does not explicitly state when to use or not use the tool, nor does it mention alternative tools (e.g., when might step 1 or 3 be used). The sibling list includes many authority tools, but no guidance on selection is provided.

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

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

With no annotations, the description effectively discloses the cascade behavior, no-op effect on chain steps, and warning surfacing. It also states the access restriction. It does not cover authorization details or rate limits, but the key behaviors are clear.

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

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

The description is concise and well-structured: action, cascade behavior, restriction. Every sentence adds value with no redundancy.

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

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

Given the presence of an output schema, the description adequately covers the tool's effects and constraints. However, the lack of parameter documentation makes it slightly incomplete for a tool with 2 parameters.

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

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

The input schema has 0% description coverage, and the description does not explain the purpose of 'coupon_id' or 'dpop_token'. The description focuses on behavior rather than parameter meaning, leaving the agent with only the parameter names and types.

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

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

The description clearly states 'Delete a coupon' with a specific verb and resource. It also explains the cascading effect on redemptions and chain steps, distinguishing it from sibling tools like mint, update, list, or forget.

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

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

The description mentions that the operation is restricted to operators and requires proof, giving some context. However, it does not explicitly state when to use this tool vs alternatives like 'authority_forget_coupon' or when not to use it.

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

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

The description identifies the operation as a write to a sensitive vault and highlights the need for proof, but does not detail reversibility, error behavior, or impact on other fields. No annotations are present.

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

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

The description is two sentences with clear, front-loaded purpose. Every sentence adds value without redundancy.

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

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

The description covers the core action and prerequisites, and an output schema exists to handle return details. It lacks mention of edge cases like nonexistent fields, but is adequate for a simple delete tool.

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

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

Schema coverage is 100% and the description adds minimal extra meaning beyond the schema, such as noting the dpop_token requirement. It does not elaborate on parameter syntax or constraints.

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

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

The description clearly states the tool removes a single patron credential field and distinguishes it from related tools like authority_update_patron_credential or authority_forget_credentials by specifying it operates on one field at a time.

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

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

The description mentions the tool is free and requires proof of npub ownership via a dpop_token, but does not explicitly state when not to use it or list alternatives. However, the sibling tools provide context.

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

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

With no annotations, the description carries the full burden. It discloses the two-proof requirement and a security risk (operator removal without authority proof). However, it does not explain the role of the `dpop_token` parameter, side effects, or whether removal is reversible. The behavior is partially transparent.

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

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

The description is relatively concise with an initial action statement followed by a bullet-like list of requirements. The security context adds important value without excessive verbosity. It is well-structured and front-loaded.

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

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

Output schema exists, so return values are handled. However, the input parameter `dpop_token` is not explained, and the description omits prerequisites like operator registration status. It references register_operator without cross-tool clarity. The description covers the core behavior but leaves gaps.

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

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

The input schema has three parameters; the description adds useful context for `authority_proof` but ignores `dpop_token` entirely. It also mentions a `proof` parameter that does not exist in the schema, causing confusion. Only 67% of parameters have schema descriptions, and the description fails to compensate for the missing `dpop_token` explanation.

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

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

The description clearly states the action 'Remove an Operator from the DPYC community registry'. The verb 'Remove' and resource 'Operator' are specific, and it distinguishes itself from sibling tools by being the only deregister tool. However, it references register_operator without full explanation, slightly reducing clarity.

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

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

The description mentions required proofs but does not explicitly state when to use this tool versus alternatives. No scenarios or exclusions are provided. The security warning about unauthorized removal implies a caution but does not serve as a usage guideline.

Agents often have multiple tools that could apply. Explicit usage 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 discloses the key behavioral trait (cosmetic only, coupon still exists) but lacks details on idempotency, error states, or side effects. This adds value beyond the schema but is not exhaustive.

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

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

The description is two sentences, front-loaded with the action, and every sentence provides necessary context without redundancy.

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

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

Given the tool's simplicity and existence of an output schema, the description adequately explains the effect (cosmetic removal) but fails to document parameters or output. It is minimally complete for a basic operation.

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

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

Schema description coverage is 0%, and the description only loosely references 'npub' without explaining any parameter's purpose, format, or role. coupon_id and dpop_token are entirely undocumented, leaving the agent with insufficient guidance.

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

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

The description clearly states the verb 'Remove' and the resource 'coupon from this patron's redemption list.' It distinguishes from sibling tools like authority_delete_coupon by noting the cosmetic nature.

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

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

The description explains that the removal is cosmetic and the coupon remains redeemable, providing context for when to use it versus permanent deletion. It also mentions the requirement for 'proof of npub,' but does not explicitly list alternatives or non-usage scenarios.

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

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

Discloses that deletion is as destructive as a write and always requires proof of npub ownership via dpop_token. Since no annotations are provided, the description fully covers behavioral traits.

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

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

Three sentences with no redundancy. Each sentence adds necessary information: what it does, how to use, and a warning.

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

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

Complete for a deletion tool with full schema coverage and an output schema. The description covers authentication requirements and destructive behavior, leaving no ambiguity.

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

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

All three parameters are already described in the schema (100% coverage). The description adds value by clarifying the roles of npub (operator vs. patron) and the dpop_token requirement, going beyond the schema.

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

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

The description clearly states it deletes vaulted credentials for a specific service and npub. It uses the verb 'delete' and specifies the resource and parameters, distinguishing it from sibling tools like authority_delete_patron_credential.

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

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

Provides explicit guidance on when to use operator vs. patron npub, and warns that deletion is destructive and requires proof of ownership. This helps the agent decide when to invoke the 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 must carry the behavioral burden. It discloses that the operation is a read, free (no cost), and requires no proof (authentication). This is good transparency for a read tool.

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

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

The description is short (two sentences) and mostly front-loaded. The second sentence references another tool, which adds some noise but is still concise.

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

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

With an output schema present and a simple single-parameter input, the description covers the essential context. It explains who can use it (operator) and the nature (free, no proof). No missing critical details.

Complex tools with many parameters or behaviors need more documentation. 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 describes the parameter. The description adds no new semantic meaning beyond what the schema provides, only contextual remarks about cost and authentication.

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

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

The description clearly states it reads an operator's adoption-request status. It adds context (free, no proof) but doesn't explicitly differentiate from siblings like authority_adoption_status, which has a similar name.

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

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

The description implies use by operators to poll their own status and references another tool (adoption_status) for polling. However, it doesn't explicitly state when to use this vs alternatives or provide 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?

Discloses it returns latest metadata fields, lists fields, and mentions empty profile case, with no side effects (read-only). No annotations, so description carries full burden and does so effectively.

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

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

Two concise sentences: first states purpose, second adds value (free, no proof, returns list, empty case). Front-loaded and 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?

Handles the full scope: what it reads, what it returns (including empty profile), and usage conditions. Output schema exists, but description adds extra clarity.

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

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

Only parameter npub is described implicitly by the tool purpose, but schema description coverage is 0%; the description adds context about usage but lacks explicit parameter format or example.

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

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

The description clearly states the tool reads a public Nostr profile via npub, specifying it's NIP-01 kind-0 metadata, which distinguishes it from sibling tools like authority_publish_nostr_profile (write).

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

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

Provides context that it's free and requires no proof because data is public, implicitly distinguishing from write operations, but does not explicitly list when to avoid using it or compare with alternatives.

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

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

No annotations provided, so the description carries full burden. It mentions the action (generate proof) but not side effects, prerequisites, or behavior like read-only nature.

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

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

Single sentence, front-loaded verb, no unnecessary words. Highly concise and well-structured.

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

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

Output schema exists, so return values may be covered. However, the description lacks context about Merkle proofs or how to interpret the result, leaving some gaps.

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

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

Schema coverage is 100%, with descriptions for both parameters. The description adds no extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Generate' and the resource 'Merkle inclusion proof' for a patron's balance in a Bitcoin-notarized snapshot. It is specific but does not differentiate from sibling tools.

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

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

No guidance on when to use this tool versus alternatives. The description implies use for generating proofs but lacks exclusions or context.

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

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

No annotations provided, so the description carries full burden. It discloses the authentication gate (Schnorr signature) but does not cover idempotency, side effects, or rate limits. As a retrieval tool, 'retrieve' implies read-only, but without explicit statement.

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

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

Two concise sentences with front-loaded purpose. No extraneous information; every word earns its place.

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

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

Given the tool has an output schema (unknown but assumed), the description may not need to detail return values. However, the description lacks guidance on when to use this tool versus related ones and does not explain the 'dpop_token' parameter, leaving some contextual 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 50%: 'npub' is described in schema as 'Your Nostr npub (bech32)', and the description adds no extra meaning. The 'dpop_token' parameter is undocumented in both schema and description, leaving a gap.

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

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

The description clearly states the tool retrieves operator bootstrap configuration (Neon URL, schema), with a specific verb and resource. It is distinct from siblings like 'authority_operator_status' and 'authority_repair_operator_schema', but lacks explicit differentiation.

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

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

The description mentions the Schnorr signature requirement for ownership proof, implying a prerequisite, but does not specify when to use this tool versus alternatives or any exclusions.

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

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

No annotations provided, so description carries full burden. It implies a safe read operation but does not disclose authentication requirements, data freshness, or any side effects beyond reporting status. 'Free' hint is minimal.

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

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

Two concise sentences, no wasted words. First sentence states core purpose, second sentence provides alternative. Clean and structured.

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

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

Given no parameters and output schema exists, description adequately covers tool's value. It explains what is reported and how it differs from a sibling. Could possibly mention output format but not required.

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

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

No parameters, so baseline is 4. Description adds context about what the report covers (configured vs missing, delivery guidance), which is useful beyond the empty schema.

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

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

The description uses specific verb 'Report' and resource 'operator onboarding status', clearly stating it shows configuration readiness, missing settings, and how to deliver them. It distinguishes from 'get_patron_onboarding_status'.

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

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

Explicitly states when not to use (for patron-level) and recommends alternative 'get_patron_onboarding_status'. Does not mention other alternatives among many siblings, but provides clear guidance for a key distinction.

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

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

With no annotations, the description fully discloses key behaviors: values are never exposed, it's free, proof of npub ownership is required, and the list is sensitive because it reveals integrations. This goes beyond basic safety.

Agents need to know what a tool does to the 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 paragraphs, front-loaded with the primary action. It's concise and every sentence adds value, though the second paragraph could be slightly more compact.

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

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

Given the tool has only 2 parameters and an output schema exists, the description is fully complete: it explains what is returned (field names), what is not (values), security requirements, and sensitivity. No gaps.

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

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

Schema coverage is 100% for both parameters (npub and dpop_token). The description adds 'Proof of npub ownership is required' but doesn't provide new parameter-level details beyond what the schema already gives. Baseline 3 is appropriate.

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

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

The description clearly states 'List stored patron credential field names (not values)' with specific verb ('list') and resource ('patron credential field names'). It distinguishes from siblings like authority_get_operator_config or authority_get_patron_onboarding_status by focusing on credential fields.

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

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

The description says 'use this to verify which fields are configured' and provides context (free, requires proof of npub ownership). It doesn't explicitly mention when not to use or suggest alternatives, but the context is clear enough for an agent to decide.

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

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

With no annotations provided, the description fully discloses key behavioral traits: the tool is free, requires proof of npub ownership, explains why (sensitive info about patron setup), and describes different behaviors for set-once vs. dynamic services. This provides excellent transparency beyond a typical tool description.

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

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

The description is relatively concise, using two paragraphs to convey purpose, behavior, and usage notes. It front-loads the main action. However, it could be slightly more streamlined by merging some sentences, but overall it is well-structured and efficient.

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

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

Given the tool's complexity (two service types, sensitive info), and the presence of an output schema (which handles return values), the description is complete. It covers purpose, usage, behavioral traits, and prerequisites without leaving obvious gaps.

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

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

The input schema already has 100% description coverage for both parameters. The description adds context that proof of npub ownership is required, but it does not enhance the semantic meaning of the parameters themselves beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states that the tool reports a patron's credential readiness for an operator. It distinguishes between set-once services (eXcalibur, TheBrain) and dynamic/OAuth2 services (Schwab), providing specific examples. This level of detail distinguishes it from sibling tools like authority_get_operator_onboarding_status.

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

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

The description indicates when to use the tool: to check credential readiness for a patron. It implies that for operator-level onboarding, a sibling tool exists, but it does not explicitly state when not to use it or name alternatives. It does mention prerequisites (npub ownership proof), which guides usage.

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

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

With no annotations, the description fully bears transparency burden. It reveals the tool is free, self-initializes a scaffold if no model exists, and clarifies that no economic data is inferred from code. These are valuable behavioral disclosures.

Agents need to know what a tool does to the 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 purpose. Every sentence adds unique value without redundancy. Efficient and well-structured.

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

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

Despite having an output schema, the description fully covers the tool's behavior with zero parameters. It explains edge cases (self-initialization) and cost (free), making it complete for an agent.

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

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

No parameters exist and schema coverage is 100%, so baseline is 4. The description does not need to add param information.

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

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

The description clearly states the tool retrieves the active pricing model for the operator, using specific verb 'Get' and resource 'pricing model'. It distinguishes from sibling tools like set and reset.

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

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

Explicitly mentions 'Free' and describes what happens when no model exists (self-initializes). It implies when to use (to read the model) but does not explicitly exclude alternatives like set or reset.

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

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

With no annotations, the description carries the full burden. It discloses the key behavioral trait: the need for owner consent proof (authority_proof). It implies a read operation by saying 'list pending' and mentions 'review-on-your-own-time', which suggests no side effects. This is sufficient for a simple list tool.

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

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

The description is extremely concise: two sentences covering purpose, restriction, and context. Every word adds value, with no redundancy. It front-loads the core verb and resource.

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

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

Given the tool's simplicity (single parameter, list operation) and the existence of an output schema, the description is complete. It covers the authorization requirement, the owner-specific scope, and the tool's role as a review surface, leaving no major gaps.

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

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

Schema coverage is 100% and the schema description for authority_proof already states 'Proof signed by the Authority's OWN npub (owner consent).' The tool description only indirectly references this via 'consent proof', adding no new meaning beyond the schema. The baseline score of 3 applies.

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

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

The description clearly states the tool lists pending operator-adoption requests for the owner queue, using specific verbs and resource. It distinguishes itself from siblings by specifying 'Owner queue' and 'Restricted to the Authority owner (consent proof)', making it unambiguous.

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

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

The description provides clear context that this tool is for the Authority owner to review pending requests, implying when to use it. While it doesn't explicitly list exclusions or alternatives, the 'review-on-your-own-time' phrasing and sibling tool names (e.g., authority_approve_adoption, authority_reject_adoption) effectively signal its role as a read-only listing.

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

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

With no annotations, the description fully discloses behavior: it is read-only ('Free, no side effects') and explains how the output reacts to renames (tool_id unchanged, mcp_name changes). This provides complete transparency about its behavior.

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

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

The description is brief but comprehensive, front-loading the core action in the first sentence. Every sentence adds value: purpose, use case, behavioral nuance, and safety guarantee. No redundant text.

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

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

Given no parameters and an existing output schema, the description sufficiently covers purpose and behavior. It mentions key output fields and how they change. Some details about exact return structure are omitted but not critical due to output schema.

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

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

The input schema has zero parameters, so no parameter explanations are needed. The description adds context about the output fields (tool_id, mcp_name, ...), which is useful even though not strictly required.

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

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

The description explicitly states the tool 'Return canonical (tool_id, mcp_name, …) for every registered tool,' clearly identifying the resource (canonical identities of all tools) and action (return list). It distinguishes itself from sibling tools by explaining it provides a global mapping of tool IDs to names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 specifies that this tool is 'the authoritative source for any client... that needs to know how this MCP identifies its tools' and mentions specific use cases like UUID-joining with pricing models. It does not explicitly state when not to use it, but the purpose is clear and context is provided.

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

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

No annotations are provided, so the description must carry behavioral disclosure. It states the tool is free and lists return values, but does not explicitly confirm read-only nature, auth needs, or side effects. However, the read-only intent is obvious from the action, so a mid-range score is appropriate.

Agents need to know what a tool does to the 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 concise sentences, front-loading the purpose and then detailing returns and cost. No extraneous 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?

Despite no annotations, the description fully explains the tool's output and context (pricing pipeline). With an output schema present, the return value explanation is sufficient for a simple listing tool with no parameters.

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

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

The input schema has zero parameters, so description does not need to add parameter details. Schema coverage is 100% vacuously. The baseline for no parameters is 4, and the description adds no redundant info.

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

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

The description clearly states the tool lists all constraint types and their parameter schemas, specifying the return fields (type, category, description, parameter specs). It is distinct from siblings which are general CRUD or status operations.

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

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

The description provides clear context (used in pricing pipeline) and notes it is free. Although it doesn't explicitly state when not to use or alternatives, the tool is self-contained and no similar sibling exists, making usage straightforward.

Agents often have multiple tools that could apply. Explicit usage 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 partially covers behavioral traits: it lists order (newest first), mentions the 'times_redeemed' counter, and states restriction. It does not disclose potential errors or side effects like what happens without proper proof.

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

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

The description is very concise with three clear sentences: purpose, data detail, and restriction. Every sentence adds value and 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?

The tool has low complexity (one parameter, output schema exists), but the description omits the parameter meaning entirely. It provides some context about the output data but is incomplete for a safe and correct usage.

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

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

The description does not mention the single parameter 'dpop_token', and the schema has 0% description coverage. The agent receives no guidance on the purpose or format of this parameter, severely hindering correct invocation.

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

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

The description clearly states 'List every coupon this operator has minted (newest first)', specifying the verb and resource. It distinguishes from siblings by specifying 'operator' context, but does not explicitly differentiate from 'authority_list_my_coupons'.

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

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

The description notes the tool is 'RESTRICTED to operator — requires proof', indicating when it should be used. However, it does not provide guidance on when not to use it or suggest alternatives like 'authority_list_my_coupons'.

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

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

Discloses that it returns both active and exhausted redemptions with a status field listing possible values, and that authentication is required. No annotations exist, so description carries the burden well.

Agents need to know what a tool does to the 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, no filler, front-loaded purpose, and efficient use of words.

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

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

Covers purpose and return values but lacks input parameter explanations and does not mention pagination or limits. With output schema present, return structure is covered, but input details are 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 0%, and the description does not explain the parameters (npub, dpop_token) beyond implying npub is needed for proof. No semantic help is given.

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

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

The description clearly states the verb 'List' and the resource 'coupons this patron has redeemed on this operator', distinguishing it from sibling 'authority_list_coupons' which lists all coupons.

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

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

Mentions 'Free — requires proof of npub' which provides usage prerequisites, but does not explicitly contrast with alternatives or state when not to use it.

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

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

With no annotations, the description must fully disclose behavioral traits. It only says 'recent records' without defining recency, ordering, or pagination. The read-only nature is implied but not explicit, and no side effects or limitations are mentioned.

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

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

The description is a single concise sentence. For a simple list tool with well-documented parameters, this is efficient and front-loaded. Could slightly expand on context, but overall good.

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

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

Despite having an output schema, the description lacks context about what 'notarization records' entail, default behavior (e.g., limit defaults to 20), and how results are ordered. Given the complexity of the domain and many sibling tools, more completeness is needed.

Complex tools with many parameters or behaviors need more documentation. 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%; both parameters have descriptions in the schema (limit, status). The tool description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description 'List recent Bitcoin notarization records' clearly states the action (list) and the resource (Bitcoin notarization records). It distinguishes from siblings like authority_get_notarization_proof (single proof) and authority_notarize_ledger (creation).

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or comparisons to related tools such as authority_get_notarization_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?

No annotations provided, and description only mentions creation without disclosing side effects, authorization needs, or uniqueness constraints. It under-delivers on transparency for a write operation.

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

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

Single sentence, efficiently conveys core purpose with no redundancy.

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

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

Despite having 7 parameters and an output schema, the description provides no high-level summary of key fields or overall behavior, leaving gaps for effective use.

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

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

Schema description coverage is 86%, so baseline applies; description adds no additional parameter meaning, making it adequate but not enhanced.

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

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

Description clearly states verb 'Create' and resource 'new operator-owned discount coupon', distinguishing it from sibling tools like list, delete, update, and redeem.

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

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

No explicit guidance on when to use vs alternatives; the purpose is clear but lacks contextual instructions (e.g., that updates should use authority_update_coupon).

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

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

With no annotations, the description carries the full burden. It discloses that the tool builds a Merkle tree (a read-heavy operation) and submits to Bitcoin, with a 1-6 hour confirmation. It also states it's free and operator-only. However, it does not detail potential side effects or error conditions, but overall provides adequate behavioral context.

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

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

The description is three short sentences, each providing essential information: action, operator/background nature, and time/cost. No superfluous content; 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?

Given the zero-parameter input and existence of an output schema, the description adequately covers the tool's context. It explains the long-running nature and cost, though it could mention how to retrieve the result (e.g., via sibling tools). Still, it is mostly complete for a straightforward trigger action.

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

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

There are no parameters, and schema coverage is 100%. Per guidelines, a baseline of 4 applies. The description does not need to add parameter details since none exist, and it correctly omits unnecessary elaboration.

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

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

The description clearly states the tool's action: 'Build a Merkle tree of all patron balances and submit the root to Bitcoin via OpenTimestamps.' It is distinct from sibling tools like 'authority_get_notarization_proof' by specifying it is a background task, leaving no ambiguity about its 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 explicitly says 'Operator-only background task,' indicating the intended user role. It also mentions the Bitcoin confirmation delay (1-6 hours), setting expectations for usage. While it doesn't state when not to use it or provide explicit alternatives, the context is sufficient for an agent to infer appropriate use cases.

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

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

With no annotations, the description discloses important behavioral traits: requires Schnorr proof for external npub, skips proof for self-inspection. This goes beyond a simple 'view' and provides context on security and privilege.

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

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

The description is concise, front-loading the purpose in the first sentence, and then providing necessary behavioral details in two additional sentences. No redundant or vague phrasing.

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

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

Given the existence of an output schema (which likely covers return values), the description adequately covers purpose, parameter behavior, and security context. It is complete for a view tool with no destructive actions.

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

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

Schema description coverage is 50% (npub has a description, dpop_token does not). The description adds meaning for npub by explaining the proof requirement and fallback, but does not address dpop_token, leaving its purpose unclear.

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

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

The description clearly states the tool views registration status, balance summary, and the Authority's Nostr npub. It uses a specific verb ('View') and identifies resources, but does not explicitly differentiate from sibling tools, though the purpose is unique enough.

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

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

The description explains when to use the tool (viewing status with or without npub) and the proof requirement, but does not mention when not to use it or compare to alternatives among the many sibling tools.

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

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

No annotations are present, so the description carries full burden. It does not disclose whether the tool is read-only, requires authentication, or any side effects. The 'Free.' hint is insufficient.

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

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

The description is very short with two elements: purpose and 'Free.' It is efficient but the 'Free.' is ambiguous. Still, no redundant 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?

Despite having an output schema, the description does not explain the return format or what 'describing the ecosystem' entails. It lacks details needed for an agent to interpret the output.

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

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

The tool has no parameters, and schema coverage is 100%, so the description does not need to add parameter details. However, it adds no value beyond the schema, earning a baseline score.

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

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

The description clearly states the tool describes the DPYC ecosystem via the Oracle, using a specific verb and resource. It distinguishes itself from sibling tools that perform specific actions like checking, listing, or updating.

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

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

No guidance is provided on when to use this tool versus alternatives. The description lacks context about prerequisites or exclusions, offering only the purpose and a cryptic 'Free.'

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

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

No annotations are provided, so the description carries full responsibility. It only mentions 'Free' but does not disclose idempotency, authentication needs, rate limits, or whether it is a read operation.

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

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

The description is very short (two words of purpose plus 'Free.'). It is concise and front-loaded, though it could be slightly more informative without losing brevity.

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

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

Given zero parameters and the presence of an output schema, the tool is likely self-contained. The description is adequate for a simple query tool, though it could mention that no input is required.

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

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

There are zero parameters, so baseline is 4. The description does not need to add parameter info since the schema is empty and coverage is 100%.

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

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

The description states 'Get the current DPYC certification tax rate' which is a specific verb and resource. It clearly distinguishes from sibling tools like authority_oracle_about or authority_oracle_lookup_member.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as other oracle tools. No context or exclusions are given.

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

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

Only states 'Free' as behavioral hint. With no annotations, the description should disclose authentication, rate limits, or what actions it performs. It omits any details about side effects or required permissions.

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

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

Extremely concise at 7 words, no wasted text. Could be improved by adding more structure or context while maintaining brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 parameterless tool with an output schema, the description is minimally adequate. It gives the primary purpose but lacks details on expected input (none) or how output is structured, which may be covered by the schema.

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

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

No parameters exist, so baseline score of 3 applies. The description adds no parameter information, but schema coverage is 100% vacuously.

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

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

The description clearly states the tool retrieves DPYC onboarding instructions from the Oracle, using specific verb and resource. It distinguishes from siblings like 'authority_get_patron_onboarding_status' which is about status, not instructions. However, 'DPYC' may require domain knowledge.

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

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

No guidance on when to use this tool versus alternatives. The description lacks context about prerequisites or scenarios, and does not mention exclusions or complementary 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. The description mentions 'Free.' which implies no cost, but does not disclose any other behavioral traits such as whether it requires authentication, rate limits, or if it's read-only. The lack of annotations places full burden on the description, which is insufficient.

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

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

Extremely brief and front-loaded, with no wasted words. However, the inclusion of 'Free.' is arguably not essential for a tool description, slightly reducing focus.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 lookup tool with an output schema, the description is minimal. It does not explain what information the lookup returns or any side effects, leaving the agent reliant on the output schema without behavioral context.

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

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

Only one parameter (npub) with zero schema description coverage. The description explicitly states 'by npub', adding meaning beyond the schema's simple type definition. This adequately explains the parameter'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 verb 'Look up' clearly indicates a read operation, and the resource is a 'DPYC community member' by 'npub'. While it doesn't explicitly differentiate from siblings like authority_get_nostr_profile, the 'oracle' prefix and 'Free.' hint at its unique role.

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

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

No guidance on when to use this tool versus others, no prerequisites, exclusions, or context provided. The description is purely functional.

Agents often have multiple tools that could apply. Explicit usage 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 mentions the tool is 'Free' but lacks details on authentication, side effects, or rate limits. The verb 'Get' implies read-only, but not stated explicitly.

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

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

Extremely concise with two sentences, front-loaded with the core action. No unnecessary words.

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

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

While the tool is simple with no parameters and an output schema available, the description omits behavioral context like authentication requirements or typical use cases, leaving some 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?

Zero parameters, and schema coverage is 100%. Baseline score of 4 applies since there are no parameters to describe.

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

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

The description clearly states the verb 'Get' and specific resource 'active network advisories from the Oracle', distinguishing it from sibling tools like authority_oracle_about or authority_oracle_get_tax_rate.

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

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

No explicit guidance on when to use this tool versus alternatives. While the resource name implies context, the description does not provide usage scenarios or exclusions.

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

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

With no annotations, the description fully discloses behavioral traits: signature verification, relay to public relays, no private key handling, authorization via signature, and free usage. This exceeds expectations for transparency.

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

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

The description is concise with no filler. It uses clear language and structure: a brief purpose statement followed by a detailed but essential explanation of the process and security model. Every sentence adds value.

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

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

Given the presence of an output schema (not shown but indicated), the description covers all necessary aspects: purpose, usage flow, security, parameters, and cost. It is complete for the tool's moderate complexity.

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

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

Schema coverage is 100% with adequate descriptions, but the description adds context about the signed_event being a 'client-signed kind-0 event' and explains the signing flow, enhancing understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: publish a client-signed kind-0 profile to relays for an npub. It uses specific verbs and resources, and distinguishes itself from sibling tools like authority_get_nostr_profile by being the publishing counterpart.

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

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

The description explains when to use this tool: when a frontend has a client-signed kind-0 event and expects it to be relayed. It implies security considerations (no key custody) and that it's the intended path for profile publishing on this system. No explicit alternatives or exclusions, but sibling names suggest no direct substitutes.

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

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

No annotations exist, so the description carries the full burden. It discloses the flow: creates invoice, requires payment, and needs npub proof. It mentions it's free. However, it does not cover error cases, timeouts, or what happens if payment fails.

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

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

The description is concise (5 sentences), front-loaded with the main action, and each sentence adds value without redundancy. It clearly outlines the process and requirements.

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

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

The description covers the main purchase flow adequately. Since an output schema exists, it does not need to explain return values. However, it lacks details on error handling, invoice expiry, or how to obtain the dpop_token.

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

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

Schema coverage is 100%, so baseline is 3. The description adds little beyond the schema: it references npub and dpop_token indirectly but does not provide additional meaning or examples for parameters.

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

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

The description clearly states the tool's function: 'Buy credits via Bitcoin Lightning.' It specifies the verb 'Buy' and the resource 'credits,' and distinguishes itself from siblings like authority_check_price or authority_redeem_coupon by focusing on the purchase flow.

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

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

The description provides context: proof of npub ownership required, free to call, and follow-up with check_payment. However, it does not explicitly state when to use this tool versus alternatives, such as when to redeem a coupon or check price.

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

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

With no annotations, the description fully discloses behavior: inline Schnorr verification, durable pending row creation, best-effort DM, and the explicit note that provisioning is deferred. No contradictions.

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

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

Two sentences, each serving a distinct purpose: first states the core action, second details verification, side effects, and limitation. No wasted words.

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

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

Given the presence of an output schema and thorough parameter descriptions, the description covers all necessary context: inbound nature, MCP-to-MCP invocation, verification mechanism, side effects, and what it does not do. Distinguishes from sibling 'approve_adoption'.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add new parameter meaning beyond the schema's param descriptions, but it provides context on how parameters are used in the verification process.

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

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

The description clearly states the tool's purpose: to record an operator's request to be adopted by this Authority. It distinguishes itself from siblings like 'authority_request_adoption' (outbound) and 'authority_approve_adoption' (post-request) by specifying it is an inbound MCP-to-MCP call.

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

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

The description explicitly notes that this tool is called MCP-to-MCP by the operator's 'request_adoption', implying it is not meant for direct agent invocation. It also clarifies what it does not do (provisioning waits for 'approve_adoption'), but does not explicitly discourage direct use.

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

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

No annotations provided, so description fully bears the burden. It details deterministic one-shot retrieval, relay draining, deletion of wrong DMs, NACK behavior, stop-on-match, courier_not_found on no match, and credential_card bypass. Thorough 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?

Multiple paragraphs but well-structured: main purpose first, then detailed behavior, then alternative path. No fluff; every sentence adds necessary information. Slightly dense but appropriate for complexity.

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

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

Given 4 params, no required params, and presence of output schema, the description covers all essential aspects: when to call, mechanics, alternative path, error result, and post-success reinitialization. Highly complete.

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

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

Schema coverage is 100% and schema descriptions are sufficient. The description adds behavioral context for each parameter: service must match the channel, dpop_token is the session phrase, credential_card bypasses relay and dpop_token. Adds value beyond schema.

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

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

Description clearly states the tool picks up credentials from Secure Courier and completes the CREDENTIAL-DELIVERY flow, distinguishing it from the sibling `receive_npub_proof` (ownership-proof counterpart). Verb and resource are specific.

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

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

Explicitly states 'Call this only after the user confirms they have replied' and 'Do NOT poll, loop, or retry.' Provides clear context for when to use and the alternative credential_card path that bypasses the relay.

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

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

With no annotations, the description fully discloses behavior: it is deterministic and one-shot, drains only the pinned relay, deletes mismatched DMs without revealing the expected phrase, and stores a hash of the token. The token handling and storage process are clearly explained.

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

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

The description is somewhat long but well-structured with clear paragraphs. It front-loads the purpose and then details important constraints and behaviors. Every sentence adds value, though minor trimming could improve 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?

The description provides complete context for a complex tool, including the flow, prerequisites, return value, token storage, and the need for the calling application to remember the dpop_token. Even without the output schema, the description is self-sufficient.

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

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

The input schema already has 100% coverage with clear descriptions for both parameters. The description adds some context (e.g., 'the same token' for dpop_token) but does not significantly augment the parameter meaning beyond what the schema provides.

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

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

The description clearly states the tool's purpose: receiving npub ownership confirmation from a patron and completing the npub-OWNERSHIP-PROOF flow. It distinguishes itself from the sibling tool 'receive_credentials' by naming it as the counterpart for credential delivery.

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

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

Explicit usage guidance is provided: 'Call this only after the user confirms they have replied' and 'Do NOT poll, loop, or retry.' It also clarifies that if called before the user replies, the message will never be found, and specifies the one-shot nature.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool is free, requires proof of npub, is idempotent, validates window and total cap, and records per-patron redemption. It does not discuss rate limiting or specific error scenarios.

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

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

The description is organized into three short paragraphs covering main action, post-redemption behavior, and free/idempotent traits. It is front-loaded with the core purpose and avoids unnecessary repetition.

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

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

The tool is moderately complex (3 params, output schema exists). The description covers key aspects: validation, recording, idempotency, and discount application. It does not detail output structure or error conditions, but output schema may cover that.

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

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

The description adds meaning to parameters: 'code' is explained as 'the code the operator shared', and 'npub' is mentioned as requiring proof. The optional dpop_token is not explained, but its default value suggests limited impact. Given 0% schema coverage, the description compensates well.

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

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

The description clearly states the tool's purpose: 'Claim a coupon by its name (the code the operator shared).' It specifies the verb ('redeem') and resource ('coupon'), and distinguishes it from siblings by focusing on redemption rather than minting, deletion, or listing.

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

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

The description provides context about when to use the tool: 'Subsequent paid tool calls on this MCP auto-apply the discount until uses_per_patron is exhausted.' It also mentions idempotency and free usage, but does not explicitly contrast with alternative tools like authority_mint_coupon or authority_list_coupons.

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

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

With no annotations provided, the description must fully disclose behavioral traits. It states the tool 'sends a Nostr DM challenge', indicating a write operation, but does not mention side effects, authentication requirements, rate limits, idempotency, or what happens upon failure. For a step in a multi-step process, this level of disclosure is insufficient to guide an agent's safe and correct invocation.

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

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

The description is a single sentence of 13 words, front-loaded with the critical 'Step 1/3 of Authority onboarding' context. Every word is essential, with no redundancy or filler. It is maximally concise while conveying the core action and sequential role.

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

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

Given the tool is part of a multi-step onboarding process and has an output schema, the description covers the immediate action but lacks context on preconditions, expected outcome beyond sending the DM, and how it connects to subsequent steps. The output schema may partially compensate, but the description alone is not fully complete for an agent to understand the entire interaction.

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

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

The input schema already provides a description for the only parameter (candidate_npub: 'The Nostr npub of the candidate who wants to become the curator'), achieving 100% schema coverage. The tool description does not add meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states what the tool does: 'send a Nostr DM challenge to the candidate' as part of a multi-step onboarding process. It uses specific verb 'send' and resource 'Nostr DM challenge', and the phrase 'Step 1/3' distinguishes it from sibling tools that handle later steps or other aspects of authority management.

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

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

The description explicitly frames the tool as 'Step 1/3 of Authority onboarding', providing clear sequential context. This implies it should be used before other onboarding steps, though it does not explicitly mention when not to use it or list alternative tools. The step designation gives sufficient guidance for an agent to understand its place in the flow.

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

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

No annotations are provided, so the description carries full burden. It discloses idempotency ('safe to call again') and explains the two required proofs. However, it does not describe any side effects, revertibility, or error behaviors, leaving gaps in behavioral understanding 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 description is well-structured with a summary paragraph, bullet points, and a clear next-step sentence. It is detailed but not overly long. The key information is front-loaded, though the detailed proof explanation could be slightly condensed.

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

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

Given the complexity (4 parameters, no annotations, but an output schema exists), the description covers the registration process, prerequisites, and next steps adequately. It does not explain the output format, but the output schema is available separately. The tool has many siblings, but the description provides enough context for a knowledgeable agent.

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

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

Schema coverage is 75% (only dpop_token lacks description). The description compensates by thoroughly explaining the purpose of both proof parameters (proof and authority_proof) and their creation process, adding significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Provision an operator in the Authority ledger' and explains the downstream use (purchase credits, certify purchase orders). It provides specific details about the process, but does not explicitly differentiate from sibling tools like authority_approve_adoption or authority_check_authority_approval, which could cause confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 context on when to use this tool (after obtaining proofs) and provides the next step ('Call purchase_credits'). It explains the required proofs and their sources, but does not explicitly state when not to use this tool or mention alternatives among the many sibling tools.

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

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

With no annotations, the description carries the full burden. It states the tool rejects a pending request and mentions 'owner consent', but does not disclose side effects, reversibility, or permission requirements. Basic purpose is clear but depth is lacking.

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

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

Single sentence, front-loaded with the key action, no extraneous words. Highly concise.

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

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

For a simple rejection tool with no annotations and an output schema, the description is minimally complete but lacks usage context and behavioral details. With many sibling tools, more guidance would improve completeness.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds only minor context about authority_proof ('owner consent'), not significantly 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?

The description clearly states the action 'Reject a pending operator-adoption request (owner consent)', using a specific verb and resource. It distinguishes from sibling tools like authority_approve_adoption.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as authority_approve_adoption or authority_list_adoption_requests. It mentions 'owner consent' but does not clarify prerequisites or contexts.

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

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

With no annotations, the description carries full burden. It states the tool is idempotent, does not rotate passwords or send bootstrap DMs, and only fixes ownership and grants. It explains the behavioral consequence (enables CREATE INDEX). No contradictions.

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

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

The description is very concise: two sentences plus a brief clarification and 'Idempotent.' It is front-loaded with the main action and contains no unnecessary words.

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

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

An output schema exists, so return values need not be explained. The description covers the repair scenario and distinguishes from an alternative tool. No major gaps given the tool's complexity.

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

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

Schema coverage is 100%, so the schema already describes both parameters adequately. The description adds minimal extra meaning beyond the schema's own parameter descriptions, so baseline score of 3 applies.

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

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

The description clearly states the tool's purpose: reassign ownership of tables in an operator's tenant schema to the operator's role and re-grant DML. It specifies the resource (operator's tenant schema) and action, and distinguishes from the sibling tool 'register_operator' by explicitly listing what it does not do.

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

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

The description provides context on when to use the tool: for tenants where tables are owned by the provisioning role, causing bootstrap failures due to inability to CREATE INDEX. It explicitly differentiates from register_operator, indicating when not to use it. However, it does not list prerequisites or error conditions.

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

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

With no annotations, the description fully discloses behavior: it resolves the Authority's MCP endpoint, mints an ownership proof, delivers the request MCP-to-MCP, and explains that the Authority records it as pending and the operator flips to ready upon provisioning. No contradictions.

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

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

The description is a concise paragraph with no wasted words. It is front-loaded with the main action. Slight improvement could be structuring into bullet points, but it is still effective.

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

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

Given the complexity, the description covers the full workflow, including prerequisites (proof of npub), the process (MCP-to-MCP delivery), and post-condition (pending status, polling adoption_status). An output schema exists, so return values are not needed. The description is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minor context (e.g., 'optional message' for note, 'ownership proof' for dpop_token, 'MCP endpoint' for service_url) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Ask a chosen Authority to adopt this operator (deferred courtship).' It uses a specific verb ('ask') and resource ('Authority'), and distinguishes from siblings like authority_approve_adoption and authority_get_adoption_status.

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

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

The description specifies that the tool is 'RESTRICTED to the operator — requires proof the caller controls this operator's npub.' It also suggests polling adoption_status for progress, providing clear context. However, it does not explicitly state when not to use it or mention alternatives.

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

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

No annotations are provided, so the description carries the full burden for behavioral disclosure. It transparently explains that this is a human-in-the-loop flow (requires user reply in Nostr client), that it sends a welcome DM, and that `receive_credentials` destructively drains the mailbox. It also warns against polling. While it covers the key behavioral traits, it does not mention idempotency, rate limits, or authorization requirements, which would elevate it to 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?

The description is efficient with no wasted sentences. It is well-structured: a one-line summary, followed by a paragraph explaining the credential flow and alternatives, then bullet-like instructions for the agent. Every sentence adds value, and the use of emphasis (bold, backticks) enhances readability without verbosity.

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

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

Given that an output schema exists (as indicated by context signals), the description does not need to explain return values. It covers the tool's action, usage, behavioral nuances, and procedural steps. However, it omits prerequisites such as authentication status or role requirements, which are relevant for a tool opening a secure channel. Sibling tools like `authority_session_status` might be needed first, but this is not mentioned.

Complex tools with many parameters or behaviors need more documentation. 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% (both parameters are described in the schema). The tool description does not add new semantic meaning beyond what the schema already provides for `service` and `sender_npub`. It mentions them in context but does not elaborate on their format, constraints, or examples. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Open a Secure Courier channel for credential delivery.' It specifies the resource (credential delivery) and action, and explicitly distinguishes it from the sibling tool `request_npub_proof`, which is for proving npub control. This meets the criteria for a specific verb+resource with sibling differentiation.

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

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

The description provides explicit guidance on when to use this tool (for credential delivery) and when not (for npub proof use `request_npub_proof`; for dynamic/OAuth2 services, check `service_status` first). It also includes procedural instructions: after calling, stop and tell the user, wait for confirmation, do not poll. This constitutes clear usage context with exclusions and alternatives.

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

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

No annotations provided, so description carries full burden. Discloses human-in-the-loop, challenge DM nature, returns dpop_token, destructive drain on relay, and lifecycle/caching behavior. Completely transparent.

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

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

Well-structured with sections (bolded terms) and bullet points. Every sentence provides distinct information. Slightly verbose but not wasteful; could trim a few words without losing clarity.

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

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

Given complexity (human-in-the-loop, dpop_token lifecycle, sibling differentiation), description is complete. Covers when to call, what it does, what it returns, how to proceed, and lifecycle details. Output schema exists but description explains semantics of dpop_token.

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

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

Only one parameter (patron_npub) with 100% schema coverage, so baseline 3. Description adds value by clarifying it is required despite empty default, and implies format (npub). Minor extra context.

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

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

Description uses specific verb ('request npub ownership proof') and resource ('from a patron via Nostr DM'). It clearly distinguishes from sibling tool 'request_credential_channel' by stating this proves npub control, not delivering secrets. All within first two sentences.

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

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

Explicitly states when to use: 'when a call returns proof_required'. Provides lifecycle instructions: call this, wait for user, then call receive_npub_proof. Warns against polling/retrying and explains destructive behavior.

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

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

No annotations exist, so the description carries full burden. It discloses destructive behavior (erase all models), initialization with tools at 0 sats, and operator restriction. It does not detail side effects like session disruption but is generally transparent.

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

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

The description is fairly concise, with a strong first sentence summarizing the action. It uses two short paragraphs without fluff, though it could be slightly more structured.

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

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

Given the tool's destructive nature and operator restriction, the description covers key aspects: erasing, initializing, and returning the new model. It lacks detail on the dpop_token parameter but has output schema, so returns are covered. Overall adequate for agent use.

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

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

The input schema has one parameter (dpop_token) with no description in schema (0% coverage). The description does not explain this parameter at all, leaving the agent to guess its purpose. This fails to add meaning beyond the schema.

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

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

The description clearly states the tool erases all pricing models and restores a viable default, with precise actions (delete, initialize). It distinguishes itself from siblings like authority_set_pricing_model and authority_get_pricing_model by specifying a destructive reset.

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

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

The description mentions it is restricted to operator with proof required, providing a clear usage context. However, it does not explicitly state when to use this tool versus alternatives (e.g., set_pricing_model) or give when-not-to-use guidance.

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

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

No annotations exist, so the description carries full burden. It discloses that the tool is restricted to the operator, idempotent (returns success with 0 credits if already credited), and used for manual credit grants. While it doesn't detail side effects or rate limits, the idempotency and operator restriction provide good behavioral context.

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

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

The description is well-structured with a concise opening sentence, bolded restriction, bullet-like use cases, and a clear idempotency note. Every sentence adds value with no redundancy.

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

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

Given that an output schema exists, the description doesn't need to detail return values. It covers purpose, use cases, idempotency, and authorization. However, it lacks explanation for edge cases like invalid invoice or mismatched patrons, but overall is adequate for the tool's simplicity.

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

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

Schema coverage is 100%, so baseline is 3. The description reiterates the restriction on dpop_token (must be operator-signed) and the purpose of invoice_id and patron_npub, but does not add new semantic meaning beyond the schema.

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

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

The description clearly states the tool's action ('Credit a patron's ledger from a BTCPay-settled invoice.') with a specific verb and resource. It distinguishes itself from siblings by emphasizing it is a manual credit grant restricted to operators, not a purchase or other operation.

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

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

Explicitly states when to use the tool via enumerated use cases (e.g., cold-start vault races, ncred delivery hiccups) and who should invoke it (operator only). It also provides a when-not scenario by noting that patrons must escalate to operator, guiding proper usage.

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