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 the tool generates a statement, returns specific data, is free, and requires authentication. It also clarifies what the statement is not (operator's tax balance). No mention of side effects, but 'generate' implies a read operation and no mutations.

Agents need to know what a tool does to the 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: four sentences with clear front-loading of purpose. Every sentence adds value (purpose, content, distinction, cost, prerequisite). No redundancy or fluff.

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

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

Given the existence of an output schema, the description need not detail return values, but it helpfully lists the content. It covers key aspects: purpose, required auth, cost, and differentiation. Could mention behavior of the 'days' parameter, but overall sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it lists what the statement includes but does not elaborate on parameters like 'days' or 'dpop_token'. The 'days' parameter's effect (including daily usage history) is only implied by the description's mention of daily usage logs.

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

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

The description clearly states the verb 'Generate' and the resource 'patron's account statement', listing the specific data returned (purchase history, credit tranches, etc.). It distinguishes the statement from the operator's tax balance, but does not explicitly differentiate from the sibling tool 'optionality_account_statement_infographic', leaving some ambiguity.

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

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

The description mentions that the tool is free ('no credits consumed') and that proof of npub ownership is required, which are useful usage constraints. However, it does not provide guidance on when to use this tool versus alternatives (e.g., the infographic sibling).

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

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

No annotations provided, but the description discloses cost (1 api_sat) and the verification step, which is important behavioral context. It also describes the output format in detail.

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

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

The description is three sentences, front-loaded with the main purpose, then output details and cost. Every sentence is necessary and well-structured.

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

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

Given the presence of an output schema, the description adequately explains the tool's output and cost implications. Minor missing details (e.g., performance) don't significantly impact completeness.

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

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

Schema coverage is 100% so all parameters are documented. The description adds no additional meaning beyond the schema's descriptions, meeting the baseline.

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

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

The description clearly states the tool generates a visual SVG infographic of an account statement, distinguishing it from the sibling tool 'account_statement' by specifying the output format and elements.

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

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

It mentions cost and verification but does not explicitly guide when to use this tool vs the plain account_statement. The context is implied but not clearly stated.

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

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

No annotations are provided, so the description carries the full burden. It states 'Free' and lists possible statuses (pending/approved/rejected/provisioned) but does not disclose error handling, authentication needs, rate limits, or side effects. The description is too minimal for a mutation-free 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 short sentences, no redundant information, and front-loaded with the core purpose. Every word earns its place.

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

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

The output schema exists, so return values need not be explained. However, the description lacks prerequisites (e.g., whether an adoption request must exist first), error scenarios, and relationship to sibling tools. For a simple check tool, it covers the minimum but leaves gaps.

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

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

Schema description coverage is 0%, yet the description fails to explain any parameter. It mentions 'at a chosen Authority' implicitly referring to 'authority_npub', but provides no details on the 'dpop_token' parameter or expected formats. The description adds no value beyond the raw 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', the resource 'adoption-request status', and the context 'operator's' and 'at a chosen Authority'. It uniquely identifies the tool among siblings with related names like 'optionality_request_adoption' and 'optionality_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 mentions it is free and polls the Authority MCP-to-MCP, but does not explicitly state when to use this tool versus alternatives like 'optionality_request_adoption' or 'optionality_get_operator_onboarding_status'. It provides no exclusions or contextual triggers.

Agents often have multiple tools that could apply. Explicit usage 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 reveals key behaviors: the tool returns a claim check (not the hint), requires polling via `fetch_tip`, and handles degenerate questions synchronously. It does not mention error conditions, rate limits, or authentication details, but the core async behavior is well-disclosed.

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

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

The description is succinct: a clear opening sentence, parameter explanation, return pattern, and edge case. Each sentence earns its place without redundancy. It is well-structured and front-loaded with the core purpose.

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

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

Given the tool's complexity (async pattern, claim check), the presence of an output schema (reducing need to describe return structure), and 5 parameters, the description is largely complete. It covers the async workflow and degenerate input but omits details about `dpop_token` and potential error states.

Complex tools with many parameters or behaviors need more documentation. 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 20% (only npub has a schema description). The tool description compensates by explaining the `history` parameter's purpose and the degenerate question case. However, `entry_id`, `question`, and `dpop_token` lack meaningful description, relying on inference. The added value is moderate.

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

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

The description clearly states the verb 'Get' and the resource 'a non-spoiler Socratic hint for an open journal entry'. It distinguishes this tool from the companion `optionality_fetch_tip` by explaining the claim check pattern, making the purpose highly specific and 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?

The description provides clear context for when to use the history parameter for follow-up conversations and notes that 'oversupplying gains nothing' (a usage hint). It also explains the degenerate question case. However, it does not explicitly state when NOT to use this tool versus siblings, though the claim check pattern implies the need for `fetch_tip` afterward.

Agents often have multiple tools that could apply. Explicit usage 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 the tool is read-only (check operation), returns sats available, and notes consequences of zero balance. It also states it is 'Free', implying no cost or side effects. This sufficiently covers behavioral traits.

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

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

Description is concise with multiple sentences, each adding value: function, return, condition, distinction, and cost. No redundant or unnecessary information. Well-structured and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 presence of output schema, the description fully explains the tool's purpose, return value, relevant conditions, and clarifies it is operator-specific and free. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. 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, baseline is 4. Description does not add parameter information as there are none, so no expectation violated. It remains clear about what the tool does without 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?

Description clearly states the tool checks the operator's tax balance at the Authority, distinguishes from patron balance by stating 'operator's own funding — not a patron balance', and provides specific context (returns sats for certifying patron credit purchases). This differentiates it from siblings like 'optionality_check_balance'.

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

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

Explicitly states when to use (to check operator's tax balance before certifying patron top-ups) and what to do when balance reaches zero (call purchase_credits). Also clarifies it is not for patron balances, guiding against misuse.

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

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

Discloses that the call is free, requires proof of npub ownership via a signed token, and explains the anti-enumeration rationale. No annotations provided, so description carries full burden; minor gap on error behavior.

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

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

Five sentences in two paragraphs, front-loaded with purpose. Every sentence adds value: what, distinction from sibling, free, auth requirement. 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?

With a low-complexity tool, high schema coverage, and output schema present, the description provides all needed context: domain, cost, auth, and sibling differentiation.

Complex tools with many parameters or behaviors need more documentation. 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 good descriptions, and the description adds context: dpop_token is a kind-27235 signed event and explains its purpose (proof of ownership), exceeding schema alone.

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

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

The description clearly states the tool checks a patron's credit balance at this operator, specifying it's the spending balance from Lightning purchases. It distinguishes from authority_check_balance, making 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?

Explicitly tells when to use this (patron balance) vs authority_check_balance (operator's balance). Also notes it's free and requires npub proof, setting clear 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?

No annotations provided, but description discloses key behaviors: free operation, authentication requirement (npub proof), and context after payment. Some details like idempotency or error states are missing, but adequate for a read-only 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?

Description is very concise (3 sentences) with front-loaded purpose. Every sentence adds unique value: purpose, usage context, and rationale for auth requirement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 is sufficiently complete for a simple status check. It covers workflow context, cost, and auth. Could mention what happens if payment not yet made, but not critical.

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

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

Schema covers all parameters with descriptions. The tool description adds value by explaining the rationale for dpop_token and clarifying invoice_id source from purchase_credits. This helps the agent understand parameter relationships.

Input schemas describe structure but not intent. Descriptions should explain 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 payment status of a Lightning invoice, with specific verb-resource pair. It distinguishes itself from siblings like optionality_check_balance by tying to the purchase_credits workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 to call after paying the invoice from purchase_credits, mentions it's free, and explains the need for npub proof to prevent front-running. This is clear when-to-use guidance.

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

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

No annotations are provided, so the description carries the full burden. It states the tool is free and previews cost, implying a read-only, non-destructive operation. However, it does not disclose authentication needs, rate limits, side effects, or whether it modifies state. The description adds some behavioral context (free) but lacks completeness.

Agents need to know what a tool does to the 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 plus a tag. It is front-loaded with the core action ('Preview the effective cost of a tool call') and every sentence adds value. 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 4 parameters and an output schema, the description is brief. It covers the core purpose and freeness but omits context like when to call it, prerequisites, or the nature of the preview (e.g., is it static or dynamic?). The existence of an output schema partially mitigates the need for return value details, but more contextual completeness would improve agent usage.

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

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

Schema coverage is 50% (only tool_id and tool_kwargs have descriptions). The description does not explain the purpose of npub or dpop_token, nor does it provide additional details beyond the schema. With half the parameters undocumented in both schema and description, the description fails to compensate for the gap.

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

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

The description clearly states the tool's purpose: 'Preview the effective cost of a tool call.' It specifies what it shows (base cost and constraint effects) and that it's free. This distinguishes it well from sibling tools, which cover accounts, statements, deals, 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?

The description mentions it's free but does not provide explicit guidance on when to use this tool vs alternatives (e.g., optionality_get_pricing_model). There is no exclusion criteria or context about prerequisites. Usage is implied but not clearly delimited.

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

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

No annotations provided, so description fully bears this burden. States it is free, has no side effects, does not evict cache or touch relays. Missing details on authentication or rate limits but sufficient.

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

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

Concise, three sentences. Front-loads purpose, then usage context, 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 output schema exists, return values need not be described. Tool is simple; description covers purpose, usage, and behavioral guarantees 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?

Input schema has 100% coverage with descriptions, so description adds minimal extra value. Only mentions parameters in passing, no new semantic context.

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

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

Clearly states the action: check if a dpop_token is still valid. Distinguishes from siblings by specifying it mirrors check_oauth_status for 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?

Explicitly advises use before a paid call to avoid wasted credits. Lacks explicit when-not-to-use or alternative tool names, but context is clear.

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

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

No annotations provided, so description must carry behavioral disclosure. It fails to mention that this is a write operation that creates a journal entry, may incur token costs, or that replay_entry_id skips LLM call. The description is silent on side effects, auth requirements, or output behavior.

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

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

Description is a single sentence, which is concise but lacks structure. It could be improved with bullet points or separate sections for purpose and usage, but it is not overly verbose.

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

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

For a tool with 7 parameters and an output schema, the description is inadequate. It does not explain what an options trading scenario entails, how the journal entry is used, or any context about the replay mechanism. Given the complexity, more context is needed for effective use.

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

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

Schema description coverage is 86%, high, so baseline is 3. The tool description does not add meaning beyond schema, but the schema already provides detailed parameter descriptions. No additional parameter insight is necessary.

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

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

The description uses specific verb 'generate' and identifies the resource as 'options trading scenario' and 'journal entry'. It clearly states the tool creates a fresh scenario, implying new creation. However, it does not explicitly distinguish from sibling tools like fetch_scenario, which retrieves existing scenarios, but the word 'fresh' provides differentiation.

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

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

No guidelines on when to use this tool vs alternatives like fetch_scenario or judge_trade. No prerequisites or exclusions mentioned. The description does not guide on selecting mode or difficulty parameters, relying solely on schema descriptions.

Agents often have multiple tools that could apply. Explicit usage 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 cascading deletions to redemptions, chain step behavior (no-op for unknown ids), and studio warnings. The restriction and proof requirement are also noted. It could add details on irreversibility but is otherwise 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 very concise: three sentences with no redundant information. It front-loads the core action and efficiently adds necessary context about side effects and restrictions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 annotations and 0% schema coverage, the description should be comprehensive. It covers purpose, side effects, and authorization, but lacks parameter descriptions and error conditions. The existence of an output schema mitigates missing return info, but overall completeness is moderate.

Complex tools with many parameters or behaviors need more documentation. 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 mentions 'coupon_id' implicitly but does not describe its format or purpose. 'dpop_token' is completely undocumented. The description adds minimal semantic value for parameters.

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

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

The description starts with 'Delete a coupon.', a clear verb+resource pair. It further specifies cascading to patron redemptions and chain step behavior, which distinguishes it from siblings like 'forget_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 explicitly states 'RESTRICTED to operator — requires proof.', providing clear context on who can use the tool and what authorization is needed. It does not directly mention alternatives or when not to use, but the restriction is sufficient guidance.

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

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

With no annotations, the description carries full burden. It discloses that the deletion is permanent ('Hard-delete') and that it recomputes the leaderboard cache, which is a significant side effect. However, it does not mention any authentication, rate limits, or confirmation steps, though the schema provides some context via the npub parameter.

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

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

The description is very concise (one sentence), but it could be restructured to list parameters or provide examples. However, it is front-loaded with the key action, so it earns a good score for 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 the low schema coverage and no annotations, the description should provide more context about parameters and return values. The side effect is mentioned, but the lack of parameter guidance and usage instructions makes it incomplete for an agent to use correctly.

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

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

Schema description coverage is only 33% (only npub has a description). The tool description adds no meaning for the other two parameters (entry_id, dpop_token), which remain undocumented. The description fails to compensate for the low coverage.

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

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

The description clearly states the action ('Hard-delete') and the resource ('a journal entry'), and also mentions a side effect ('recompute the leaderboard cache'), distinguishing it from sibling tools like optionality_get_journal or optionality_list_journal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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, no prerequisites, and no exclusions. The agent must infer usage purely from the verb 'delete', but there is no explicit when-to-use or when-not-to context.

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

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

No annotations provided, but description discloses write operation, proof requirement, and sensitivity. Mentions 'Free' which adds value. Lacks error or side-effect details.

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

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

Three concise sentences, front-loaded with purpose, each sentence adds necessary information without redundancy.

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

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

Adequately describes the action and requirement for a simple deletion. Output schema exists, so return value explanation not needed. Could mention if only certain fields are deletable or error conditions.

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

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

Schema covers all 3 parameters with descriptions. Description adds minimal value beyond schema: mentions proof of ownership linking dpop_token and npub but no additional 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?

Clearly states 'Remove a single patron credential field' and elaborates with 'Deletes one field from stored credentials without affecting other fields.' Specific verb and resource, distinct from siblings like update_patron_credential.

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

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

Provides context like 'Proof of npub ownership is required' and 'this is a write to the patron's sensitive credential vault,' but does not explicitly state when not to use or list alternatives.

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

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

No annotations provided, so description carries full burden. It discloses operator can sign DMs on behalf, encryption details (AES-256-GCM, key derived from operator nsec), and rejection condition if nsec doesn't match npub. Minor gap: no mention of cost 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?

Description is concise (5 sentences), front-loaded with core purpose, and each sentence adds value without redundancy.

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

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

Given an output schema exists, description covers purpose, usage context, behavioral notes, and constraints. Could mention success/failure feedback but output schema likely covers it.

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

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

Schema description coverage is only 33% (only npub has a description). The description does not add meaning for nsec or dpop_token beyond the schema. It mentions nsec must be fresh but doesn't clarify format or restrictions.

Input schemas describe structure but not intent. Descriptions should explain 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 deposits a freshly-generated nsec for operator-managed Nostr signing. It distinguishes from sibling 'optionality_withdraw_nsec' (the withdrawal counterpart) and specifies it's for game-persona keypairs 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?

Explicitly says when to use: for fresh game-persona keypairs, not for existing Nostr identities. Also provides a constraint: nsec must derive to the same npub that authenticated the call.

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

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

Discloses polling mechanism, status transitions (running, done, expired), and result structure (entry_id + evaluation). Also states 'Free.' No annotations provided, and description does not mention auth requirements beyond npub parameter, but overall good transparency for a poll 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?

Four sentences, front-loaded with purpose and polling logic. No redundant information; every sentence adds value.

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

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

Covers the polling pattern and result fields (entry_id, evaluation). Output schema exists, so return values need not be fully detailed. Implicitly requires a prior judge_trade call; could be more explicit but is clear enough.

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

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

Adds context for claim_check parameter by stating it is a claim check from judge_trade. npub description repeats schema. dpop_token gets no additional info. Schema coverage is low (33%), but description partially compensates for claim_check.

Input schemas describe structure but not intent. Descriptions should explain 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 'Redeem a judge_trade claim check' and describes the polling lifecycle (running, done, expired), distinguishing it from sibling tools like optionality_judge_trade (which initiates the 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?

Provides explicit polling instructions: 'While status is running, wait poll_after_seconds and call again.' Also explains when to use again (expired) and that it's free. Does not list alternatives or explicit when-not-to-use scenarios, but context is clear.

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

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

With no annotations, the description carries full burden. It discloses the polling behavior, status transitions (running, done, expired), and action for each state. It mentions 'Free.' for billing context. Missing details like idempotency or error handling, but overall 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 extremely concise and well-structured: one-line action, then clear conditional instructions with formatting (backticks for variables). Every sentence adds value, no redundancy.

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

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

Given the complexity of polling and output schema existence, the description covers the lifecycle adequately. It explains what to do in each state. Missing explicit prerequisites (must have called deal_scenario first) and error cases, but these are inferable.

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

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

Description only indirectly explains 'claim_check' by mentioning 'claim check' in context, but does not specify its format or constraints. It ignores 'npub' (required) and 'dpop_token' entirely. Schema coverage is low (33%), so description should compensate but fails to explain all 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 verb 'Redeem' and the resource 'deal_scenario claim check', making the tool's purpose specific. It distinguishes from siblings like optionality_deal_scenario which creates the claim, and optionality_fetch_judgement which fetches a different resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 instructions on when to call: while status is running, wait and retry; when done, read result; if expired, start new request. This guides usage effectively. It does not explicitly mention alternatives but the polling pattern is clear.

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

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

No annotations are provided, so the description carries full burden. It discloses the polling pattern, statuses, and result structure. However, it omits details about authentication or billing implications of the npub parameter.

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

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

The description is very concise and front-loaded with the purpose. Every sentence adds value, explaining the polling flow without extra 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 output schema exists, the description appropriately focuses on the polling behavior and statuses. It covers the lifecycle well but could mention that claim_check comes from optionality_ask_tip.

Complex tools with many parameters or behaviors need more documentation. 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% (only npub has a description). The description does not explain the parameters (claim_check, dpop_token) beyond what is in the schema. It fails to add meaning for the two undocumented 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 'Redeem an ask_tip claim check' with a specific verb and resource. However, it does not explicitly distinguish this from sibling fetch tools like optionality_fetch_judgement or optionality_fetch_scenario.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clear context: free, asynchronous polling behavior with statuses (running, done, expired). But it does not explicitly state when to use this tool versus alternatives, such as after obtaining a claim_check from optionality_ask_tip.

Agents often have multiple tools that could apply. Explicit usage 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 carries behavioral disclosure. It states the operation is cosmetic, coupon persists, can be re-redeemed, and requires proof of npub. This informs the agent of non-destructive, cost-free nature.

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

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

Three concise sentences: main action, behavioral nuance, and usage condition. No wasted words, properly front-loaded.

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

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

Given output schema exists and moderate complexity (3 params), the description covers behavior, prerequisites, and side effects. It could mention error handling but is adequate.

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

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

Schema coverage is 0% (no descriptions for parameters) and the description only implicitly defines npub as patron identifier and coupon_id as coupon to remove. It adds minimal meaning beyond field names, missing explicit format or constraints.

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

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

The description clearly states the tool removes a coupon from a patron's redemption list, using specific verb 'remove' and resource 'coupon'. It distinguishes from siblings like 'optionality_delete_coupon' by noting it is 'cosmetic only' and the coupon still exists.

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

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

The description implies the tool is for cosmetic removal (coupon can be re-redeemed) but does not explicitly compare to alternatives like delete_coupon or list_coupons. No when-not-to-use advice is given.

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

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

No annotations provided, so description carries full burden. Discloses destructive nature ('as destructive as a write') and the need for a dpop token for proof of ownership. Lacks detail on side effects or reversibility.

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

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

Two concise sentences: first states purpose, second adds essential usage context. No fluff, 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?

Covers purpose, param usage, and security warning. Output schema exists but description doesn't mention return values; still fairly complete for a destructive 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 coverage is 100%, so baseline 3. Description adds context on dpop_token purpose and destructive nature, but does not add new constraints or details 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 clearly states the tool deletes vaulted credentials for a specific service and npub, distinguishing it from siblings like delete_coupon or delete_journal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clear context: how to identify npub for operator vs patron, and highlights the requirement for proof of ownership. Does not explicitly exclude alternatives but 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 behavioral disclosure burden. It mentions the return format and that the FE uses it for cost calculations, but does not disclose caching, freshness, idempotency, or authorization requirements. It is somewhat transparent but 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 relatively concise, with a clear first sentence that states the tool's purpose. The JSON example adds specificity but could be considered verbose. Overall, it's well-structured and front-loaded.

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

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

The tool is simple read-only stats, and an output schema exists, so the description need not detail return values. However, it lacks information about data freshness, caching, or any side effects. It is adequate but not comprehensive.

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

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

Schema description coverage is 50% (one of two parameters described). The description adds no extra meaning beyond the schema; it does not mention or elaborate on the parameters. Given the moderate coverage, the description should have compensated but did not.

Input schemas describe structure but not intent. Descriptions should explain 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 returns aggregated token usage stats for the patron's Claude API calls, with a specific return format. However, it does not explicitly differentiate from sibling tools, though its unique name and purpose make it distinguishable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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, nor does it specify any prerequisites or exclusions. It only implies scope to the current patron's calls.

Agents often have multiple tools that could apply. Explicit usage 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 credit cost) and returns a simple boolean. Since no annotations are provided, the description adequately covers the read-only nature and lack of side effects, though it does not mention rate limits or authentication details.

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

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

The description is extremely concise: one sentence plus a short example. It front-loads the return type and provides the use case without fluff.

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

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

The description covers core functionality, return value, and use case, but it omits explanation of the dpop_token parameter. For a tool with two parameters, this gap reduces completeness despite the presence of an output schema.

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

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

The tool description does not explain the parameters; it only mentions them indirectly via the schema (npub has a description, dpop_token does not). With schema coverage at 50%, the description should compensate but does not add meaning beyond the schema.

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

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

The description clearly states that the tool returns {'escrowed': bool} to indicate whether Optionality holds the patron's nsec. It also distinguishes its purpose from siblings like optionality_escrow_nsec (deposit) and optionality_withdraw_nsec (withdrawal) by specifying it checks 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 mentions that the front end polls this tool to decide between Withdraw and Deposit affordances, giving a concrete use case. However, it does not explicitly state when to use this tool instead of its siblings or when not to use it.

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

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

The description implies a read operation via 'return', but with no annotations, it fails to disclose billing requirements (npub, dpop_token), data retention, or any side effects. The tool's input schema suggests authentication/credit billing, which is 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 (8 words) and front-loads the core action. However, it omits necessary context; each word earns its place but is insufficiently informative.

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

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

With an output schema (likely explaining return structure) and minimal parameters, the description lacks completeness on parameter semantics and usage context. It does not clarify the role of npub and dpop_token in billing.

Complex tools with many parameters or behaviors need more documentation. 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% (npub described). The description adds no parameter-level context; entry_id and dpop_token are unexplained. Given the low coverage, the description should compensate but does not.

Input schemas describe structure but not intent. Descriptions should explain 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 full journal entry with scenario and evaluation, specifying the resource and action. It distinguishes from sibling tools like list_journal (list vs. get) and delete_journal (delete vs. get).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (e.g., list_journal or delete_journal). There is no mention of prerequisites such as requiring an entry_id or billing 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 are provided, so the description must carry the burden. It only states 'Global leaderboard' without explaining any behavioral traits like caching, authentication requirements (though npub is in schema), or result ordering details. Minimal 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?

One sentence that is front-loaded and contains no extraneous information. Highly concise.

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

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

The tool has a moderate complexity with 5 parameters and an output schema, but the description is too minimal. It lacks details on what the leaderboard contains (scores, ranks, etc.), authentication, or default behavior. Incomplete for an agent to use effectively.

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

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

Schema description coverage is 80%, with most parameters having clear descriptions. The tool description adds no additional meaning beyond what the schema provides. 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 states it is a 'Global leaderboard ordered by sort_by', clearly indicating the tool retrieves a leaderboard with sorting. This is specific and distinguishes it from many sibling tools, though it could explicitly contrast with similar 'get' tools.

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

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

No guidance on when to use this tool vs alternatives, no prerequisites or context provided. The description does not help the agent decide between this and other leaderboard or ranking 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 must convey behavior; it correctly identifies the read operation and output (leaderboard row + rank). However, it omits details about authentication, side effects, or limitations. The description is adequate but not thorough.

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

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

The description is a single sentence, efficient and front-loaded with the key purpose. It is concise but could include more detail without becoming verbose.

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

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

Despite having an output schema, the description fails to address the three input parameters (especially npub and dpop_token) or how they affect behavior. It is incomplete for a tool with 3 parameters and 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 only 33% (only npub has a description). The description does not explain sort_by values or dpop_token, adding no additional parameter semantics. For low-coverage schemas, the description should compensate, but it does not.

Input schemas describe structure but not intent. Descriptions should explain 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 returns the caller's leaderboard row and ordinal rank under sort_by, which clearly differentiates it from sibling optionality_get_leaderboard that returns the full leaderboard. However, it could be more explicit about what fields the row contains.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 vs alternatives like optionality_get_leaderboard. There is no mention of prerequisites or context for 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?

No annotations are provided, so the description carries the full burden. It discloses that the operation is free and requires no proof, and states what fields are returned (name, display_name, about, picture, banner, nip05, website, lud16) and the fallback (empty profile). It does not mention error handling or rate limits, but for a simple read operation this 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 concise: two sentences that front-load the purpose. Every sentence adds value, with no wasted words. It is well-structured and easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (1 parameter, has output schema), the description covers the essential aspects: purpose, usage context, return fields, and what happens if no profile exists. It could optionally include error cases or rate limits, but it is largely complete for an agent to use correctly.

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

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

Schema description coverage is 0%, but there is a single parameter 'npub'. The description mentions 'npub' in the first sentence, so it adds meaning beyond the schema (which only gives type and default). However, it does not explain the format of npub (e.g., bech32) or behavior when the default empty string is used, so the compensation is partial.

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

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

The description clearly states 'Read an npub's public Nostr profile (NIP-01 kind-0 metadata).' It specifies the verb 'Read', the resource (npub's profile), and a technical standard (NIP-01). It is easily distinguishable from sibling tools like optionality_publish_nostr_profile (write) and optionality_get_patron_profile (different resource).

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

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

The description says 'Free, no proof — the data is already public on relays.' This tells the user that no authentication is needed and there is no cost, which is helpful. However, it does not explicitly state when not to use this tool versus alternatives, nor does it mention prerequisites or exclusions.

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

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

With no annotations, the description should disclose behavioral traits. It states 'generate' without indicating whether this is read-only, whether it requires authentication, or whether it has side effects. The generation is likely non-destructive, but this is not confirmed. The description adds limited transparency beyond the basic action.

Agents need to know what a tool does to the 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 that is front-loaded with the action and resource. It is concise and contains no unnecessary words, earning its place by communicating the core function 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 presence of an output schema covering return values, the description need not explain outputs. However, it lacks context about prerequisites (e.g., valid notarization_id, existing patron npub) and when to use this tool over siblings. It is minimally adequate but not fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add any additional meaning beyond the schema's parameter descriptions. It simply restates the tool's purpose without elaborating on the 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 action ('Generate a Merkle inclusion proof'), the specific resource ('a patron's balance'), and the context ('included in a Bitcoin-notarized snapshot'). This distinguishes it from sibling tools like optionality_list_notarizations or optionality_check_proof_status, which handle different aspects of notarizations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 a notarization exists and a patron wants a proof, but it does not explicitly state when to use this tool versus alternatives (e.g., check_proof_status for verifying an existing proof). No when-not or prerequisite information is provided, leaving the agent to infer context.

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

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

No annotations are provided. The description discloses that the tool reports configuration readiness and shows missing values, but does not mention behavioral traits such as whether it is read-only, rate limits, or side effects. Given the tool's simplicity (no parameters), the description is minimally adequate.

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

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

Three sentences: the first states the purpose, the second elaborates on what it shows, and the third provides a sibling reference. No redundant information, well 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 no input parameters and an output schema assumed to describe return values, the description sufficiently explains what the tool does and how it relates to a sibling. It could be improved by defining 'operator' in context, but it is adequate.

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

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

The tool has zero parameters, so the description does not need to explain any. Baseline for 0 parameters is 4, and the description meets that without adding unnecessary information.

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

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

The description clearly states the verb 'report' and resource 'operator configuration readiness'. It explicitly differentiates from the sibling 'get_patron_onboarding_status', making the tool's scope distinct.

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

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

Explicitly states when to use (check operator configuration readiness) and when not to (for patron-level status, use the sibling tool). Clear and actionable guidance.

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

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

With no annotations, the description discloses key behaviors: it only returns field names, never values; it is free; and it requires proof of npub ownership. It does not cover error states but adequately informs about the tool's limitations and auth requirements.

Agents need to know what a tool does to the 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, each serving a distinct purpose: purpose, return details and limitation, cost, and authentication rationale. No redundant or unnecessary text.

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

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

Given the presence of an output schema, the description adequately covers the tool's purpose, constraints, auth requirements, and sensitivity. No important aspect is missing for a list tool of this 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 input schema already describes both parameters (npub and dpop_token) with full coverage (100%). The description adds context about the sensitivity of the output but does not provide additional parameter-level details beyond the schema.

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

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

The description clearly states it lists stored patron credential field names (not values), specifying it is for verifying which fields are configured. This distinguishes it from sibling tools like optionality_update_patron_credential which modify credentials.

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

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

The description advises using the tool to verify configured fields, notes that values are never exposed, and explains the sensitivity requiring npub ownership proof. While it does not explicitly mention when not to use it or compare to alternatives, the context is clear.

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

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

With no annotations, the description fully discloses behavior: it is a read-only report, requires authentication (dpop token), explains sensitivity of credential presence, and notes it is free. No side effects are implied, and the presence of an output schema covers return values.

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

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

The description is well-structured with a front-loaded purpose sentence followed by four concise sentences that explain behaviors, categories, cost, and security. 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's nuance (two service types, auth requirement) and the presence of an output schema, the description covers all essential aspects: purpose, behavior for each case, prerequisites, cost, and sensitivity. It is complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context (why proof of ownership is required) but does not add new semantic details about parameter formats, constraints, or examples beyond what the schema already provides.

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

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

The description clearly states the tool reports a patron's credential readiness, specifies two categories (set-once vs dynamic/OAuth2) with explicit examples, and distinguishes from sibling tools (e.g., get_operator_onboarding_status, get_patron_credential_fields) by focusing on patron-level readiness.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: for checking credential readiness, with service-type distinctions. It mentions a prerequisite (proof of npub ownership) and cost (free). However, it does not explicitly compare with alternative tools 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?

Describes return fields but lacks disclosure of side effects, authentication needs, or rate limits; no annotations to compensate.

Agents need to know what a tool does to the 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 concise sentence with front-loaded verb, no filler words, effectively scoped.

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

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

Output schema exists so return values are covered, but parameter context is incomplete and no usage guidance; adequate but could improve.

Complex tools with many parameters or behaviors need more documentation. 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 npub parameter has schema description; dpop_token undocumented in both schema and description. Description adds no parameter semantics beyond schema.

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

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

Description clearly states it returns the caller's profile with specific fields (display_name, avatar, bio, relays), distinguishing it from sibling tools like 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?

Implies use for own profile but no explicit when-to-use vs alternatives like get_nostr_profile, and no preconditions or context.

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

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

With no annotations, the description must disclose behavioral traits. It reveals a side effect (self-initializes a scaffold if no model exists), cost (free), and what it does not include (economic data from code). This is informative beyond the typical getter, but does not address permissions or rate limits, which are not critical here.

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

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

The description is brief—two sentences—with the main purpose in the first sentence and a critical behavioral detail in the second. Every word adds value; no redundancy or fluff.

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

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

Given no parameters and an existing output schema, the description covers the essential behavioral aspects: purpose, self-initialization, cost, and exclusions. It does not detail the return format, but the output schema handles that. A minor gap is the lack of mention of idempotency or multiple calls, but overall complete for a simple read tool.

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

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

The input schema has no parameters, so the description adds no parameter-specific info. However, it provides context about cost and behavior, which is helpful. With 100% schema coverage and zero params, a baseline of 4 is appropriate.

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

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

The description states the verb 'Get' and the resource 'active pricing model', clearly differentiating it from siblings like 'set_pricing_model' and 'reset_pricing_model'. It also adds specific behavior (self-initializes if no model exists) and caveats (free, no economic data). This is a precise and distinguishable purpose.

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

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

The description provides context for usage ('free', 'no economic data from code') and implies a read-only action, but does not explicitly state when to use this tool versus alternatives like 'set_pricing_model' or 'reset_pricing_model'. For a simple getter, the usage is somewhat implied, but explicit guidance is missing.

Agents often have multiple tools that could apply. Explicit usage 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 traits: read-only nature ('free read'), eager-loading of evaluation and trade proposal, and no identity injection. This informs the agent about expected behavior without contradicting structural fields.

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

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

Description is concise (three sentences) with no redundant information. Each sentence adds unique value: purpose, access constraints, and behavioral details. Well-structured and front-loaded.

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

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

Given the low complexity (2 params), high schema coverage, and existence of output schema, the description is complete. It covers what the tool does, who can use it, how it behaves (eager-loads), and the required parameter. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. 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 already covers 100% of parameters with descriptions. The description adds ordering ('newest first') and contextualizes target_npub as 'target patron', but doesn't add significant new semantics for the parameters themselves.

Input schemas describe structure but not intent. Descriptions should explain 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 ('List'), resource ('target patron's shared evaluated entries'), and order ('newest first'). It distinguishes from sibling tools like optionality_share_entry (write) and optionality_get_leaderboard (different resource).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 that anyone (including guests) can use it ('Public, free read'), and that it's a bootstrap-style tool without identity injection. This tells the agent when to use it (no auth needed) and implicitly when not (if identity is required). Could be more explicit about 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?

The description discloses multiple behavioral traits: persistence, parsing, leaderboard recomputation, and the claim check pattern. Since no annotations are provided, the description fully carries the burden. It could mention authorization requirements (npub parameter) but it's not contradictory.

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

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

The description is two sentences plus a follow-up line about the return pattern. Every sentence adds value: first sentence states the action and side effects, second sentence explains the claim check and redemption. 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?

For a tool with async behavior and side effects, the description is adequate but leaves gaps. It mentions parsing legs but does not define 'legs.' It does not explain the structure of 'trade_proposal.' The presence of an output schema alleviates some burden for return values, but input semantics are under-specified.

Complex tools with many parameters or behaviors need more documentation. 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 25% (only 'npub' has a description). The tool description does not explain any parameters beyond the schema. It fails to clarify what 'trade_proposal' should contain or how 'entry_id' is used. With low schema coverage, the description should compensate but does not.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Evaluate the trainee's trade.' It also explains key actions: persists evaluation, parses legs, recomputes leaderboard. It distinguishes from sibling 'optionality_fetch_judgement' by noting that this tool returns a claim check, not the evaluation itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 tells when to use this tool vs the alternative: use this tool to submit a trade, then use 'optionality_fetch_judgement' to retrieve the actual evaluation. It also advises the polling workflow: 'polling until status is done.'

Agents often have multiple tools that could apply. Explicit usage 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. It explains that the tool returns data for all registered tools, that tool_id is stable while mcp_name changes on rename/rebrand, and explicitly states 'Free, no side effects.' This provides adequate transparency for a read-only listing 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 concise with 5 sentences, each adding meaningful content. The first sentence front-loads the primary action. Subsequent sentences elaborate on authority, use case, design rationale, and side-effect declaration. No redundant or unnecessary phrasing.

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

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

Given that the tool has no parameters, no annotations, but an output schema exists, the description sufficiently covers all aspects: purpose, output semantics, design intent, and safety. It explains the output fields and their relationship, making it complete for a list query tool.

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

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

The tool has zero parameters, so the description does not need to add parameter-level guidance. Baseline for 0 parameters is 4, as the description has no gaps in this dimension.

Input schemas describe structure but not intent. Descriptions should explain 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 begins with a clear statement: 'Return canonical (tool_id, mcp_name, …) for every registered tool.' It specifies the exact output fields and the overall purpose, which is to list identity mappings. The tool name 'list_canonical_identities' matches the action, and it is distinct from siblings as no other tool has a similar purpose.

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

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

The description explicitly states that this is 'the authoritative source for any client... that needs to know how this MCP identifies its tools.' It provides a concrete use case: 'Reconcile uses this output to UUID-join against the stored pricing model.' It also warns against alternative approaches: 'no name-based UUID derivation, no guessing.' This gives clear when-to-use and when-not-to-use guidance.

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

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

No annotations are provided, so the description must convey behavioral traits. It states the tool is free, which is helpful, but it does not explicitly declare that it is read-only, non-destructive, or safe to call repeatedly. For a simple listing tool, this is adequate but not comprehensive.

Agents need to know what a tool does to the 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 two short sentences, front-loading the core purpose. Every sentence provides useful information without any fluff or redundancy.

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

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

The tool has no parameters and an output schema exists (not shown but indicated). The description sufficiently covers what the tool does and what it returns. Given the tool's simplicity, the description is complete and provides all necessary context for an agent to use it correctly.

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

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

The input schema has no parameters, so the baseline is 4. The description adds value by detailing what the tool returns (type, category, description, parameter specs), which is not in the schema. Since there are no parameters, the description fully meets the need.

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

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

The description explicitly states the tool lists all available constraint types and their parameter schemas, including the specific fields returned (type, category, description, parameter specs). The name is also descriptive and distinguishes it from sibling listing tools like optionality_list_coupons or optionality_list_journal.

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

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

The description mentions the tool is free (no credits required), which implies it can be used freely for exploration. However, it does not provide explicit guidance on when to use it versus alternatives, nor does it state prerequisites or exclusions. The usage context is implied but not fully articulated.

Agents often have multiple tools that could apply. Explicit usage 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 convey all behavioral traits. It states ordering ('newest first'), data content (times_redeemed, total_uses), and access restriction (operator only with proof). It does not mention whether the operation is read-only, rate limits, or if pagination exists.

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

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

The description is three concise sentences, front-loaded with the core purpose. Each sentence adds value without redundancy.

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

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

Given the output schema exists, the description provides useful detail about the response (times_redeemed counter, progress bar). However, it omits pagination details and does not cover the dpop_token parameter. For a listing tool, this is mostly adequate.

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

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

The input schema has one parameter (dpop_token) with 0% coverage—no description in schema. The tool description does not explain dpop_token at all, leaving the agent without guidance on its purpose or usage.

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

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

The description clearly states 'List every coupon this operator has minted (newest first)', specifying the verb (list), resource (coupons), and scope (operator's minted). However, it does not distinguish from the sibling tool 'optionality_list_my_coupons', which likely serves a similar purpose.

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

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

The description indicates the tool is 'RESTRICTED to operator — requires proof', implying usage context. However, no explicit guidance is given on when to use this tool versus alternatives like 'optionality_list_my_coupons' or other listing tools.

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

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

No annotations provided, but the description discloses that sorting/grouping are SQL-based and that each page is a slice of the fully-ordered dataset. It also specifies the return structure, giving adequate behavioral insight for a read operation.

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

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

Three concise, front-loaded sentences with no redundant information. Each sentence adds value: first states the purpose, second explains the SQL behavior, third describes the return 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 output schema exists, the description adequately covers the core functionality and return structure. It mentions 'caller's journal' implying authorization context. Lacks error cases but overall sufficient for a relatively simple 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?

Schema coverage is high (89%), and the description does not add detail beyond the schema for individual parameters. The baseline of 3 is appropriate since the schema itself provides most parameter meaning, and the description adds no new parameter-specific insights.

Input schemas describe structure but not intent. Descriptions should explain 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 'Server-side sorted, grouped, paginated list of the caller's journal', specifying the verb (list), resource (journal), and key features (sorting, grouping, pagination). It distinguishes from sibling tools like get_journal and delete_journal.

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

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

The description implies use for listing journal entries with sorting/grouping, but lacks explicit when-to-use or when-not-to-use guidance compared to alternatives. No mention of when to prefer other list tools.

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

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

With no annotations, the description carries full burden. It discloses that the operation is free, requires npub proof, and returns both active and exhausted redemptions with enumerated statuses. This is fairly transparent for a read-only listing, though it could mention potential pagination 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 two sentences: the first directly states the main function, and the second adds key details about output and constraints. Every sentence earns its place with no redundancy.

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

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

Given the tool's simplicity and the presence of an output schema, the description is adequate but incomplete. It covers scope, statuses, cost, and auth, but omits explanation of the dpop_token parameter, which could affect usability.

Complex tools with many parameters or behaviors need more documentation. 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 links npub to 'proof of npub', adding meaning. However, the optional dpop_token parameter is not explained at all, leaving a gap in understanding its purpose.

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

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

The description clearly states the verb 'List' and the resource 'coupons this patron has redeemed', distinguishing from sibling 'optionality_list_coupons' which likely lists all coupons. It also explains the output includes statuses, making the purpose 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 mentions that the tool is 'Free' and 'requires proof of npub', giving some context. However, it does not explicitly state when to use this tool compared to alternatives like optionality_list_coupons, nor does it provide exclusions or prerequisites beyond npub.

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

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

With no annotations, the description must disclose behavior. It states 'list recent' but doesn't define 'recent' (time window?) or ordering. No mention of pagination semantics or authentication needs. Adequate for a simple read operation.

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

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

A single sentence with no filler. Every word adds value. No redundant or vague phrasing.

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

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

The tool has no required parameters and an output schema (not shown). The description is minimal but covers the core purpose. Missing details about pagination, default sorting, or status filter behavior, but acceptable for a simple 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?

Schema coverage is 100%, so the parameters ('limit', 'status') are already documented. The description adds no new semantic meaning beyond the schema, meeting the baseline but not exceeding it.

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

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

The description uses a specific verb ('List') and resource ('Bitcoin notarization records'), clearly distinguishing it from sibling tools like 'list_coupons' or 'list_canonical_identities'. The qualifier 'recent' adds scope.

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

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

No guidance on when to use this tool versus alternatives (e.g., 'get_notarization_proof' for a single record). No conditions, prerequisites, or exclusions mentioned.

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

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

No annotations exist, so the description must carry the full burden. It fails to disclose whether the operation is idempotent, destructive, or requires permissions, and does not mention uniqueness constraints or side effects.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It is concise, though it could benefit from slightly more detail.

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

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

Given the 7 parameters and output schema, the description lacks critical context such as uniqueness of the name, effects on the operator's account, and the meaning of 'operator-owned'.

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

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

With 86% schema description coverage, the schema already explains most parameters. The tool description adds no additional parameter semantics, 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 specifies the verb 'Create' and the resource 'operator-owned discount coupon', clearly distinguishing this tool from siblings like update, delete, or redeem coupon tools.

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

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

No guidance is provided on when to use this tool versus alternatives such as optionality_update_coupon or optionality_redeem_coupon.

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

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

With no annotations provided, the description carries the full burden. It discloses the tool is a background task, the time-to-confirmation window, and that it's free. It clearly indicates a side effect (submitting to Bitcoin). This is sufficient, though it could mention that the operation is irreversible or may fail.

Agents need to know what a tool does to the 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 highly concise: two sentences covering the core action, user restrictions, timing, and cost. Every sentence adds value with no redundancy.

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

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

Given the tool's complexity (Merkle tree + Bitcoin submission), the description provides essential context: it's operator-only, takes hours, and is free. The presence of an output schema means return values don't need to be described. It could elaborate on what happens after submission, but it's 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 tool has zero parameters and 100% schema coverage trivially. The description adds no parameter information because none is needed. 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 action: 'Build a Merkle tree of all patron balances and submit the root to Bitcoin via OpenTimestamps.' This specific verb+resource combination distinguishes it from sibling tools like optionality_get_notarization_proof, which is about retrieving proof, not initiating notarization.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 it is an 'Operator-only background task' and that 'Bitcoin confirmation takes 1-6 hours,' guiding the agent on who can use it and the expected latency. However, it does not explicitly mention alternatives, such as using optionality_get_notarization_proof to check status after submission.

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

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

No annotations provided, and the description only adds 'Free' which is minimal behavioral context. It does not disclose whether the tool is read-only, requires authentication, or any other traits.

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

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

The description is very concise at two short phrases. It is front-loaded with the key action and resource. The word 'Free' earns its place by providing a cost hint.

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

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

With no parameters and an output schema assumed present, the description is minimally adequate. However, it lacks details on what 'describe' entails and could be more informative for a tool that likely provides a broad overview.

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

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

No parameters exist, so schema coverage is trivially 100%. The description does not need to add parameter meaning; baseline for zero-parameter tools 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 uses a specific verb 'describe' and identifies the resource 'DPYC ecosystem via the Oracle'. It is clear and distinct from siblings like 'optionality_oracle_how_to_join' 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. The word 'Free' hints at no cost but doesn't provide context for selection among many oracle 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 must disclose behavioral traits. It only mentions 'Free', but fails to describe what the tool returns, potential caching, rate limits, or any side effects. The return value is undocumented beyond the inferred tax rate.

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

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

The description is a single sentence with no redundant words. It is concise and front-loaded with the core purpose.

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

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

Given the simplicity (no parameters, existence of an output schema), the description is minimally adequate but lacks context such as whether the tax rate is a percentage or flat fee, or the currency. The 'Free' tag is helpful but insufficient for full completeness.

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

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

The tool has zero parameters, so the input schema documentation is already complete. Per guidelines, the baseline is 4 for no parameters, and the description adds no relevant parameter info.

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

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

The description clearly states the verb 'Get' and the specific resource 'the current DPYC certification tax rate'. It is unambiguous and distinguishes itself from sibling tools, as no other tool targets tax rates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 additional information is 'Free', which hints at cost but does not inform decision-making relative to other tools.

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

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

No annotations are provided, and the description only says 'Free.' It lacks disclosure of any behavioral traits such as idempotency, rate limits, or side effects beyond the bare 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 (8 words) and front-loaded. Every word earns its place.

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

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

Given zero parameters and an existing output schema, the description is adequate: it states what the tool returns and that it's free. A slight improvement could mention prerequisites or context, but it's not necessary.

Complex tools with many parameters or behaviors need more documentation. 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, so schema coverage is 100%, and the baseline is 4. The description adds no extra semantic value but doesn't need to.

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

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

The description uses specific verb+resource ('Get DPYC onboarding instructions from the Oracle'), clearly distinguishing from sibling tools like optionality_get_operator_onboarding_status or optionality_oracle_about.

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

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

No explicit when-to-use or alternatives are mentioned. The phrase 'Free.' hints at no cost but provides no guidance on when to choose this over other oracle tools.

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

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

No annotations provided, so description carries full burden. Only 'Free' is mentioned, which is not behavioral. No disclosure of read-only nature, authentication needs, or limitations. Output schema exists but description adds no behavioral context.

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

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

Very short at 6 words, which is concise but too terse. Lacks structure like prerequisites or examples. Earns its place for brevity but sacrifices informativeness.

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

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

Output schema exists, so return values need not be explained. However, description lacks context on what a DPYC community member is, how npub is used, or any error handling. Minimal but functional for a simple lookup.

Complex tools with many parameters or behaviors need more documentation. 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 compensate. Only states 'by npub' without explaining what npub is (e.g., format, meaning). Parameter meaning is nearly absent.

Input schemas describe structure but not intent. Descriptions should explain 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 looks up a 'DPYC community member' by npub, using a specific verb and resource. It distinguishes from sibling tools like optionality_get_nostr_profile or optionality_get_patron_profile by specifying the community, though it doesn't define 'DPYC'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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_nostr_profile or optionality_oracle_about. 'Free' hints at cost but does not clarify usage context or exclusions.

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

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

With no annotations provided, the description bears full responsibility for behavioral disclosure. It only mentions 'Free' but omits any details about side effects, authentication requirements, rate limits, or data freshness. This is insufficient for a tool that returns network advisories.

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

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

Comprising just two short sentences, the description is concise and to the point. However, it could be more informative without sacrificing brevity, such as hinting at the advisory content or update frequency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, the description is minimally adequate. However, it lacks context about the nature of the advisories (e.g., types, how often they update) that would help an agent use the output effectively.

Complex tools with many parameters or behaviors need more documentation. 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 does not need to explain parameter behavior, and the baseline score is 4. The addition of 'Free' is minor but acceptable.

Input schemas describe structure but not intent. Descriptions should explain 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 'Get' and identifies the resource as 'active network advisories from the Oracle'. It clearly distinguishes the tool's purpose from its many siblings, which all have different functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 simply states what it does without any context about appropriate usage scenarios or exclusions.

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

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

Even with no annotations, the description fully discloses behavioral traits: the wheel never holds the nsec, it verifies the signature, relays to public relays, and that the signature serves as authorization. It also mentions it's free and has no key custody, providing complete transparency for a mutation tool.

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

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

The description is very concise (four sentences) and front-loads the core purpose. Every sentence adds value: purpose, security model, process, and cost. No filler 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 (not shown but signaled) and the thorough explanation of the publishing flow, the description is complete. It covers what the tool does, how it interacts with the client, and the security guarantees. No important aspects are missing.

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

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

Both parameters are described in the schema with meaningful descriptions. The tool description doesn't add significant new meaning beyond what the schema already provides. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool publishes a client-signed kind-0 profile to relays for a given npub. It distinguishes itself from sibling tools like optionality_get_nostr_profile by focusing on publishing rather than reading. The specific verb 'publish' and resource 'kind-0 profile' provide a precise purpose.

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

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

The description explains the workflow: the client signs the event and passes it here. It implies that this tool is used after client-side signing. However, it does not explicitly state when not to use it or mention alternatives like the read tool for profiles. Still, the context is clear enough for correct 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?

Without annotations, the description fully discloses behavior: creates a Lightning invoice, requires proof of npub ownership, is free to call, and expects follow-up with check_payment. This is transparent and actionable.

Agents need to know what a tool does to the 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 (7 sentences), logically structured: purpose first, then process and requirements. It's efficient yet informative.

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

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

Given output schema exists, return values need not be explained. The description covers the complete user flow, prerequisites, and next steps. It's sufficiently complete for a purchase tool.

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

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

Schema coverage is 100%, and the description adds no extra parameter details beyond schema. It reinforces the npub and dpop_token roles but doesn't clarify defaults or constraints. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Buy credits via Bitcoin Lightning.' It explains the flow: invoice creation, payment, and confirmation. While it doesn't explicitly differentiate from siblings like check_payment, the unique action of purchasing is well-defined.

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

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

The description provides usage context: when to buy credits, prerequisite of npub proof, and the need to call check_payment. It mentions no cost to invoke. However, it lacks explicit guidance on when not to use the tool or 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 fully discloses the tool's behavior: it drains only the pinned relay, deletes wrong DMs, NACKs mismatched session phrases, ACKs the first match, returns 'courier_not_found' on no match, and explains the alternative credential_card path that bypasses relay access.

Agents need to know what a tool does to the 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 paragraphs and front-loaded with the main action. It is informative without being overly verbose, though slightly longer than necessary.

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

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

Given the existence of an output schema (not shown but indicated), the description adequately covers when to call, behavior, error cases, and alternative paths. It is complete for the tool's complexity.

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

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

The input schema has 100% coverage, but the description adds value by explaining the role of each parameter in the broader flow, such as the credential_card bypassing relay and dpop_token not being needed for that path. This goes beyond the basic schema descriptions.

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

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

The description clearly states the tool's purpose: 'Pick up credentials from the Secure Courier.' It identifies the specific flow (CREDENTIAL-DELIVERY) and distinguishes itself from the sibling tool 'receive_npub_proof' by naming it as the ownership-proof counterpart.

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

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

Explicitly states when to call: 'Call this only after the user confirms they have replied.' It also provides behavioral constraints such as 'Do NOT poll, loop, or retry' and explains the one-shot retrieval mechanism.

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

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

No annotations exist, so the description fully handles behavioral disclosure. It details that the tool drains only the pinned relay, stops at matching DM, deletes mismatched DMs without revealing expected phrase, and that the proof is stored as a hash. The token handling and safety measures are 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 well-structured with clear sections and bullet points, front-loading the purpose. Despite its length, every sentence adds value—no superfluous text. It prioritizes critical constraints and usage notes 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 complexity of the proof flow and the presence of an output schema, the description provides sufficient context: it explains the trigger condition, the one-shot retrieval, the token storage, and the return value (dpop_token). No gaps remain for an agent to misuse.

Complex tools with many parameters or behaviors need more documentation. 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 each parameter described. The description reinforces that dpop_token is the value from request_npub_proof and explains its role in the proof flow, adding context beyond the schema's basic description. This warrants a score above baseline.

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

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

The description clearly states the tool's purpose: 'Receive npub ownership confirmation from a patron.' It specifies the action and ties it to the larger flow, distinguishing it from the counterpart receive_credentials. The verb 'receive' and the resource 'npub proof' are precise.

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

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

Explicit usage instructions are provided: 'Call this only after the user confirms they have replied.' It also advises against polling or retrying: 'Do NOT poll, loop, or retry.' Clear context for when to call and when not to.

Agents often have multiple tools that could apply. Explicit usage 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 fully discloses behavior: validates window/cap, records redemption, auto-applies discount on future calls, free, idempotent, and requires proof of npub. 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, with a clear opening sentence and subsequent details. No redundant information; each sentence adds value.

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

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

Given the tool's complexity (3 params, no annotations, output schema exists), the description covers purpose, behavior, preconditions, and effects adequately. No obvious gaps.

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

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

The description adds meaning for 'code' (the coupon name) and 'npub' (proof required). The optional 'dpop_token' is not explained, but with 0% schema coverage, the description compensates well for two key 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 this tool claims a coupon by its code, with specific details on validation, redemption, and discount application. It distinguishes itself from siblings like optionality_mint_coupon or optionality_delete_coupon by focusing on redemption.

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

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

The description gives clear context: use when you have a coupon code to claim, requires npub, idempotent, free. However, it does not explicitly exclude other tools or mention 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 fully discloses behavioral traits: operator restriction, proof requirement, inline mintage, MCP-to-MCP delivery, pending status, and eventual ready state. It provides comprehensive context beyond what annotations would cover.

Agents need to know what a tool does to the 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 the main action upfront. It is slightly verbose but each sentence adds value, explaining restrictions, process, and outcome. Could be more concise but remains effective.

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

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

Given the complexity (4 parameters, output schema exists) and the comprehensive coverage of purpose, usage, behavioral traits, and parameter context, the description is complete. It does not need to explain return values due to output schema presence.

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

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

Schema description coverage is 100%, so the description adds limited per-parameter semantics. It gives overall context (e.g., proof requirement, endpoint) but does not elaborate on each parameter individually. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states the action ('Ask a chosen Authority to adopt this operator') and the resource (adoption by Authority). It distinguishes from siblings like 'optionality_adoption_status' by specifying this is the request initiation, not status polling.

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

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

The description implies usage context: it is for initiating adoption, restricted to the operator, and suggests polling 'adoption_status' for progress. It provides clear context but lacks explicit when-to-use vs. alternatives, though the specificity compensates.

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

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

No annotations provided, but description fully discloses behavior: sends a welcome DM, human-in-the-loop flow, requires waiting for user confirmation, warns against polling/retrying, and notes that receive_credentials destructively drains mailbox.

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

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

Appropriately sized with front-loaded purpose. Each sentence adds value, though could be slightly tightened. Structure is logical 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?

Covers the human-in-the-loop async nature, required user intervention, and destructive receive behavior. Output schema exists so no need to describe return values.

Complex tools with many parameters or behaviors need more documentation. 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 100%, so baseline 3. Description mentions service and sender_npub but adds little beyond schema; it implies service comes from onboarding status tools but no further detail.

Input schemas describe structure but not intent. Descriptions should explain 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 opens a secure courier channel for credential delivery (API keys, tokens). Distinguishes from request_npub_proof and notes when not to use (dynamic/OAuth2 services).

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

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

Explicitly says when to use (credential delivery), when not to (OAuth2, proof of npub), and names alternative tool (request_npub_proof). Also advises checking service_status first.

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

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

No annotations provided, so description carries full burden. Discloses human-in-the-loop, challenge DM, non-delivery of secrets, destructive drain of relay mailbox by receive_npub_proof, return of dpop_token that must be remembered, and that the MCP does not persist the token across restarts. Also mentions expiry and lifecycle.

Agents need to know what a tool does to the 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 sections and formatting (bold, blockquotes). Information is front-loaded. However, there is some redundancy (e.g., 'This is the npub-OWNERSHIP-PROOF flow' and later 'it does NOT deliver any service secret' could be merged). Still, overall efficient and easy to parse.

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

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

Explanation covers purpose, when to use, return value (dpop_token), lifecycle expiry, and link to sibling receive_npub_proof. Output schema exists but description supplements with important usage details. No gaps identified 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?

Only one parameter (patron_npub) with schema already providing name, type, default, and description. The description adds minimal new semantic value—only that it is 'the patron's npub to request proof from.' Since schema description coverage is 100%, baseline is 3; description does not substantially improve 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?

Clearly states it requests npub ownership proof via Nostr DM. Distinguished from sibling tool request_credential_channel by noting that this proves control of npub and does not deliver service secrets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 to use when a call returns 'proof_required'. Contrasts with request_credential_channel. Provides step-by-step flow: call, tell user, wait for confirmation, then call receive_npub_proof. Instructs not to poll/retry. Describes lifecycle with expiry and re-invocation.

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