optionality-mcp

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

With no annotations, the description carries full burden. It discloses that no credits are consumed, that npub proof is required to prevent scraping, and it specifies the return contents. It does not explicitly state read-only behavior, but the description implies it. Rate limits or other behaviors are not mentioned, but overall it adds sufficient 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 (4 sentences) and front-loads the main purpose. It avoids unnecessary details. Could be slightly tighter, but overall 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 has 3 parameters, no annotations, and an output schema exists, the description provides good context about purpose, return data, cost, and authentication requirement. It does not cover error cases or rate limits, but the output schema likely covers return format. Overall, it is sufficiently complete for an agent to understand how to use it.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds context for dpop_token: 'Proof of npub ownership is required to prevent statement-scraping of arbitrary patrons.' This provides additional meaning beyond the schema's technical description. No significant added value for 'days' or 'npub'. Baseline of 3 is appropriate.

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

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

The description clearly states the tool generates a patron's account statement and specifies exactly what data is returned (purchase history, credit tranches, usage breakdown, daily logs). It distinguishes from the sibling tool 'optionality_account_statement_infographic' by clarifying this is the raw statement, not an infographic, and also clarifies it is the patron's spending account, not the operator's tax balance.

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

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

The description provides clear context: it's free, requires proof of npub ownership, and is for generating a statement. However, it does not explicitly compare to sibling tools or state when to use this versus alternatives, such as why one might choose this over 'optionality_check_balance' or 'optionality_get_journal'.

Agents often have multiple tools that could apply. Explicit usage 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 cost (1 api_sat per call) and proof verification process, which are key behavioral traits not covered by annotations (none provided). Does not detail rate limits or other safety aspects.

Agents need to know what a tool does to the 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 sentences efficiently convey purpose, output format, cost, and verification. No redundant or irrelevant 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?

Covers main functionality, output components, cost, and verification. With output schema present, description adequately explains what the SVG contains.

Complex tools with many parameters or behaviors need more documentation. 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 parameters are already well-documented. Description adds no extra parameter meaning beyond what 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?

Clearly states it generates an SVG infographic of account statement, distinguishes from sibling account_statement by mentioning it returns same data as that tool but rendered visually.

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

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

Implicitly suggests use for visual representation compared to account_statement for raw data, but lacks explicit when-to-use/when-not-to-use guidance or alternative references.

Agents often have multiple tools that could apply. Explicit usage 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 operation is 'Free' and that it 'Polls the Authority MCP-to-MCP', giving insight into cost and communication method. It also enumerates possible statuses. This is good behavioral context, though rate limits or authentication requirements are not 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 extremely concise at two short sentences, with no redundant words. Every sentence adds value: first gives the core purpose, second adds cost and polling detail. No fluff.

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

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

Given the tool is a simple status check with 2 parameters and an output schema, the description covers core purpose, cost, method (polling), and possible return values. However, it lacks explicit explanation of parameter formats or any edge cases. The output schema likely covers return structure, so overall it is sufficiently complete but with a minor gap in parameter 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 description coverage is 0%, so the description must compensate. It only implicitly references 'chosen Authority' for the required 'authority_npub' parameter but does not explain its format (e.g., npub string). The optional 'dpop_token' is completely undocumented in the description. 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 uses the verbs 'Check' and 'Polls' to clearly state the action (checking status) and identifies the resource as 'this operator's adoption-request status at a chosen Authority'. It distinguishes itself from sibling tools like 'optionality_request_adoption' or 'optionality_get_operator_onboarding_status' by focusing specifically on adoption-request status checking.

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

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

The description clearly states when to use the tool: to check the status of an adoption request at a chosen Authority. It implies a read-only polling operation but does not explicitly list alternatives or conditions to avoid. The context is clear, but exclusion guidance is missing, making it a 4.

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

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

The description discloses the claim-check model, polling requirement via separate tool, and degenerate-case behavior. With no annotations, this is strong but lacks details on billing or rate limits.

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

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

Three concise sentences: purpose, parameter use, and return behavior. Front-loaded with the main action. 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?

Adequately covers the two-step process, degenerate case, and history usage. Lacks full parameter explanations for entry_id and dpop_token, but overall sufficient given the output schema exists.

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

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

Schema coverage is 20%; the description adds meaning for history (JSON-encoded array) and question (degenerate handling) but does not explain entry_id or dpop_token. Partially compensates for schema gaps.

Input schemas describe structure but not intent. Descriptions should explain 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 returns a non-spoiler Socratic hint for an open journal entry, specifying verb and resource. It distinguishes from sibling optionality_fetch_tip by explaining the two-step claim-check pattern.

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

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

Guidance on using history for follow-up context and notes on degenerate questions (empty/oversized) provide clear when-to-use advice. However, no explicit exclusions or comparisons to other siblings.

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

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

With no annotations, the description carries full burden. It discloses that the tool returns sats available, implies no side effects (read-only), and explains the consequence of zero balance. It lacks mention of authentication or rate limits but is sufficient for a simple balance check.

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

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

The description is concise with five sentences each adding unique value: purpose, return value, consequences of zero balance, and clarification of ownership. 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 no parameters and an output schema (though not detailed), the description adequately covers what the tool does, its return, and its operational context. It is complete for a 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?

The tool has no parameters, so schema coverage is 100%. The description adds value by explaining what the tool returns and its significance, beyond just stating it checks balance.

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

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

The description clearly states the tool checks the operator's tax balance at the Authority, specifying it is for the operator's own funding and not a patron balance. It distinguishes itself from sibling tools like optionality_check_balance by clarifying the context of authority balance.

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

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

The description explains when to use the tool (to check sats available for certifying patron credit purchases) and what happens when balance reaches zero (operator must call purchase_credits). It provides actionable context but does not explicitly mention when not to use it, which is acceptable given its specific role.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool is free (no credits consumed) and requires a cryptographic proof of npub ownership to prevent enumeration. This adds significant behavioral context beyond 'check balance', though it could mention potential failure modes.

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

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

The description is concise with three short paragraphs. The first sentence immediately states the tool's purpose. Every sentence adds value: clarifying the type of balance, directing to an alternative tool, and noting the free nature and security requirement. No fluff.

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

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

With two parameters, full schema coverage, and an output schema present, the description rounds out the picture by adding usage context, cost implications, and authentication requirements. It is sufficient for an agent to decide when and how to invoke this tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The input schema already contains detailed descriptions for both npub and dpop_token. The overall description adds context that this is a patron's spending balance, but does not significantly enhance parameter 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 verb 'check' and the resource 'patron's credit balance at this operator'. It distinguishes itself from the sibling tool 'authority_check_balance' by specifying that this tool is for the patron's balance, not the operator's. This avoids 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 provides explicit when-to-use: checking a patron's spending balance. It also explicitly states when not to use: for the operator's own balance, instead use authority_check_balance. Additionally, it mentions that the tool is free and requires proof of npub ownership, setting clear prerequisites.

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

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

No annotations exist, so description carries full burden. Discloses that it is free and requires proof of npub to prevent front-running, adding behavioral context beyond schema. However, does not describe typical outcomes or error states, leaving some gaps.

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

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

Three sentences with no redundancy. Front-loaded with purpose. Every sentence adds value: purpose, usage order, free and security note.

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

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

Describes when to call, cost, and security requirement. Output schema exists (reducing need to explain returns). Could mention error cases (e.g., what if not yet paid) but overall sufficient for a simple 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 description coverage is 100%, so baseline is 3. Description adds little beyond schema: it mentions invoice_id comes from purchase_credits, but that is already in schema. No additional semantics for npub or dpop_token.

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

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

Description clearly states the tool checks the payment status of a Lightning invoice, with a specific verb and resource. It distinguishes from siblings like check_balance by specifying the object (invoice) and context (after paying).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ordering ('Call after paying the invoice from purchase_credits') and notes the tool is free and requires proof of npub ownership. Lacks explicit when-not-to-use or alternatives, but the context is clear.

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

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

The description discloses that the tool is free ('no credits required'), which is a key behavioral trait. However, it does not explicitly state that the operation is read-only, nor does it mention authentication requirements, side effects, or any constraints beyond cost. With no annotations to fall back on, this leaves gaps.

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

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

Extremely concise: two sentences clearly stating purpose and output details. No wasted words, front-loaded with the main action.

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

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

Covers the tool's purpose and output (base cost, constraint effects). With an output schema present, return values are handled. However, it lacks prerequisites, parameter hints, and does not address the context of when the tool is applicable (e.g., valid tools). Adequate but with noticeable 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 description adds no information about any of the 4 parameters. Schema description coverage is only 50% (tool_id and tool_kwargs have descriptions), but the description does not compensate for the undocumented parameters (npub, dpop_token). The agent must rely solely on the schema, which is incomplete.

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

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

The description clearly states 'Preview the effective cost of a tool call' with a specific verb (Preview) and resource (cost of a tool call). It distinguishes from sibling tools by focusing on pricing, while siblings cover account statements, balances, profiles, etc.

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

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

No guidance is provided on when to use this tool versus alternatives. Siblings include other 'check' tools (e.g., optionality_check_balance, optionality_check_payment) with overlapping purposes, but the description does not differentiate them or offer usage conditions.

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

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

With no annotations provided, the description fully discloses behavior: 'Free, no side effects — does not evict the cache or touch relays.' This assures the agent it is safe and read-only, which is critical for a check 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 three sentences long, front-loads the purpose, and adds context and safety info without redundancy. Every sentence is valuable and concise.

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

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

Given the simplicity of the tool and the presence of an output schema, the description covers purpose, usage, side effects, and parameter dependencies adequately. No gaps remain for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% and each parameter has a clear description in the schema (dpop_token and patron_npub). The tool description does not add additional 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 the tool's purpose: 'Check whether a previously-cached dpop_token is still valid.' It uses a specific verb ('check') and resource ('dpop_token validity'), and distinguishes from sibling check tools (e.g., check_balance, check_price) by focusing on the npub-proof 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 for when to use: 'before burning credits on a guaranteed failure.' It mirrors check_oauth_status for the npub-proof flow. However, it does not explicitly exclude other scenarios or contrast with similar tools, leaving some room for ambiguity.

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

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

With no annotations, the description must disclose behavioral traits. It only says 'generate and open a journal entry', omitting details like mode-dependent web search costs, parameter effects, or data persistence. Does not explain what 'open a journal entry' entails.

Agents need to know what a tool does to the 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, which is concise but undersized for a 7-parameter tool. It lacks structure or front-loading of key information, though it has no wasted words.

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

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

Given the tool's complexity (7 params, output schema), the description is too vague. It does not explain what a 'scenario' is, how journal entries work, or the role of required parameters. Inadequate for an agent to fully understand the tool's 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 description coverage is high (86%), so baseline is 3. The description adds no meaning beyond the schema; it does not explain how parameters like mode, difficulty, or replay_entry_id affect behavior. No value added.

Input schemas describe structure but not intent. Descriptions should explain 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 resources 'options trading scenario' and 'journal entry', distinguishing it from siblings like optionality_fetch_scenario (fetch existing) and optionality_judge_trade (judge trade).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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, nor any prerequisites or exclusions. The description lacks context about required parameters or setup.

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

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

No annotations, so description carries burden. Discloses cascade to redemptions, no-op behavior for chain steps, and operator restriction. Lacks details on return format or errors.

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

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

Highly concise: two short paragraphs, front-loaded purpose, no filler words. Every sentence adds value.

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

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

Covers key behavioral aspects but omits parameter descriptions and return value details (despite output schema existing). Some gaps remain for a complete understanding.

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

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

Schema coverage is 0%; description does not explain 'coupon_id' or 'dpop_token' beyond implying 'proof'. Does not add meaning beyond parameter names.

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

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

Clearly states action 'Delete a coupon' and resource, contrasts with sibling tools (e.g., mint, update, redeem). Includes cascading behavior for additional specificity.

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

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

Explicitly states operator restriction and proof requirement. Implies when used (only deletion) but doesn't specify when not to use 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?

With no annotations provided, the description carries full burden. It discloses 'hard-delete' implying permanence and 'recompute leaderboard cache' as side effect, but lacks details on irreversibility, required permissions, or error states.

Agents need to know what a tool does to the 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 with no wasted words. However, it could be slightly restructured to include brief parameter hints without adding length, so not a perfect 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (3 params, output schema exists), the description gives a basic idea but lacks completeness on output behavior, error handling, or prerequisites like authentication. Minimal but acceptable for a straightforward delete 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?

Schema description coverage is 33% (only 1 of 3 parameters described in schema), and the description does not add any parameter semantics. Key parameters like npub and dpop_token are not explained, leaving ambiguity for the agent.

Input schemas describe structure but not intent. Descriptions should explain 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 'Hard-delete a journal entry and recompute the leaderboard cache' uses a specific verb 'Hard-delete' and resource 'journal entry', clearly distinguishing it from sibling tools like optionality_get_journal or optionality_list_journal. The additional detail about cache recomputation adds context.

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

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

No guidance on when to use this tool vs alternatives (e.g., is there a soft delete?). No mention of prerequisites or conditions for deletion. The description only states what it does, not usage context.

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

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

With no annotations provided, the description carries the full burden. It states this is a delete operation (mutation) and requires authentication via dpop_token, but does not disclose aspects like reversibility, idempotency, error behavior, or whether it returns confirmation. Some transparency is provided but it is incomplete.

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

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

The description is extremely concise: two sentences front-loading the core purpose, then adding key constraints. Every sentence earns its place with no fluff. This is efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (context signal), the description does not need to detail return values. It covers purpose, authentication requirement, and scope. However, it lacks information on behavior when the field does not exist or on potential errors, which would be helpful for a deletion tool. Still, it is fairly complete for a simple 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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds minimal parameter-specific value beyond stating the requirement for proof of ownership, which is already implied by the dpop_token description. The baseline score of 3 is appropriate.

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

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

The description explicitly states 'Remove a single patron credential field' and 'Deletes one field from stored credentials without affecting other fields.' This clearly identifies the action (delete), the resource (patron credential field), and the scope (single field). It distinguishes itself from sibling tools like 'optionality_update_patron_credential' and 'optionality_get_patron_credential_fields'.

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

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

The description mentions 'Proof of npub ownership is required' and that it is a write to a sensitive vault, but does not explicitly state when to use this tool versus alternatives (e.g., update or get). It lacks clear usage context or exclusion criteria, leaving the agent to infer from the action name.

Agents often have multiple tools that could apply. Explicit usage 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 the encryption method (AES-256-GCM), key derivation, operator's ability to sign on behalf of the user, and the critical constraint that the nsec must derive to the same npub. This is transparent about behavior and risks.

Agents need to know what a tool does to the 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 (4 sentences) and front-loaded with the core purpose. Each sentence adds value, and there is no redundant or extraneous information.

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

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

Given the complexity of the tool (cryptographic deposit, security implications) and the lack of annotations, the description provides a solid overview. It explains the trade-off, security, and constraints, but could mention the expected return value or confirmation behavior.

Complex tools with many parameters or behaviors need more documentation. 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 low (33%, only npub described). The description adds context for the nsec parameter (freshly-generated, must match npub), but does not explain npub beyond the schema's billing purpose or the dpop_token parameter. More parameter explanations are needed.

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

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

The description clearly states the tool's purpose in the first sentence: 'Deposit a freshly-generated nsec for operator-managed Nostr signing.' This provides a specific verb and resource, distinguishing it from other optionality tools like withdraw.

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

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

The description gives clear usage context: 'Use this only for fresh game-persona keypairs — never for an existing Nostr identity that lives elsewhere.' It explains the trade-off between sovereignty and UX, implicitly guiding when to use this tool versus alternatives like optionality_withdraw_nsec.

Agents often have multiple tools that could apply. Explicit usage 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 the tool is free, the polling mechanism, and the possible statuses including the 'expired' error condition. It does not mention authentication or side effects, but the tool appears to be a read-only fetch 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 extremely concise yet informative, consisting of three short sentences. It uses front-loaded structure: the first sentence states the primary function, and subsequent sentences add crucial behavioral details without unnecessary words.

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

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

Given that an output schema exists (context signal: has output schema=true), the description need not detail return values. It covers the key states and the result structure (entry_id + evaluation). For a polling/fetch tool, this is adequate, though the parameter descriptions could be enhanced.

Complex tools with many parameters or behaviors need more documentation. 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 low (33%): only npub has a description. The description does not explain dpop_token or provide more detail on claim_check beyond its role. The description mentions 'claim_check' in context but does not compensate for the missing schema descriptions of the other two 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 redeems a judge_trade claim check, and explains the lifecycle (running, done, expired). This distinguishes it from sibling tools like optionality_judge_trade (which likely creates the claim) and other fetch tools.

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

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

The description explains when to use the tool (after obtaining a claim_check from judge_trade), how to poll while status is 'running', and what to do when 'expired' (resubmit). It implies not to use it without a claim_check, but does not explicitly list alternatives or when not to use.

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

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

No annotations provided, so description carries full burden. It explains polling behavior, states (running, done, expired), and expected results. Missing details on error handling or side effects beyond 'Free' and auth via npub.

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

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

Three concise sentences, each adding value. Front-loaded with purpose, uses backticks for clarity. 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?

Adequately explains polling logic for a tool with output schema, but misses parameter details (npub, dpop_token) and does not elaborate on output schema structure beyond 'entry_id + scenario'. Could be more complete for a tool with optional 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?

Only claim_check is implied as the claim to fetch. npub and dpop_token are not explained in description despite schema coverage being low (33%). No details on parameter format or use beyond schema's brief npub description.

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

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

The description clearly starts with 'Redeem a deal_scenario claim check,' specifying the action and resource. It distinguishes from sibling 'optionality_deal_scenario' which presumably creates the claim, and explains the polling lifecycle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 instructions on when to call: while status is running, wait and retry; when done, result is ready; if expired, start new request. Lacks explicit exclusions or alternatives but provides sufficient context for typical 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?

With no annotations, the description covers core behavior: polling, status values, and result retrieval. It mentions the tool is 'Free' but omits details on authorization (beyond npub requirement) or potential rate limits. The description is solid but 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 concise (few sentences) and front-loaded with the core purpose. Every sentence adds necessary information without waste.

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

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

Given the tool's simplicity (polling a claim check) and the presence of an output schema, the description is complete. It explains the polling loop, statuses, and expected behavior, which suffices for 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?

Schema description coverage is only 33%, yet the tool description does not compensate for the lack of parameter details. It mentions 'claim_check' implicitly but provides no explanation for 'npub' or 'dpop_token'. The description adds minimal value beyond the schema.

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

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

Description clearly states 'Redeem an ask_tip claim check,' which is a verb+resource pair. It differentiates from the sibling tool 'optionality_ask_tip' by implying it retrieves a previously created tip. The polling explanation further clarifies the tool's role.

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

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

Explicit polling guidance is provided: 'While status is running, wait poll_after_seconds and call again.' It also explains conditions for done and expired, giving clear usage patterns. No misuse conditions are stated, but the context makes it obvious.

Agents often have multiple tools that could apply. Explicit usage 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's cosmetic (non-destructive), the coupon still exists, re-redeem is possible, and it requires proof of npub. This provides clear expectations for the agent.

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

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

Three sentences, all essential: purpose, key distinguishing feature, and prerequisite. Front-loaded with verb. 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?

For a simple removal tool with an output schema, the description covers the core behavior, side effects, and requirements. Return values are left to the output schema, which is acceptable.

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

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

Schema description coverage is 0%, so the description must explain parameters. It only mentions npub as required proof, but does not describe coupon_id or dpop_token. The coupon_id is implied but not explicitly explained.

Input schemas describe structure but not intent. Descriptions should explain 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 coupon from a patron's redemption list (specific verb+resource). It distinguishes from the sibling delete_coupon by noting it's 'cosmetic only', indicating it's not permanent deletion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the cosmetic nature and that the coupon can be re-redeemed, implying when to use this over permanent deletion. However, it does not explicitly name the sibling delete_coupon as the alternative for permanent removal.

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

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

With no annotations, the description carries full burden. It discloses destructive nature ('as destructive as a write') and proof-of-ownership requirement via dpop_token. Does not detail side effects but conveys key behavioral traits.

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

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

Two sentences, no wasted words. Information is front-loaded and every sentence serves a purpose.

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

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

Output schema exists, so return values need no explanation. Description covers purpose, key usage guidance, and behavioral trait (destructive). Could mention success/failure indicators but not essential given output schema.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context for npub (operator vs patron) beyond schema, but dpop_token is already well-documented. Minimal added semantic value.

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

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

The description clearly states the tool deletes vaulted credentials for a specific service and npub, using a strong verb 'delete' and specific resources. It distinguishes from siblings like optionality_delete_patron_credential by focusing on credentials in general.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 mentions the dpop_token requirement. Lacks explicit exclusion of alternatives but is clear enough 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?

With no annotations, the description carries the full burden. It adds context about the output fields, including the caveat that total_cost_usd is provider-reported and not comparable across models, and explains priced_runs and avg_cost_usd. However, it does not explicitly state that the operation is read-only, safe, or idempotent, nor does it mention any side effects or authorization needs beyond the npub hint in the schema.

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

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

The description is front-loaded with the purpose, then provides the output format in a code block, followed by a detailed yet relevant explanation of cost fields. It is longer than strictly necessary but each sentence adds useful information. Could be slightly more concise, but structure is 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?

Given the complexity of the return data (models, totals, cost nuances) and the absence of an output schema, the description compensates well by providing the full output structure and clarifying the meaning of each field. It also warns against misinterpreting cost comparisons. However, it lacks context on error handling, rate limits, or whether historical data is available. Still, it covers the most critical aspects for an AI agent to parse the response correctly.

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

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

Schema description coverage is 50% (dpop_token lacks description). The tool description itself does not mention any parameters or their meanings. The npub parameter is described in the schema as required for billing, but the description adds no extra value for parameters. This is a missed opportunity to explain dpop_token or clarify usage.

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

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

The description starts with a clear statement of what the tool does: 'Aggregated LLM usage and cost for this patron's calls.' This is specific, uses a verb+resource format, and distinguishes it from the many sibling tools that deal with balances, profiles, or coupons. No ambiguity.

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

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

The description provides no guidance on when to use this tool versus alternatives like optionality_get_leaderboard or optionality_check_balance. It does not mention scenarios, prerequisites, or exclusions. An AI agent must infer usage solely from the tool's name and summary.

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

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

Despite no annotations, the description discloses the return format ({"escrowed": bool}) and that it is free. It implies a read-only operation without side effects, which is adequate for a simple status check.

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

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

The description is extremely concise, with two clear sentences front-loading the purpose. Every word serves a purpose 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?

For a simple read tool with an output schema, the description covers purpose, return value, usage context, and cost. It is sufficiently complete.

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

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

Schema coverage is 50% (npub has description, dpop_token does not). The description does not add parameter details beyond what the schema provides, so it provides minimal added value.

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

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

The description clearly states the tool returns whether Optionality holds the patron's nsec, using a specific return format. This distinguishes it from related tools like optionality_escrow_nsec and optionality_withdraw_nsec.

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

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

It specifies the tool is free and polled by the frontend to decide UI affordances, giving clear usage context. It does not explicitly exclude other scenarios, but the context is sufficient.

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

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

With no annotations, the description carries the full burden. It adds that the entry includes scenario and evaluation, which is beyond the schema. However, it does not disclose auth requirements, rate limits, or whether it is read-only (though implied).

Agents need to know what a tool does to the 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, concise and front-loaded. No fluff, but could be slightly expanded without losing efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 there is an output schema, return values are not required, but the description fails to provide enough context for the parameters or usage scenarios. For a 3-parameter tool with no annotations, it is incomplete.

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

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

Schema description coverage is only 33%, with only npub having a description. The tool description does not clarify the entry_id parameter or any other parameter beyond what the schema already states.

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

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

The description clearly states the tool returns a journal entry with scenario and evaluation, using a specific verb ('return') and resource ('journal entry'). It distinguishes from siblings like optionality_list_journal (list) and optionality_delete_journal (delete).

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

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

No guidance on when to use this tool vs alternatives like list_journal or delete_journal. No prerequisites or context provided.

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

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

No annotations are provided, so the description must fully disclose behavior. It does not mention authentication (npub for billing), rate limits, destructiveness, or response format. The description adds no behavioral insights beyond the minimal purpose.

Agents need to know what a tool does to the 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, which is concise, but it is under-specified. It includes a code formatting for sort_by but lacks essential 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 5 parameters and an output schema, the description omits many details needed for effective use, such as the meaning of scope filters, the billing requirement for npub, and what the response contains.

Complex tools with many parameters or behaviors need more documentation. 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 high (80%), so the schema already explains most parameters. The description does not add any additional meaning to parameters like 'scope' or 'sort_by' 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 states it retrieves a 'Global leaderboard ordered by sort_by,' which is a specific verb-resource pair. However, it is vague and does not differentiate from sibling tools like optionality_get_my_rank, which might also use leaderboard data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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, no exclusions, and no context about prerequisites. The description provides no usage direction.

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

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

No annotations are provided, so the description must disclose behavioral traits. It does not mention side effects, permissions, or rate limits. It is likely read-only but not explicitly stated.

Agents need to know what a tool does to the 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 with no unnecessary words. It uses backticks to reference parameters, which is helpful. However, it lacks structure or bullet points.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 lack of annotations and 3 parameters, the description is minimal. Though an output schema exists, its content is unknown. The description does not cover usage context or return values adequately.

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

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

The schema has 3 parameters with 33% description coverage (only npub described). The description mentions sort_by but does not explain its meaning or valid values. dpop_token is undocumented. The description adds little value beyond the schema.

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

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

The description states it retrieves the caller's leaderboard row and rank under sort_by, which indicates a personal rank retrieval. However, 'leaderboard row' is ambiguous and 'caller' is not explicitly linked to the user. Sibling tool 'optionality_get_leaderboard' suggests this is personal, but the description lacks specificity.

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

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

No guidance on when to use this tool versus alternatives like 'optionality_get_leaderboard'. There is no mention of prerequisites or when not to use it.

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

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

With no annotations, the description carries full burden. It discloses the read-only nature, public data access, and return behavior including empty profile if none published. Minor omissions: no mention of potential relay failures or rate limits, but acceptable for a simple read.

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

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

Three sentences: purpose, free/public nature, and return fields. Each sentence adds value with no redundancy. Front-loaded with essential information.

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

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

Covers the core behavior and return fields. With an output schema presumably present, return details are not needed. Lacks error conditions but is adequate for a simple read tool with no annotations.

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

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

Schema coverage is 0% for the only parameter 'npub'. The description mentions 'npub' but does not explain its format (bech32, hex) or default behavior. For users unfamiliar with Nostr, this is insufficient to construct valid input.

Input schemas describe structure but not intent. Descriptions should explain 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 'Read' and the resource 'npub's public Nostr profile' (NIP-01 kind-0 metadata). It distinguishes from the sibling tool 'optionality_publish_nostr_profile' as the read counterpart, making the purpose unambiguous.

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

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

The description implies usage when needing a public profile, noting it is free and requires no proof. However, it does not explicitly state when not to use or compare with alternatives like other 'get_*' tools in the sibling list. Guidance is minimal.

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

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

Without annotations, the description carries the full burden. It does not disclose whether the operation is read-only, computationally expensive, requires authentication, or any side effects, leaving the agent underinformed.

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

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

A single, well-structured sentence that conveys the core purpose without any fluff or 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?

Given the presence of an output schema (covering return values) and a simple purpose, the description is complete enough. Minor improvement would be to mention that the proof is for a specific snapshot or that it requires a prior notarization.

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

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

The input schema already describes both parameters fully (100% coverage). The description adds no additional meaning or format details beyond what is 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 uses a specific verb 'Generate' and a clear resource 'Merkle inclusion proof', and it is distinct from siblings like 'list_notarizations' which list records rather than generating proofs.

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

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

No guidance is provided on when to use this tool versus alternatives such as check_proof_status or list_notarizations, nor any exclusions or prerequisites.

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

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

No annotations provided, so description carries full burden. It accurately describes the tool's output (reporting readiness) but does not disclose behavioral traits like side effects, authentication needs, or rate limits. The description is sufficient but not rich.

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

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

Three sentences: first summarizes purpose, second details output, third provides alternative. No wasted words, front-loaded, and every sentence adds value.

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

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

Given zero parameters and an existing output schema, the description is complete. It explains what the tool does without needing to describe return values. The 'Free' note adds minor but harmless 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?

No parameters exist, and schema coverage is 100%. The description does not need to add parameter meaning. Baseline for zero parameters is 4, and the description effectively conveys the tool's function without requiring parameter details.

Input schemas describe structure but not intent. Descriptions should explain 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 reports operator configuration readiness, showing which settings are configured/missing and how to deliver missing values. It distinguishes itself from the sibling tool get_patron_onboarding_status by specifying it is for operator-level 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 mentions an alternative tool for patron-level status, providing a clear when-not scenario. Though it does not elaborate on when to use this tool, the purpose is clear enough for selection.

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

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

With no annotations, the description fully discloses behavior: values are never exposed, delivered_at timestamps are provided (null if before recording), the tool is free, and it requires proof of npub ownership because the list of configured fields is sensitive. 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 two paragraphs, each with a clear focus: first on the return data, second on auth and sensitivity. It is efficient without extraneous words, though slightly more compact could be achieved.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, the description does not need to detail return types. It covers purpose, return fields (names + timestamps), behavior (never expose values), cost (free), and authentication requirements. All necessary context is provided.

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

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

Schema coverage is 100%, but the description adds significant value beyond schema descriptions, especially for dpop_token: it specifies the exact format (raw JSON of kind-27235 event), what not to use (base64, NIP-98 framing), and requirements like the u tag, content, created_at within 60s, and nonce recommendation. This is highly informative.

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

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

The description clearly states it lists stored patron credential field names (not values), with a specific verb 'List' and resource 'patron credential field names'. It distinguishes from sibling tools like update or delete by specifying it only returns names and timestamps, not values.

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

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

The description explains the tool can be used to verify which fields are configured and how old each one is, and mentions the authentication requirement. While it does not explicitly state when not to use it or name alternatives, the context is clear enough for an agent.

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

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

No annotations are provided, so the description carries full burden. It describes the tool as reporting status and mentions privacy sensitivity, but does not explicitly declare it as read-only or describe any side effects, rate limits, or error conditions.

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

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

The description is three concise sentences: one for primary purpose, two for context. No unnecessary words, well-structured and front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 main behavior, authentication requirement, and sensitivity. It could mention expected response structure or error handling, but overall it is complete for the tool's purpose.

Complex tools with many parameters or behaviors need more documentation. 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 little beyond what the schema already provides. It reiterates the requirement for dpop_token as proof of ownership but does not enhance understanding of parameter semantics.

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

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

The description clearly states the tool reports a patron's credential readiness for an operator, distinguishing between set-once and dynamic services. This is specific and differentiates from sibling tools like get_patron_credential_fields or 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 explains that proof of npub ownership (via dpop_token) is required and notes the tool is free. It implicitly indicates when to use (check readiness) but does not explicitly contrast with alternatives or state when not to use.

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

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

No annotations exist, so the description must fully convey behavior. It does not mention whether authentication is required, if the operation is read-only, or how the npub parameter affects billing. The description is too sparse to guide safe usage.

Agents need to know what a tool does to the 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, clear sentence with no extraneous words. It efficiently conveys the tool's primary purpose and return fields.

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

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

Given the existence of an output schema, the description need not detail return values, but it lacks context about what 'caller' means, how the npub is validated, and whether dpop_token is required. The minimal information leaves gaps 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 description adds no meaning beyond the input schema. The schema already documents npub as 'Required. Your Nostr public key... for credit billing.' The dpop_token parameter is not explained in either place. With 50% schema coverage, the description fails to compensate.

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

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

The description clearly states the tool returns the caller's profile with specific fields (display_name, avatar, bio, relays). However, it does not differentiate from the similar sibling 'optionality_get_nostr_profile', which may have different behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (e.g., optionality_get_nostr_profile). No prerequisites, context, or exclusion criteria are provided.

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

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

The description discloses a key behavioral trait: 'If no model exists, self-initializes a scaffold with all registered tools at 0 sats.' It also notes 'No economic data from code,' though this phrase is slightly ambiguous. Since no annotations are provided, the description carries the burden and handles it 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?

The description is three short, front-loaded sentences. Every sentence adds value: purpose, cost, and behavioral note. No wasted words.

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

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

Given the tool has no parameters and an output schema (though not shown), the description covers the essential point of initialization behavior. However, it does not describe the return structure or any error cases, but the output schema likely handles 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 tool has zero parameters, and the input schema is empty. The description does not need to explain parameters. Baseline is 4 for no parameters, 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's function: 'Get the active pricing model for this operator.' The mention of 'Free' adds clarity. This distinguishes it from sibling tools like optionality_set_pricing_model and optionality_reset_pricing_model.

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

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

The description provides clear context for when to use the tool (retrieve pricing model), but does not explicitly state when not to use it or name alternatives. However, for a straightforward getter, this is sufficient.

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

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

No annotations exist, so description carries full weight. It discloses the tool is a public, free read, eager-loads data, and requires no authentication. This covers key behavioral traits beyond the schema.

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

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

Four sentences, each adding value: core purpose, public access, eager-loading benefit, and authentication model. No unnecessary words; front-loaded with the main action.

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

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

With an output schema present, the description need not detail return values. It covers purpose, usage, behavior, and parameters adequately for a simple read tool, though it omits error scenarios or pagination 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 baseline is 3. The description does not add new information about parameters beyond what the schema already provides (e.g., 'target_npub' and 'limit' are self-explanatory).

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

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

The description clearly states the action ('List'), resource ('a target patron's shared evaluated entries'), and ordering ('newest first'). It distinguishes the tool from siblings like 'optionality_share_entry' which creates entries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when to use (to browse public shared entries), calls out the public and free nature, and notes it's a bootstrap tool without identity injection. It lacks explicit exclusion of alternatives but provides strong context.

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

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

Discloses side effects (persists, recomputes leaderboard) and async behavior (returns claim check). No annotations provided, so description bears full burden, and it meets it adequately.

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

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

Two sentences, front-loaded with action, zero waste. Every sentence adds value.

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

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

Covers key behavioral flow (claim check, polling). Does not explain format of trade_proposal or prerequisites, but output schema exists. Reasonably complete for the tool's complexity.

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

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

Schema coverage is 25% (only npub described). Description adds no further parameter details; meaning of entry_id, dpop_token, and trade_proposal are left implicit. Fails to compensate for low schema coverage.

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

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

Description clearly states the action ('Evaluate the trainee's trade') and specifies persistence, parsing, and leaderboard recomputation. It effectively distinguishes from siblings like 'optionality_fetch_judgement'.

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

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

Describes the asynchronous flow (returns claim check, poll with optionality_fetch_judgement) but does not explicitly state when to avoid using this tool or contrast with alternatives.

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

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

No annotations are provided, so the description carries full burden. It effectively discloses behavior: returns both ToolIdentity-seeded and @paid_tool tools missing from registry with 'registered: false', diffs the live wire surface, identifies deploy drift (#174/#175), and explicitly states 'Free, no side effects' at the end. This is strong behavioral disclosure for a zero-annotation tool.

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

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

The description is quite long for a no-parameter introspection tool, with some redundancy. Both the 'registered: false' point and the 'unregistered array / deploy drift' point are made to emphasize the same behavior (flagging drift instead of silently under-reporting), which repeats the same idea twice. While each section adds genuine value, the text could be tightened by ~30% without losing 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 (which reduces the burden on the description to explain returns), the description thoroughly covers the tool's purpose, consumers, edge cases (unregistered tools, renamed functions), and the design rationale (canonical-UUID). It's a zero-parameter tool, so there are no param gaps. The description fully compensates for absent annotations and provides a complete picture.

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

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

Tool has 0 parameters and schema coverage is 100% (empty properties object). With no params, the baseline is 4. The description appropriately doesn't waste space on parameter semantics since there are none to document.

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

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

Specific verb+resource ('Return canonical (tool_id, mcp_name, …) for every tool the wheel exposes'). Clearly states scope (every tool), and distinguishes from siblings by explaining it's the authoritative source for tool identity mapping. The 'list' family of siblings is much narrower (specific domain lists), so this is well differentiated.

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

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

Explicitly names the primary consumer ('Reconcile') and how the output is consumed ('UUID-join against the stored pricing model'). Tells the agent when NOT to guess ('no name-based UUID derivation, no guessing'). Provides strong context on which audience (Studio, agents, FE) needs this output.

Agents often have multiple tools that could apply. Explicit usage 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 bears the full burden. It adds the behavioral trait 'Free — no credits required', which is beyond a basic description. It does not address caching or rate limits, but for a simple listing tool, this is adequate.

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

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

The description is only two sentences, front-loading the core purpose. Every sentence adds value: the first states the action and output, the second adds cost context. 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 tool has no parameters and an output schema exists to document return values, the description is complete. It covers cost (free) and purpose, fully satisfying the needs for this simple listing tool.

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

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

The input schema has zero parameters and schema coverage is 100%, so the description does not need to add parameter information. The absence of parameters makes this dimension automatically well-served.

Input schemas describe structure but not intent. Descriptions should explain 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 available constraint types and their parameter schemas, specifies the return fields (type, category, description, parameter specs), and the context (pricing pipeline). This uniquely identifies it among siblings, none of which are about constraint types.

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

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

The description explicitly notes it is free and requires no credits, which helps usage decisions. While it doesn't state when not to use or list alternatives, the context is so straightforward that exclusion criteria are unnecessary.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool lists all minted coupons, returns rows with 'times_redeemed' counter against 'total_uses', and is restricted. It does not mention rate limits or pagination, but given the simplicity, it is fairly 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 composed of three concise sentences: the first states the purpose, the second provides details about the output fields, and the third notes the 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 that an output schema exists (though not shown), the description sufficiently explains the tool's purpose and a key output field. It clarifies the scope (operator's own minted coupons) and restriction. The parameter is not explained, but the tool is simple enough that the description is mostly complete.

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

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

The input schema has one optional parameter 'dpop_token' with no description. The tool description does not mention it, and schema description coverage is 0%. Since the description does not add meaning, it scores low despite the parameter likely being an authentication token.

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

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

The description clearly states the tool lists every coupon minted by the operator, newest first. It uses a specific verb ('list') and resource ('coupons'), and distinguishes itself from siblings like 'optionality_list_my_coupons' which likely lists coupons belonging to the caller, not necessarily minted by them.

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

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

The description mentions the tool is restricted to operators and requires proof, implying authentication. However, it does not explicitly state when to use this tool versus alternatives such as 'optionality_list_my_coupons' or when not to use it.

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

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

No annotations exist, so description carries full burden. Discloses SQL-based sorting/grouping and that each page is a slice of the fully-ordered dataset. Also specifies return structure. Misses explicit read-only or auth requirements, but list implies read-only.

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

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

Two sentences, front-loaded with purpose, then behavioral detail and return format. No fluff, every sentence adds unique value.

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

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

For a list tool with 9 parameters and an output schema, the description covers the key behavioral traits (SQL sorting, pagination) and the return structure. Given output schema existence, no need to enumerate return fields.

Complex tools with many parameters or behaviors need more documentation. 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 89% (8 of 9 parameters described). Description adds context about SQL processing but does not elaborate on any parameter meaningfully beyond the existing schema descriptions. The undocumented `dpop_token` is not addressed.

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

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

Clearly states it returns a sorted, grouped, paginated list of the caller's journal. Distinguishes from single-entry retrieval tools like `optionality_get_journal` and from reporting tools like `optionality_get_leaderboard`.

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

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

Implies usage for listing journal entries, but does not explicitly compare with sibling tools (e.g., `get_journal`, `get_my_rank`). No when-not-to-use or alternative guidance, leaving the agent to infer.

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

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

With no annotations provided, the description carries full burden. It discloses that it returns both active and exhausted redemptions with a per-row status field, and that it requires proof of npub and is free. This is sufficient for an agent to understand the basic behavior, though it could mention idempotency or rate limits.

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

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

The description is three sentences: first states purpose, second explains return content, third adds cost/auth info. No wasted words, well structured, and front-loaded with the main action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 purpose, return values, and auth requirements. With an output schema present, the agent can infer return format. However, it does not explain the dpop_token parameter or mention pagination, which could be needed for large lists. Still, it is mostly complete for a list tool.

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

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

The schema has 2 parameters (npub, dpop_token) with 0% description coverage. The description only mentions npub implicitly via 'requires proof of npub', but does not explain the dpop_token parameter or the format/requirements of npub. This leaves the agent guessing about the second parameter.

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

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

The description clearly states the verb 'List', the resource 'coupons', and specifies the scope 'this patron has redeemed on this operator'. It also distinguishes from sibling tools like list_coupons (generic) and redeem_coupon (action) by focusing on patron-specific redemptions.

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

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

The description provides implicit usage context by mentioning 'Free — requires proof of npub', but lacks explicit guidance on when to use this tool versus alternatives like list_coupons or check_proof_status. No when-not instructions 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?

No annotations are provided, and the description is minimal. It does not disclose whether the operation is read-only, destructive, requires authentication, or any rate limits. The term 'recent' is vague and not explained. The existing output schema partially compensates for return format, but behavioral context 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, a single phrase. While concise, it omits potentially useful context like sorting order or default behavior. It is not verbose but could be more informative without sacrificing conciseness.

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

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

Given the existence of an output schema and full parameter descriptions, the description provides adequate high-level purpose. However, it lacks details on pagination (beyond 'limit'), ordering, and the exact meaning of 'recent'. This leaves gaps for an agent to fully understand the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. 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 'limit' and 'status'. The description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists recent Bitcoin notarization records, using a specific verb ('List') and resource. It distinguishes from sibling 'optionality_get_notarization_proof' by implying a collection vs. a single proof, but does not explicitly differentiate.

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

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

No guidance on when to use this tool vs. alternatives like 'optionality_get_notarization_proof' or 'optionality_notarize_ledger'. Lacks context about prerequisites, when to avoid, or alternative tools for specific tasks.

Agents often have multiple tools that could apply. Explicit usage 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 merely states 'create' but fails to disclose behavioral traits like required permissions, idempotency, side effects, or ownership implications. With no annotations, this is a significant gap.

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

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

Single sentence, no wasted words. However, it could be longer to include usage guidance or behavioral context; conciseness is good but at the expense of completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 7 parameters and an output schema, the description is too minimal. It lacks context about uniqueness constraints, overlapping coupons, or any operational nuances required for 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?

Schema description coverage is 86%, high, so baseline is 3. The description adds no extra meaning beyond what parameters already convey in the schema.

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

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

The description clearly states the action 'Create' and the resource 'operator-owned discount coupon', distinguishing it from sibling tools like redeem_coupon, update_coupon, delete_coupon which have different verbs.

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

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

No guidance on when to use this tool vs alternatives (e.g., update_coupon), no prerequisites or context about who can create coupons or when creation is appropriate.

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

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

The description discloses that it is a background task, free, and requires operator privileges. It explains the core behavior (Merkle tree construction and Bitcoin submission) without annotations present. No destructive or side-effect information is given, but for a non-destructive background task, it provides adequate transparency.

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

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

The description is three concise sentences: first states the operation, second identifies the audience and nature (operator-only background), third provides time and cost. Every sentence adds value with no redundancy or superfluous 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 an output schema (present), the description covers purpose, intended user, execution nature, and expectation (1-6 hours, free). It does not detail the output, but that is assumed to be in the schema. Adequate for the tool's complexity.

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

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

The tool has zero parameters and the schema coverage is effectively 100%. The description adds overall context but does not need to describe parameters. Per rubric, high schema coverage baseline is 3, and the description adds no parameter-specific details, so a 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 builds a Merkle tree of patron balances and submits the root to Bitcoin via OpenTimestamps. The verb 'Build' and 'submit' plus the specific resource (patron balances) make the purpose unmistakable, and it distinguishes from sibling tools like 'get_notarization_proof' or 'list_notarizations' which are about retrieval, not initiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 it is an 'Operator-only background task' and notes confirmation takes 1-6 hours, providing clear context on who should use it and what to expect. It does not explicitly state when not to use or compare to siblings, but the context is sufficient for an agent to infer appropriate usage.

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

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

With no annotations, the description falls short in disclosing behavioral traits. It mentions 'Free' but does not explain what 'via the Oracle' entails, whether it's a query, or if any state is affected. The behavioral impact is unclear.

Agents need to know what a tool does to the 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, consisting of two fragments. While concise, the placement of 'Free.' feels disjointed and could be integrated better. It earns its place but lacks structure.

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

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

Given the simplicity (no parameters, output schema exists), the description could still provide more context about the oracle's role or what the ecosystem description includes. It is inadequate for the sibling tool diversity.

Complex tools with many parameters or behaviors need more documentation. 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 schema coverage is 100%. The description adds no additional meaning beyond the schema, but the baseline for zero parameters is 4, as no further parameter information is needed.

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

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

The description states 'Describe the DPYC ecosystem via the Oracle', which clearly indicates the action (describe) and resource (DPYC ecosystem). However, it does not differentiate from similar oracle tools like 'optionality_oracle_how_to_join' or 'optionality_oracle_network_advisory'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 only extra information is 'Free', which is vague and does not help with usage decisions.

Agents often have multiple tools that could apply. Explicit usage 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 for behavioral disclosure. It only states 'Free' and the basic action, omitting whether the operation is read-only, idempotent, or has any side effects. No behavior beyond fetching is described.

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

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

The description is extremely concise with two short statements that convey the essential purpose. It is front-loaded and contains no redundant or irrelevant information.

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

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

Given the tool's simplicity, the description is partially complete. It states what it does but lacks context about the meaning of 'DPYC certification tax rate', any prerequisites, or the output format (despite an output schema existing). Agents may need additional information to decide when to use this tool.

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

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

There are zero parameters, and schema coverage is 100% trivially. The description adds no parameter information, which is acceptable as no parameters exist. The baseline score of 4 for zero parameters 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 specifies the verb 'Get' and the resource 'DPYC certification tax rate', making the tool's purpose unambiguous. It distinguishes itself from sibling tools like 'optionality_check_price' or 'optionality_get_pricing_model' by targeting a specific tax rate.

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

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

No guidance is provided on when to use this tool versus alternatives. The word 'Free' hints at cost but does not clarify context or exclusions. Agents have no information about prerequisites or scenarios where this tool is appropriate.

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

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

No annotations are provided, so the description must carry the full burden. It states the tool returns instructions for free, but lacks details on authentication, rate limits, or other behavioral traits. The presence of an output schema is not described.

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

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

The description is a single, front-loaded sentence with no wasted words. It conveys the essential purpose efficiently.

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

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

Given the tool's simplicity (no parameters, output schema exists), the description is mostly complete. However, it could benefit from mentioning what form the instructions take or any prerequisites. The mention of 'Free' is helpful.

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

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

The tool has zero parameters, and the input schema is fully covered. The description adds no parameter details, which is acceptable as there are none to explain. Baseline for 0 params is 4.

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

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

The description clearly states the action (Get), the resource (DPYC onboarding instructions), and the source (the Oracle). It is specific and distinguishes this tool from siblings like 'oracle_about' or 'oracle_get_tax_rate'.

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

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

The description implies usage when onboarding instructions are needed, but does not explicitly state when to use this tool versus alternatives. No exclusions or prerequisites are mentioned.

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

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

With no annotations, the description should fully disclose behavior. It states 'Free' but does not confirm read-only status, authentication requirements, rate limits, or whether it has side effects. The term 'look up' suggests idempotency, but this is not explicit.

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

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

The description is extremely concise with two short phrases. Every piece of information (lookup, target, key, cost) is included without redundancy, making it highly efficient.

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

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

Given the tool has a single parameter and an output schema (unknown content), the description lacks details about the result of the lookup. It does not specify what information is returned (e.g., profile data, member status), leaving the agent underinformed.

Complex tools with many parameters or behaviors need more documentation. 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 coverage is 0%, so the description must compensate. It mentions 'npub' but does not explain what an npub is, its format, or any constraints. The description adds minimal value beyond the parameter name.

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

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

The description clearly states that the tool looks up a DPYC community member using an npub. The verb 'look up' indicates retrieval, and the resource is specified. However, it doesn't differentiate from potential similar tools like optionality_get_nostr_profile.

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

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

The description provides no guidance on when to use this tool versus alternatives. It only mentions 'Free,' which implies no cost but does not clarify when not to use it or provide context for selection among 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 bears full responsibility for behavioral disclosure. It only states it is a read operation ('Get') and free, but does not describe potential outcomes (e.g., empty result), error conditions, or any side effects. This 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 extremely concise with two short sentences. No wasted words; the purpose 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?

For a tool with zero parameters and an output schema, the description is adequate but minimal. It explains the basic function but could provide more context about what 'network advisories' are or how the output is structured. The output schema likely covers the return format, so it is moderately complete.

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

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

There are no parameters, and schema coverage is 100% (trivially). The description does not need to add parameter semantics. Baseline for zero parameters is 4.

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

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

The description clearly states the action 'Get active network advisories' and the resource 'from the Oracle'. It is a specific verb+resource that distinguishes it from the many sibling tools, which cover accounts, statements, coupons, etc.

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

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

No usage guidance is provided; it does not indicate when to use this tool versus alternatives or when not to use it. The mention of 'Free' is a minor note but not 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 carries the full burden. It discloses key behaviors: no key custody, signature verification against npub, relaying to public relays, and that it is free. This exceeds minimal expectations by explaining the security model and authorization method.

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

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

The description is four sentences, front-loaded with the primary action, followed by security, process, and cost. Each sentence is necessary and concise, with no redundant or vague language.

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

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

For a mutation tool with no annotations, the description covers input requirements and behavior well but omits output expectations (e.g., success confirmation). Since an output schema exists (per context signals), the gap is partially mitigated, but the description could still mention what the tool returns.

Complex tools with many parameters or behaviors need more documentation. 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 the relationship between npub and signed_event: the wheel verifies the signature matches the npub. This clarifies why npub is needed beyond the schema description and reinforces the flow.

Input schemas describe structure but not intent. Descriptions should explain 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 publishes a client-signed kind-0 profile to relays for an npub, using a specific verb ('Publish') and resource ('kind-0 profile'). It distinguishes from sibling tools like 'optionality_get_nostr_profile' which is read-only.

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

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

The description explains when to use this tool: when a client-signed kind-0 event is available and the wheel should relay it. It implicitly contrasts with other profile tools by emphasizing 'client-signed' and that the wheel never holds the nsec, guiding the agent away from other signing or key-custody 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 discloses key behaviors: invoice creation, payment requirement, verification step, ownership proof, and cost-free operation. Adequately transparent.

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

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

Concise two-paragraph description with no unnecessary words. Every sentence adds value and is front-loaded with the main purpose.

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

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

With output schema present, description covers the workflow well. It explains the process and next steps, though could mention expiry or failure scenarios.

Complex tools with many parameters or behaviors need more documentation. 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 description adds minimal value beyond stating proof of npub ownership (related to dpop_token). Parameters are well-documented in 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 'Buy credits via Bitcoin Lightning' and explains the invoice creation process, distinguishing it from sibling tools like check_balance and account_statement.

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

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

Provides step-by-step guidance: create invoice, pay with any Lightning wallet, then call check_payment. Also notes that it is free and requires npub ownership 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, so description carries full burden. It details deterministic one-shot retrieval, relay draining behavior, NACK/ACK process, and credential_card redemption without server restart.

Agents need to know what a tool does to the 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 a lead sentence and clear sections, but somewhat lengthy. However, every sentence contributes useful 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?

Description covers the entire flow, including success/failure conditions, two execution paths, and effects (client reinitialization). An output schema exists, so return values are not 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 has 100% description coverage for all 4 parameters. Description adds behavioral context (e.g., dpop_token as session phrase, sender_npub as the sender, credential_card bypasses relay), providing additional 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?

The description states 'Pick up credentials from the Secure Courier' and distinguishes the tool from its sibling 'receive_npub_proof' by referencing the CREDENTIAL-DELIVERY 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?

Explicitly states 'Call this only after the user confirms they have replied' and warns against polling, looping, or retrying. Also describes two paths (relay drain and credential_card redemption).

Agents often have multiple tools that could apply. Explicit usage 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 covers behavior: drains only pinned relay, stops at matching DM, deletes mismatched DMs without revealing expected phrase, and explains what happens if called too early. Also details proof storage (hash only) and the signed DM proving ownership.

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

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

Well-structured with clear paragraphs and bullet-like points. Front-loaded with purpose. Could be slightly more concise, but every sentence adds value and 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?

Given output schema exists, return value explanation is sufficient (dpop_token on success). Covers edge cases (user hasn't replied, mismatched DMs) and explains the flow thoroughly.

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

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

Schema coverage is 100%, but description adds context: dpop_token is from request_npub_proof, patron_npub is the patron's npub, and both are described as required. Minor inconsistency with schema not marking them required, but overall meaning is 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?

The description clearly states it receives npub ownership confirmation from a patron and completes the npub-OWNERSHIP-PROOF flow. It distinguishes itself from sibling tools like optionality_request_npub_proof and optionality_receive_credentials.

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

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

Explicitly says 'Call this only after the user confirms they have replied.' and warns against polling/looping. Provides deterministic one-shot retrieval instructions and marks the dpop_token for later use. Differentiates from receive_credentials.

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

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

No annotations provided, so description carries full burden. It discloses validation of window and cap, recording of redemption, auto-application of discount, idempotency, and cost (free). It does not mention error cases or rate limits, but covers key behaviors.

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

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

The description is a compact paragraph with bullet-like statements. It front-loads the main action and each sentence adds value. No redundancy or wasted words.

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

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

With three parameters (two required), no annotations, and an output schema present, the description covers validation, idempotency, discount application, and cost. It explains behavior for duplicate use. It doesn't detail output structure, but output schema exists. Overall, it provides sufficient context 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?

Schema coverage is 0%, so description must add meaning. It explains that 'code' is the operator's shared code and 'npub' is proof of identity. The optional dpop_token is not described, but its purpose can be inferred. This compensates well for low schema coverage.

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

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

The description explicitly states 'Claim a coupon by its name (the code the operator shared)', which is a specific verb+resource. It explains the lookup, validation, and recording process, and distinguishes from siblings like update_coupon, delete_coupon, and list_coupons.

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

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

The description notes that it's free, requires proof of npub, and is idempotent. It implies usage when a coupon code is available. It doesn't explicitly state when not to use or list alternatives, but given the sibling list, context is sufficient.

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

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

The description discloses that reports are public, attributed to the user's npub, incur a small fee (to prevent abuse), and are not verified. Since no annotations are provided, the description carries the full transparency burden and does so adequately.

Agents need to know what a tool does to the 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 and front-loaded with the main action, followed by conditions, cost, and output. It is slightly long but each sentence adds necessary context, so it earns a 4.

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

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

Given 5 parameters (4 required), no enums, an output schema, and no annotations, the description covers the tool's purpose, usage context, and key behaviors (fee, public attribution, unverified nature). It could mention the output schema returns repo, number, and URL, but overall it 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?

All 5 parameters are documented in the schema with 100% coverage. The description adds valuable context, such as the npub being the author of record and detailed instructions for the dpop_token (raw JSON of kind-27235 Nostr event, constraints on formatting and freshness).

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

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

The description clearly states the tool files a field report as a GitHub issue on the operator's repo, specifying the action, requirements, and outcome. It distinguishes itself from sibling tools that are primarily for account or oracle 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 explains when to use this tool (reporting wrong or confusing metadata/response) and what happens if field reports are not configured. It does not explicitly state when not to use it, but the context is clear.

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

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

No annotations provided, so description carries full burden. It details the process: resolves endpoint, mints ownership proof, delivers MCP-to-MCP, and the asynchronous nature (deferred courtship). It also explains the eventual state (operator flips to ready). 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 concise and well-structured: a clear one-line purpose followed by a detailed yet efficient explanation. It front-loads the key action and then covers restrictions, process, and follow-up without unnecessary words.

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

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

Given the complexity (operator adoption, MCP-to-MCP, authentication), the description covers the core flow: who can use, prerequisites, process, status polling, and end state. It doesn't explicitly state the return value, but an output schema exists to handle 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?

Schema coverage is 100%, but the description adds meaningful context beyond the schema, such as the requirement for ownership proof (dpop_token) and that authority_npub is resolved from a community registry. This enhances 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 purpose: 'Ask a chosen Authority to adopt this operator' and distinguishes it from sibling tools like optionality_adoption_status, which polls for progress. The verb+resource is specific and unambiguous.

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

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

The description explicitly states RESTRICTED to the operator, requires proof of control, and directs users to poll 'adoption_status' for progress. This provides clear when-to-use and when-not-to-use guidance with an alternative 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?

With no annotations, the description explains the human-in-the-loop flow, that it sends a welcome DM, and the need to wait for manual reply. It also warns about receive_credentials' destructive behavior. However, it doesn't explicitly state side effects of this tool itself (e.g., creating a channel) but the detail is strong.

Agents need to know what a tool does to the 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 clear sections: purpose, usage, process, instructions. It is relatively concise given the complexity, though some repetition (e.g., 'human-in-the-loop') is present. Front-loaded with key information.

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

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

Given the tool has an output schema (so return values don't need explanation), the description fully covers purpose, usage, behavioral nuances, and post-call steps. It references related tools and provides a complete understanding of how to use the tool correctly.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds context about the flow (welcome DM, credential delivery) but does not significantly enhance parameter meaning beyond 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 states the tool opens a Secure Courier channel for credential delivery, explicitly distinguishing it from request_npub_proof for npub control. It also notes when not to use (dynamic/OAuth2 services). The purpose is specific and well-differentiated from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (credential delivery), when not (npub proof, OAuth2), and what to do after calling: stop, tell the user, wait for confirmation, avoid polling, and note destructive drain of receive_credentials. Excellent usage instructions.

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