schwab-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 is free (no credits consumed), requires proof of npub ownership to prevent scraping, and returns specific data types. It does not mention rate limits or error handling, but provides sufficient behavioral context for safe use.

Agents need to know what a tool does to the 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 the primary purpose. Each sentence adds unique value: purpose, content, clarification, cost/auth. No 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?

Given the output schema exists and the tool has moderate complexity (3 params), the description covers the essential aspects: what is returned, authentication requirement, and cost. Could mention the time scope (e.g., statement period) or that it's per-operator, but overall sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds some context (e.g., proof requirement for dpop_token) but does not significantly enhance parameter meaning beyond schema definitions. The description's mention of 'proof of npub ownership' reinforces the dpop_token's 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?

Clearly states 'Generate a patron's account statement' and lists all returned components (purchase history, credit tranches, usage breakdown, daily logs). Distinguishes from sibling 'schwab_account_statement_infographic' by specifying textual/log output, and explicitly differentiates from operator's Authority tax balance.

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

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

No explicit when-to-use or when-not-to-use guidance compared to siblings. Does mention it's for the patron's spending account (not operator's tax) and requires npub proof, but does not advise when to choose this over 'schwab_account_statement_infographic' or other account 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 provided, the description fully covers behavioral traits: it generates an SVG, costs 1 api_sat, and has proof verification before cost. It also lists visual components, providing good transparency beyond the schema.

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

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

The description is extremely concise (two sentences) with no wasted words. It front-loads the main purpose and then adds key details about output, cost, and verification in an efficient manner.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 and the description links to the sibling account_statement tool, it provides sufficient context. It covers what the tool returns (components), cost, and verification. Minor gaps in error handling are offset by the explicit connection to related tools.

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

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

Schema coverage is 100% and the schema already describes each parameter adequately. The description adds no additional parameter meaning, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a visual SVG infographic of an account statement. It specifies the output format and distinguishes from the sibling 'account_statement' by noting it returns the same data rendered as a dark-themed SVG with specific components.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 for visual infographics versus raw data from account_statement, but does not explicitly state when to use this tool versus alternatives. It mentions cost and proof verification, but no clear guidance on selection criteria.

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

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

Discloses it's free, polls Authority, and lists possible statuses. No annotations exist, so description must carry full burden; lacks details on authentication, rate limits, or error behavior.

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

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

Concise two sentences with front-loaded purpose. Could include structured parameter info, but 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?

Output schema exists, so return values are covered, but description lacks parameter semantics and prerequisites. For a 2-param tool with 0% schema coverage, more context is needed for reliable invocation.

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

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

No parameter descriptions in schema (0% coverage) and description provides no explanation for 'dpop_token' or 'authority_npub'. Agent cannot infer parameter purpose from description 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?

Description clearly states verb ('Check') and resource ('adoption-request status'), and distinguishes from siblings by focusing on status checking. No sibling tool has 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?

Implied usage for checking adoption status, but no explicit when-to-use or alternatives. Related tool 'schwab_request_adoption' exists but no guidance on selecting.

Agents often have multiple tools that could apply. Explicit usage 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 covers behavioral traits: it initiates the OAuth flow, requires proof of npub ownership, mentions DOS prevention, and explains the dpop_token constraints. It transparently describes the return value and required subsequent step.

Agents need to know what a tool does to the 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 the main action front-loaded. While it is detailed, every sentence adds necessary context, making it appropriately concise for the complexity.

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

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

Given the OAuth flow complexity, the presence of sibling tools, and the absence of output schema, the description is complete. It explains when to use, prerequisites, return value, and the next step (check_oauth_status). Also addresses security (DOS prevention).

Complex tools with many parameters or behaviors need more documentation. 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 significant meaning beyond the schema, especially for dpop_token detailing format, constraints, and use of 'u' tag. For npub, it adds usage context ('Your DPYC patron npub').

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

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

The description clearly states the tool starts the OAuth2 authorization flow and returns an authorization URL. It distinguishes from sibling tool 'check_oauth_status' by specifying it as the completion step.

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

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

Explicitly instructs not to call pre-emptively and to first attempt a live tool call, only initiating OAuth when 'upstream_auth_refresh_needed' occurs. Also directs to call 'check_oauth_status' to complete the flow.

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

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

With no annotations, the description discloses that it is a read-only check (returns balance), that it affects patron top-up certification, and that it is free. It does not mention rate limits or error behavior, but for a simple read operation, this provides adequate transparency.

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

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

The description is four concise sentences, front-loaded with the primary purpose, followed by consequences and a clarification. Every sentence adds value without redundancy.

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

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

Given the tool has no parameters and an output schema, the description explains the return value (sats), the business logic (balance affecting certification), and the follow-up action (purchase_credits). No gaps are apparent.

Complex tools with many parameters or behaviors need more documentation. 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 the schema coverage is 100% vacuously. Baseline for 0 parameters is 4, and no additional parameter details are needed.

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

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

The description clearly states it checks the operator's tax balance at the Authority, specifically the sats available for certifying patron credit purchases. It distinguishes from sibling tools like schwab_check_balance (patron balance) and schwab_check_oauth_status by specifying it's the operator's own funding.

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

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

The description explains when to check this balance (when certifying purchases) and what to do when it reaches zero (call purchase_credits). However, it does not explicitly compare to alternatives like schwab_check_balance for patron balances, leaving some ambiguity.

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

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

No annotations provided, so description carries full burden. It discloses that the operation is free (no credits required) and requires proof of npub ownership to prevent enumeration. Does not describe error handling or rate limits, but for a simple read operation this is adequate.

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

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

Three concise sentences: states purpose, distinguishes alternative, and notes key requirements. No filler; every sentence adds value. Front-loaded with primary purpose.

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

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

Output schema exists, so return values are covered. Description covers purpose, auth requirement, cost, and alternative. For a balance-checking tool, this is comprehensive and leaves 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?

Schema coverage is 100%, but description adds significant value beyond schema: explains dpop_token format in detail (raw JSON, not base64, specific kind, tag requirements, expiration, nonce recommendation). This clarifies usage beyond the schema's description.

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

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

Description explicitly states the tool checks a patron's credit balance, with specific verb ('check') and resource ('balance'). It distinguishes from sibling 'authority_check_balance' by clarifying scope (patron vs operator balance). No ambiguity.

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

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

Explicitly states when to use (check patron spending balance) and when not to (for operator's own balance, use authority_check_balance). Also highlights that it's free and requires proof of npub ownership, setting context for usage constraints.

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

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

With no annotations, the description carries the full burden. It discloses that the tool is free, requires proof of npub ownership, and that OAuth status exposes connected upstream services. It also clarifies that a 'pending' result only reports this authorization attempt, not session validity. The description is transparent about these behavioral traits, though it could mention side effects or rate limits if any.

Agents need to know what a tool does to the 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, consisting of three short paragraphs. The first sentence is front-loaded with the tool's purpose. Every sentence adds value, and there is no redundant or irrelevant information.

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

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

Given the tool's simplicity (checking OAuth status), the description covers the key aspects: when to call, required proof, result interpretation, and handling of 'pending'. An output schema exists to describe return values, so the description is complete 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?

The input schema has 100% coverage with descriptions for both parameters. The description adds context by stating that the npub should be the same as used in begin_oauth, which is already implied in the schema. No additional parameter meaning beyond the schema is provided, placing it at the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Check whether the OAuth2 authorization flow has completed.' It uses a specific verb ('check') and resource ('OAuth2 authorization flow'), and it distinguishes itself from siblings like schwab_begin_oauth by advising when to call it and how to interpret results.

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

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

Explicit usage guidance is provided: 'Call after opening the authorization URL from begin_oauth and completing the login in your browser.' It also warns against misinterpreting 'pending' and provides fallback instructions ('attempt the live call; fall back to begin_oauth only on an explicit upstream_auth_refresh_needed error').

Agents often have multiple tools that could apply. Explicit usage 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 call is free, no credits required, and requires proof of npub ownership to prevent front-running. This provides useful behavioral context beyond a simple 'check status' description.

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

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

The description is concise with no redundant sentences. Every line provides essential information: action, sequence, cost, and security 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 an output schema exists, the description provides adequate context: the sequence (post-purchase), the security requirement, and cost. It explains the dpop_token parameter in detail. The tool is simple enough that no further explanation is needed.

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

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

Schema coverage is 100%, but the description adds value by explaining the invoice_id comes from purchase_credits and that npub links the purchase. This supplements the schema's own 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 states 'Check the payment status of a Lightning invoice' which is a specific verb+resource combination. It also mentions this is called after paying from purchase_credits, distinguishing it from sibling tools like schwab_purchase_credits.

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

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

Explicitly says 'Call after paying the invoice from purchase_credits' and mentions prerequisites (npub proof). However, it does not explicitly name alternative tools for related tasks.

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

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

No annotations are provided, so the description must bear the full burden of behavioral disclosure. It states the tool is 'free' and shows costs, but does not mention whether it is read-only, requires authentication, or has any side effects. This is insufficient for a tool that previews pricing.

Agents need to know what a tool does to the 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 that front-load the purpose and add relevant details (base cost, constraint effects, free-of-charge). Every sentence earns its place with 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?

While an output schema is present (so return values are covered), the description lacks context on how to specify the tool call (e.g., via tool_id) or any prerequisites. It is minimally viable but leaves gaps for a user unfamiliar with the system.

Complex tools with many parameters or behaviors need more documentation. 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%, but the tool description adds no extra meaning beyond the schema. It does not explain how parameters like tool_id or tool_kwargs are used in the context of cost preview. The description fails to compensate for the missing parameter documentation.

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

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

The description clearly states the tool's purpose: 'Preview the effective cost of a tool call.' It specifies the verb (preview), resource (cost of a tool call), and adds distinguishing details about base cost and constraint effects. Among many schwab tools, this stands out as the pricing preview tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 for checking cost before a tool call but does not explicitly state when to use it over alternatives (e.g., schwab_check_balance, schwab_check_payment). No exclusions or comparative guidance provided.

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

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

With no annotations provided, the description fully discloses behavior: it is free, has no side effects, does not evict the cache, and does not touch relays. This is thorough and accurate.

Agents need to know what a tool does to the 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 core purpose, and every sentence adds value. No redundancy or unnecessary detail.

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

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

Given the presence of an output schema (for return values), the description sufficiently covers purpose, behavior, and usage. It is complete for a check-status tool with two well-documented parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description provides context (e.g., 'previously-cached dpop_token') but does not add significant meaning beyond the parameter descriptions already in the schema.

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

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

The description clearly states it checks whether a previously-cached dpop_token is valid, with a specific verb ('check') and resource ('proof status'). It explicitly distinguishes itself from the sibling 'schwab_check_oauth_status' by noting it mirrors that tool 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?

The description gives explicit context: agents can use this before a paid call to avoid wasting credits on a guaranteed failure. It also names the alternative (check_oauth_status) and states it has no side effects, guiding appropriate use.

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

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

With no annotations provided, the description fully bears the burden. It discloses key behaviors: cascading deletion to redemptions, chain steps becoming no-ops, and orphan reference warnings in the Studio. It also notes the operator restriction. This is strong, though it does not mention reversibility or recovery paths.

Agents need to know what a tool does to the 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 only three sentences. The most important information ('Delete a coupon') is front-loaded. Every sentence adds value, and there is 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 tool's complexity (deletion with side effects) and the presence of an output schema, the description covers the main behavioral effects and restrictions. However, the lack of parameter explanations and usage guidance makes it incomplete for optimal selection and invocation.

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

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

The input schema has 0% description coverage, and the description does not explain the parameters at all. 'coupon_id' and 'dpop_token' are not mentioned, leaving the agent to infer meaning solely from names. This is a critical 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 'Delete a coupon' which is a specific verb and resource. It adds that cascading to all patron redemptions occurs, giving scope. However, it does not differentiate from the sibling tool 'schwab_forget_coupon', leaving potential confusion.

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

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

The description provides a usage restriction ('RESTRICTED to operator — requires proof') but no guidance on when to use this tool versus alternatives like 'schwab_forget_coupon' or 'schwab_update_coupon'. No when-not-to-use or context 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?

With no annotations provided, the description carries full burden. It discloses that it deletes one field without affecting others, is free, requires ownership proof, and is a write to sensitive vault. It does not mention error handling or irreversibility, but overall provides good transparency.

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

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

The description is three short sentences, front-loaded with the action, 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 an output schema, return values are covered elsewhere. The description explains the action and key constraints. It could mention idempotency or error behavior, but overall feels adequately complete for a deletion 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?

All three parameters are fully described in the schema (100% coverage). The description adds context about ownership proof but does not elaborate on parameter details beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Remove a single patron credential field', specifying a specific verb and resource. It distinguishes itself from sibling tools like schwab_update_patron_credential or schwab_forget_credentials by focusing on deletion of one field.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 proof of npub ownership is required and that it is a write to the credential vault, implying security context. However, it does not explicitly state when to use this tool versus alternatives like schwab_forget_credentials or schwab_update_patron_credential, leaving usage guidance implicit.

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

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

With no annotations, the description fully discloses key behaviors: the action is cosmetic only, non-destructive (coupon still exists at operator, re-redeemable), and free. This provides clear expectations beyond the input schema.

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

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

Two concise sentences: first states the action, second adds essential context (cosmetic, free, requirement). No waste; front-loaded with 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?

For a simple removal action, the description covers effect and constraints. The output schema exists (not shown) and likely specifies return values, so completeness is high. Minor gap: doesn't explicitly state that the coupon disappears from the list immediately.

Complex tools with many parameters or behaviors need more documentation. 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 3 parameters with 0% coverage. The description explains 'npub' (proof required) and implies 'coupon_id' (the coupon to remove), but does not mention 'dpop_token'. While it adds some meaning, it leaves one parameter unexplained, resulting in moderate compensation.

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

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

The description clearly states 'Remove a coupon from this patron's redemption list,' which is a specific verb and resource. It also adds 'cosmetic only' to distinguish from permanent deletion, helping differentiate from sibling tools like 'delete_coupon' and 'redeem_coupon'.

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

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

Explicitly states when to use ('remove from redemption list'), what happens instead ('cosmetic only'), and alternatives implied (permanent deletion via sibling tools). Also notes prerequisites: 'requires proof of npub' and that it's free, guiding agent on conditions.

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

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

With no annotations, the description takes full burden. It discloses that deletion requires proof of npub ownership and is 'as destructive as a write', providing important behavioral context about authentication and destructiveness.

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

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

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

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

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

Given the presence of an output schema, the description adequately covers purpose, usage, and behavioral traits. It lacks explicit success/failure details but is sufficient for a credential deletion tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minimal meaning beyond the schema, only clarifying npub usage for operator vs patron. It does not elaborate on parameter formats or constraints further.

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

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

The description clearly states 'Delete vaulted credentials for a specific service and npub', specifying the verb and target resources. It also distinguishes between operator and patron npub usage, differentiating it from similar tools like schwab_delete_coupon or schwab_delete_patron_credential.

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

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

The description provides explicit guidance on when to pass operator vs patron npub. However, it does not explicitly state when not to use this tool versus alternatives, but the context of 'forgetting credentials' is clear.

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

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

With no annotations provided, the description bears full responsibility. It discloses the security mechanism (proof-gated, prevents IDOR), cost (free), and the fact that it returns hash values. The behavioral context is fully transparent.

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

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

The description is concise with three paragraphs, each efficiently conveying a distinct aspect: purpose, usage prerequisites, and security rationale. No superfluous sentences. The critical information is front-loaded.

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

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

The description covers the essential steps: OAuth first, proof requirement, and subsequent call. Given the existence of an output schema, the description does not need to detail return values. It is nearly complete, though it could mention that the tool returns a list of account numbers and hashes.

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

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

Schema coverage is 100%, but the description adds value by explaining the purpose of each parameter (npub for billing, dpop_token as proof token from sibling tools) beyond the schema's brief descriptions. A score of 4 reflects this added clarity.

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

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

The description starts with a clear verb+resource: 'List Schwab account numbers and their hash identifiers.' It immediately conveys the tool's purpose and distinguishes it from sibling tools like schwab_get_brokerage_balances by positioning this as a prerequisite for brokerage data tools.

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

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

The description explicitly states when to use: 'Call after completing OAuth.' It provides prerequisites (Schnorr proof) and a follow-up action (call update_patron_credential). However, it does not explicitly state when not to use or name alternatives, but the context is clear.

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

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

No annotations provided, so description carries full burden. It thoroughly explains the Day P&L computation, fallback guards for missing or suspect snapshots, and the rationale for treating large P&L as stale.

Agents need to know what a tool does to the 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 bold lines and bullet points. While somewhat lengthy, every sentence adds value. The front-loaded summary and clear sections make it 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 the presence of an output schema, the description is largely complete, covering return values, fallback logic, and cross-referencing. The only gap is the missing parameter explanation for dpop_token.

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

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

Schema coverage is 50%: only npub has a description in the schema. The tool description does not add any additional meaning for dpop_token, leaving it unexplained. Parameter semantics are insufficient.

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

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

The description clearly states the tool retrieves the active Schwab account's current balance summary, listing four specific fields. It is distinct from siblings like get_brokerage_positions and get_brokerage_orders, which focus on other aspects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 includes an explicit cross-check recommendation for when Day P&L shows $0.00, directing to get_brokerage_positions. However, it doesn't explicitly differentiate from other balance tools like schwab_check_balance.

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

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

No annotations are provided, so the description carries the burden. It discloses the return format and average fill price computation, but does not mention authentication requirements or read-only nature. However, the tool is a simple read operation and the description is sufficient.

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

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

The description is concise, two paragraphs, front-loads the purpose, and provides usage guidance without wasted words. Every sentence adds value.

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

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

Given the presence of an output schema (though not shown), the description does not need to detail return values. It mentions the format and average fill price. However, it lacks information on error scenarios or prerequisites, but overall is complete for a simple 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 67% (2 of 3 parameters described). The description adds value by specifying the origin of order_id ('as returned by get_brokerage_orders'), but does not clarify dpop_token or expand on npub 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 'Get full details for a single order by Schwab order ID' and specifies the one-line markdown format, distinguishing it from the sibling tool get_brokerage_orders which returns a list.

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

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

Explicitly says 'Use this when you already have an orderId... and want a single crisp row rather than the full history list', providing clear guidance on when to use this tool vs. alternatives.

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

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

With no annotations, the description carries the full burden. It discloses the default behavior (30-day window), output format (markdown rows), and status enum. It does not mention authentication requirements or rate limits, but as a read-only tool, the description provides sufficient context for safe invocation. The format details are beyond schema.

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

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

The description is well-structured: a clear main statement, then bullet points for output format, a paragraph for date default, and a list for status enum. It is front-loaded with purpose. However, it is somewhat verbose with the detailed format explanation that is also present in the output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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's detailed output format is somewhat redundant but adds clarity. It covers default behavior and status filter. Missing details: pagination, max orders returned, and any account-specific notes. Overall, it is fairly complete for a read operation.

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

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

Schema coverage is 80%; the description adds important context: the date window defaults and the requirement to pass both parameters together. It also lists the valid status values, which are not in the schema's enum. This adds meaning beyond the 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 function: 'Get order history for the active Schwab account.' The verb 'Get' and resource 'order history' are specific. However, it does not explicitly differentiate from the sibling 'schwab_get_brokerage_order' (singular), which might fetch a single order. The output description suggests multiple orders, but no direct comparison.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidance on parameter usage: default date window and requirement to pass both dates if overriding one. It also lists valid status_filter values. However, it does not explain when to use this tool over alternatives like 'schwab_get_brokerage_transactions' or 'schwab_get_brokerage_order'. No when-not-to-use or context for other scenarios.

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

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

With no annotations, the description provides thorough behavioral details: it pulls from a specific endpoint, emits three markdown sections with structured output, explains quantity computation (longQuantity - shortQuantity), and describes the heuristic for spread detection, including its limitations (no iron condors, butterflies, calendars).

Agents need to know what a tool does to the 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 examples, making it easy to parse. However, it is somewhat lengthy; some sentences could be streamlined without losing information.

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

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

Given the presence of an output schema, the description still covers output format in detail (three sections with explanations). It addresses spread detection heuristic and limitations, making it complete for a positions tool. No required parameters are documented in the description, but the schema indicates none are required.

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

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

Schema coverage is 50% (npub described, dpop_token not). The description does not elaborate on these parameters, relying on the schema's minimal descriptions. No added meaning for dpop_token, and npub is briefly restated. The output format is detailed, but parameter semantics are neglected.

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

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

The description clearly states the tool retrieves current positions with automatic vertical-spread detection. It specifies the resource ('active Schwab account') and distinguishes it from sibling tools focused on balances, orders, or other data.

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

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

The description implies usage for viewing positions but does not explicitly state when to use this tool over alternatives (e.g., schwab_get_brokerage_balances, schwab_get_brokerage_orders). No when-not-to-use or alternative recommendations are provided.

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

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

No annotations provided, so description carries full burden. It describes the return format and implies a read operation, but does not disclose potential error conditions, authentication requirements, or rate limits. For a simple read, this is adequate but not enriched.

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

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

The description is concise (5 lines), front-loaded with the purpose, and includes a helpful format example. Every sentence adds value.

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

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

Given the tool has an output schema, the description covers purpose, usage context, and return format. It lacks details on error handling but is complete for a targeted retrieval 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 67% (dpop_token lacks description). The description adds no new parameter semantics beyond what the schema provides; it only repeats that transaction_id is the Schwab transaction ID. 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 retrieves full details for a single transaction by ID, and distinguishes it from the sibling get_brokerage_transactions by specifying it returns a canonical row in a specific markdown format.

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

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

Explicitly tells when to use: when you have a specific transactionId from get_brokerage_transactions, a journal entry, or confirmation, and want the canonical row instead of scanning a history window.

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

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

With no annotations, the description provides substantial behavioral detail: output format (markdown rows), fallback behavior for missing symbols, date window defaults, and the list of valid transaction type enum values. It does not disclose authentication or error handling, but overall is 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 well-structured with bullet points and clear sections. Every sentence adds value, no fluff. It efficiently conveys output format, defaults, and the enum list.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (5 params, output schema exists), the description covers output format, date behavior, and transaction types adequately. It does not mention error scenarios or authentication, but for a data retrieval tool, it is sufficiently complete.

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

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

Schema coverage is 80%, and the description adds value by explaining date defaults and listing the full set of transaction type enum values, which are not in the schema. It clarifies behavior for blank dates, enhancing parameter understanding.

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

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

The description clearly states the tool gets transaction history for the active Schwab account and provides detailed output format. It distinguishes from sibling tools like schwab_get_brokerage_balances or schwab_get_brokerage_positions by focusing on transactions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 default date range and transaction types parameter but does not explicitly contrast with schwab_get_brokerage_transaction (singular) or mention when not to use this tool. It covers the when-to-use aspect well.

Agents often have multiple tools that could apply. Explicit usage 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 bears full transparency burden. It explains the nested markdown output format, the structure of each market block, indicates sessions are conditional on Schwab reporting data, and notes the response is for a single day. This adequately discloses behavior beyond a simple 'get'.

Agents need to know what a tool does to the 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, starting with a clear one-line purpose, then a terse example of the output format. Each sentence adds value, and the structure is well-organized with bullet-like formatting. No wasted words.

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

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

Given the tool's moderate complexity (multiple markets, sessions), the description fully covers output format and conditional behavior. An output schema exists (not shown) to document return values, so the description appropriately focuses on usage and formatting context. It is complete for an agent to invoke the tool correctly.

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

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

Schema coverage is 75%, and parameter descriptions in the schema are already detailed. The tool description adds one key piece: the response is for a single trading day (implying each date must be queried separately) and notes unknown market types are dropped. However, most parameter meaning is already in the schema, so added value is marginal.

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

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

The description clearly states 'Get trading hours for one or more market types.' It uses a specific verb ('Get') and resource ('trading hours'), and uniquely identifies the tool among siblings. The example output further clarifies the 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?

No explicit guidance on when to use this tool versus alternatives is provided. The description implies use for checking market hours and explains output format, but lacks when-not-to-use or comparison with sibling tools. Usage context is inferred from the purpose.

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

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

With no annotations, the description carries the full burden. It discloses that results are capped at 20 rows server-side and returned as a markdown table, which is helpful. However, it does not mention authentication requirements (e.g., OAuth) or side effects. This is a minor gap given the tool is read-only.

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

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

Two sentences with no wasted words: first sentence states purpose and supported indices, second gives output format and cap. Highly concise and front-loaded.

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

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

The description is fairly complete for a read tool: purpose, supported inputs, output format, and limitation (cap). It lacks explicit mention of auth prerequisites, but output schema covers return structure. Minor gap, but sufficient overall.

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

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

Schema description coverage is 80%, so the schema already explains most parameters. The description adds context about the output limit (20 rows, server-side cap) but does not elaborate on parameter meanings beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Get top movers for a market index' with a specific verb and resource, and adds 'Schwab's curated mover screener' for context. It also mentions the output format and row limit, distinguishing it from sibling tools like get_stock_quote or get_price_history.

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

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

The description lists supported indices ($SPX, $DJI, $COMPX) and explicitly states unsupported ones ($VIX, $NDX, etc.), but does not provide when-to-use guidance versus other market tools like schwab_get_stock_quote or schwab_get_price_history. No explicit alternatives or exclusions are given.

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

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

With no annotations, description carries full burden. Discloses read-only nature, public data accessibility, and return behavior (latest fields or empty profile). Lacks information on rate limits or error handling, but is 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?

Two sentences, front-loaded with action, no redundant information. Every sentence adds value: what it does, why it's free, and what it returns.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 single-parameter read tool with output schema, description covers key aspects: purpose, input, return shape, and behavioral note (public data). Could mention default behavior when npub is empty, but implied as 'empty profile'.

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

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

Schema coverage is 0%; description clarifies that 'npub' parameter is the Nostr public key to look up. Does not specify format or validation, but provides sufficient context for intended use.

Input schemas describe structure but not intent. Descriptions should explain 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 explicitly states it reads a public Nostr profile for a given npub, distinguishing it from sibling write tool 'schwab_publish_nostr_profile'. Mentions specific metadata fields returned, making purpose 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?

States tool is free and requires no proof because data is public, providing clear context for when to use. However, does not explicitly exclude alternative tools or provide when-not-to-use guidance beyond that.

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

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

With no annotations provided, the description must disclose behaviors. It only states the high-level action without details on side effects (read-only vs. write), failure modes, or authentication needs. The return value is unknown without output schema visibility.

Agents need to know what a tool does to the 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, focused sentence that conveys the essential purpose without extraneous words. The structure front-loads the action and result.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 an output schema, the description need not detail return values. However, usage context is minimal; an agent might benefit from knowing this proof verifies inclusion in a snapshot, which is somewhat conveyed.

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

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

Schema coverage is 100% and both parameters have clear descriptions (npub and notarization_id). The tool description adds no extra meaning beyond the schema, meeting the baseline for well-documented parameters.

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

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

The description clearly states the tool's purpose: generating a Merkle inclusion proof for a patron's balance in a Bitcoin-notarized snapshot. The verb 'generate' and specific resource 'Merkle inclusion proof' make it distinct from siblings like schwab_list_notarizations or schwab_notarize_ledger.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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, such as schwab_check_proof_status or schwab_list_notarizations. Prerequisites like requiring a prior notarization are implied but not explicit.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool reports configuration status and is free, but does not mention authentication requirements, side effects, or idempotency. For a read-only report, the behavioral description is adequate but could be more detailed.

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

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

The description is three sentences (40 words), concise, and front-loaded with the primary purpose. Every sentence adds value: first states purpose, second explains what it shows, third gives alternative. No wasted words.

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

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

Given the existence of an output schema (not shown), the description need not explain return values. It covers what the tool does, contrasts with a sibling, and notes it is free. However, it could mention prerequisites or invocation context (e.g., after operator setup) 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?

There are zero parameters and schema coverage is 100%, so the description does not need to add parameter details. It provides context about the tool's function without needing to explain parameters. Baseline for 0 params is 4.

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

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

The description clearly states it reports an operator's configuration readiness, showing which settings are configured and missing. It distinguishes itself from the sibling 'get_patron_onboarding_status' which handles patron credential status.

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

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

The description explicitly tells when not to use this tool (for patron-level credential status) and directs to the alternative 'get_patron_onboarding_status'. However, it does not explicitly state when to use this tool, but the purpose is clear enough.

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

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

No annotations are provided, so the description carries the full burden. It describes the return format (markdown table with underlying price and filter constants) but does not mention authentication, rate limits, or credit consumption (implied by npub parameter). Disclosure is adequate but not exhaustive.

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

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

Two sentences with no fluff. The first states purpose, the second describes output. Every word is necessary 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 presence of an output schema, the description need not detail return values. It adequately covers purpose and output format but could clarify filtering criteria. Overall, it is sufficiently complete for a straightforward data 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 (83%). The description adds no additional meaning beyond the schema, focusing on output rather than parameters. Baseline of 3 is appropriate as the schema already documents 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 'Get a filtered option chain suitable for spread evaluation', specifying the verb 'Get', the resource 'option chain', and the purpose 'spread evaluation'. This distinguishes it from sibling tools like price history or stock quote.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 for spread evaluation but does not explicitly state when to use this tool versus other data tools. No alternatives or when-not guidance 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?

With no annotations provided, the description carries the full burden. It discloses that values are never exposed (safety), the tool is free (cost), and requires proof of npub ownership (authorization). It also notes that the list is sensitive. No contradictions or omissions regarding behavioral traits.

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

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

The description is concise and front-loaded, with the first sentence stating the core action. Every sentence adds meaningful information (return data, sensitivity, cost, authentication). No wasted words.

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

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

Given the presence of an output schema (not shown) and fully documented parameters, the description covers purpose, return content, cost, auth, and sensitivity. It lacks explicit error conditions or behavior for invalid inputs, but for a simple list tool, this is acceptable.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant semantic value beyond the schema; it reiterates that proof of npub ownership is required, which is already implied by the dpop_token parameter. The schema itself provides detailed parameter 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 lists stored patron credential field names (not values) and provides the return details (names + timestamps). It distinguishes itself from related tools like update or delete by emphasizing that values are never exposed, and the purpose is to verify configured fields and their age.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (verify configured fields, check ages) and mentions that proof of npub ownership is required, but does not explicitly contrast with sibling tools like update_patron_credential or delete_patron_credential. The guidance is inferred rather than explicit.

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

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

With no annotations provided, the description carries full burden. It discloses that the tool is free, requires proof of ownership, and explains behavior for different service types. It does not explicitly state read-only nature, but 'report' implies no mutation.

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

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

The description is concise with two paragraphs. It front-loads the purpose and efficiently covers variations and prerequisites without wasted words.

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

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

The tool has an output schema, and the description explains what the report contains (configured vs missing secrets). For a query tool, it is fairly complete, though it could mention error conditions or response format.

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

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

Schema coverage is 100% and schema descriptions are adequate. The description adds context about why dpop_token is needed (proof of ownership), which enhances understanding beyond the schema.

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

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

The description clearly states the tool reports patron credential readiness and distinguishes between set-once and dynamic services. However, it does not differentiate from similar sibling tools like schwab_check_oauth_status or schwab_get_operator_onboarding_status, 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 implies when to use (checking credential readiness) and mentions prerequisites (proof of npub ownership). However, it does not provide explicit guidance on when not to use or mention alternative tools among the many siblings.

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

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

With no annotations, the description discloses key behaviors: returns a markdown table, caps at 30 rows, adds truncation footnote. This provides substantial transparency beyond the input schema, though it omits any reference to authentication or billing requirements (handled via 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?

Two concise sentences. The first states the core purpose, the second explains the output format and truncation behavior. No wasted words.

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

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

Given the presence of an output schema (handling return values), the description covers purpose, output format, and a behavioral trait (truncation). It does not explain period-frequency combinations or usage context, but it is largely complete for a data retrieval tool.

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

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

Schema description coverage is 86% (high), so baseline is 3. The description adds no parameter-level details beyond the schema; it does not explain valid period-frequency combinations or the meaning of the 'npub' parameter beyond what is already in the schema.

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

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

Explicitly states 'Get historical OHLCV candle data for a symbol', clearly specifying the verb (get) and resource (historical candle data). This distinguishes it from related tools like schwab_check_price which gives current price.

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

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

Implied usage for historical data but no explicit when/not-to-use guidance or mention of alternatives. The description could be improved by noting when to prefer this over schwab_check_price or other market data 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?

Discloses critical side effect: self-initializes a scaffold if no model exists. Also notes no economic data. With no annotations, description fully covers behavioral traits.

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

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

Two concise sentences with front-loaded key info. 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?

Completely covers purpose, behavior, and side effects. Output schema handles return format. No gaps.

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

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

No parameters exist; schema coverage is 100%. Description adds nothing about parameters, which 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?

Clearly states it retrieves the active pricing model for the operator. Distinguishes from sibling tools like set or reset by being a getter.

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

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

Implicitly guides usage for reading the current model before modification. Lacks explicit when-not-to-use or alternatives, but context is sufficient for this simple tool.

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

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

With no annotations, the description must disclose behavioral traits but only states 'get real-time quotes.' It omits key behaviors such as silent omission of unresolvable symbols (though noted in schema) and the requirement for npub. The description adds minimal value beyond the structured 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?

The description is a single, clear sentence of 7 words—no wasted text. It could be more informative without becoming verbose, but it achieves conciseness effectively.

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

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

Given the tool has 3 parameters, a required npub for billing, and an output schema, the description is too minimal. It does not explain prerequisites, return format, or how it differs from the many sibling tools. The agent lacks sufficient context for correct invocation.

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

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

Schema coverage is 67% (npub and symbols described; dpop_token missing). The description itself adds no parameter information, but the schema already explains symbols handling (e.g., case-insensitive, whitespace tolerance, silent omission). Baseline of 3 is appropriate given moderate 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 tool retrieves 'real-time quotes' for 'one or more symbols,' using a specific verb and resource. However, it does not differentiate from similar siblings like schwab_check_price, which may also involve stock data.

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

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

The description provides no guidance on when to use this tool versus alternatives, no context about prerequisites (e.g., authentication via npub), and no exclusions. The agent is left to infer proper usage from the schema alone.

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

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

The description discloses that it is free and has no side effects, that it includes both seeded and unregistered tools (with registered:false flagging for drift), and that renaming a function changes mcp_name but keeps tool_id stable. It also explains it diffs the live wire surface against registry. Rich behavioral context beyond what annotations provide (and no annotations exist to contradict).

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

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

The description is fairly long (about 6 paragraphs) but each paragraph adds meaningful information: the authoritative use case, the inclusion of unregistered tools with issue references, the renaming semantics, and the wire-diff behavior. It's front-loaded with the core purpose in the first line. Slight redundancy between paragraphs 2 and 4 about drift/deploy drift, making it slightly less tight than ideal.

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

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

The tool has zero parameters, an output schema, and the description thoroughly explains return values including the registered:false flags, unregistered top-level array, and the drift-detection semantics. Given the complexity of the canonical-UUID reconciliation purpose and the absence of annotations, the description fully compensates and explains the output shape and why specific fields exist.

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

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

The tool has zero parameters and the schema is 100% covered (empty params). Per the rubric, 0 params = baseline 4. The description adds no parameter docs needed since there are none, but it does explain what the output contains semantically (registered:false, nested unregistered array), which aids the consumer in interpreting results.

Input schemas describe structure but not intent. Descriptions should explain 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 canonical (tool_id, mcp_name, ...) for every tool the wheel exposes. It uses a specific verb ('Return') with a precise resource ('canonical tool identity list'), and it distinguishes itself from siblings by framing itself as the authoritative identity source used by Reconcile — clearly differentiating from data/list tools like schwab_list_coupons and oracle introspection tools.

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

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

The description explicitly names the consumers (Studio, agents, FE, Reconcile) and states the exact use case: UUID-join against stored pricing model, with explicit instruction 'no name-based UUID derivation, no guessing.' It also explains when not to use it implicitly by positioning this as canonical against other tools that would guess. This is explicit usage guidance with concrete exclusionary instruction.

Agents often have multiple tools that could apply. Explicit usage 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 that the tool is free, lists constraint types and parameter schemas, and implies a read-only operation. No hidden behaviors or 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?

Three sentences, front-loaded with main purpose, no wasted words. Each sentence adds value: purpose, content, cost.

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

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

Simple list tool with no inputs; description covers output, cost, and scope. Output schema exists, so return values are already documented. No gaps.

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

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

Tool has zero parameters; description adds no parameter info, but baseline for 0 params is 4. No additional semantic value needed 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 uses specific verb 'list' and identifies the resource 'constraint types'. It clearly distinguishes from sibling tools that deal with accounts, orders, or other entities.

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

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

Description states it is free and returns constraint parameter schemas, implying usage when needing constraint definitions. However, it does not explicitly mention when not to use or compare with alternatives.

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

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

Discloses the 'times_redeemed' counter and progress bar rendering, and the restriction requiring proof. No annotations exist, so description carries burden well.

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

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

Three concise sentences, front-loaded with key action and ordering. 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?

Explains ordering and key return fields (times_redeemed, total_uses). Output schema presumably documents full structure, so description is sufficient.

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

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

Schema has one parameter 'dpop_token' with no description. Description does not mention or explain this parameter, adding no value beyond schema.

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

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

Description clearly states it lists coupons minted by the operator, newest first. Differentiates from sibling 'schwab_list_my_coupons' by 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?

Explicitly notes 'RESTRICTED to operator — requires proof', guiding when to use. Could explicitly mention not for non-operators.

Agents often have multiple tools that could apply. Explicit usage 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 transparently states it returns both active and exhausted redemptions with status, and that it is free but requires npub proof. It does not detail side effects (none expected) or pagination, but is sufficient 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?

Two concise sentences convey purpose, return details, and a requirement with no unnecessary words. Structure supports quick comprehension.

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

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

Given the simple parameters and existence of an output schema, the description covers core functionality and return values. Minor gaps (e.g., dpop_token meaning) but overall complete for a list tool.

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

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

Schema coverage is 0%, so description must compensate. It clarifies npub as a required proof, adding meaning beyond the schema. However, dpop_token is not explained, leaving a gap.

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

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

The description clearly states the tool lists coupons redeemed by a specific patron on the operator, with details on returned status types. This distinguishes it from sibling tools like 'schwab_list_coupons' which likely lists all coupons.

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

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

The description implies usage for retrieving a patron's redeemed coupons and mentions a prerequisite (proof of npub), but does not explicitly guide when to use this tool over alternatives like 'schwab_list_coupons' or 'schwab_update_coupon'.

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

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

With no annotations, the description bears full burden for behavioral disclosure. It only says 'List recent' without defining 'recent' (e.g., time window, order), pagination behavior, or required permissions. The agent lacks critical understanding of the tool's behavior 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 short sentence that communicates the core purpose with no extraneous words. It is optimally concise 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?

While the tool is simple (2 parameters, no required fields, and an output schema exists), the description lacks important context such as the meaning of 'recent' and typical use cases. It is adequate but not thorough for a tool that might require understanding of data recency or filters.

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

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

The input schema has 100% description coverage for its two parameters (limit and status). The description adds no additional meaning beyond what the schema already provides, so it meets the baseline but does not enhance parameter understanding.

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

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

The description 'List recent Bitcoin notarization records' uses a specific verb ('List') and resource ('Bitcoin notarization records'), which clearly distinguishes it from sibling tools like 'get_notarization_proof' (retrieve a specific proof) and 'notarize_ledger' (create a 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 provides no explicit guidance on when to use this tool versus alternatives, nor does it specify conditions or exclusions. It merely states what it does, leaving the agent to infer usage context from the name and siblings.

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

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

With no annotations, the description carries the full burden. It only says 'Create,' omitting side effects, authentication requirements, idempotency, or uniqueness constraints (e.g., the schema mentions operator-scoped uniqueness but the description does not address name collisions).

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

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

The description is a single concise sentence with no filler. Every word serves to convey the tool's purpose efficiently.

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

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

While the tool has an output schema (unseen) and decent schema coverage, the description lacks context on side effects, error cases, or usage constraints. For a creation tool, more behavioral context would be beneficial.

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

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

Schema description coverage is 86%, which is high. The description does not add meaning beyond the schema's parameter descriptions, so a 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 'Create a new operator-owned discount coupon,' providing a specific verb and resource. It distinguishes itself from sibling tools like update_coupon, delete_coupon, and list_coupons.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, conditions, or situations where another tool would be more appropriate.

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

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

Without annotations, the description effectively discloses key behaviors: it is an operator-only background task, Bitcoin confirmation takes 1-6 hours, and it is free (no credits). This provides substantial transparency beyond the tool's basic 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 at three sentences, each serving a purpose: first explains the action, second gives usage constraint, third provides time and cost information. No wasted words; front-loaded with the core action.

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

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

Given zero parameters, the description covers all essential aspects: what it does, who can use it (operator-only), behavioral expectations (1-6 hours, free). An output schema exists, so explaining return values is not required. The description is fully sufficient for a simple 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 baseline score is 4 per instructions. The description adds no parameter information, but none is needed. The schema coverage is 100% vacuously.

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

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

The description clearly states the action: building a Merkle tree of patron balances and submitting the root to Bitcoin via OpenTimestamps. It uses a specific verb ('Build... and submit') and resource ('all patron balances'). This clearly distinguishes it from sibling tools like 'schwab_get_notarization_proof' or 'schwab_check_balance'.

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

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

The description indicates this is an 'Operator-only background task', giving a clear usage constraint. However, it does not explicitly state when to use this tool versus alternatives or provide when-not-to-use guidance. The absence of sibling differentiation limits the score.

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

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

With no annotations, the description carries the full burden. It only says 'describe' and 'Free,' failing to disclose whether it is read-only, requires authentication, or has any side effects. Minimal behavioral insight.

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

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

The description is very short and front-loaded with the main action. However, 'Free.' is arguably unnecessary and adds noise. It earns a 4 for efficiency despite minor superfluous text.

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

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

Given no input parameters and an output schema present, the description is adequate but minimal. It does not explain what 'describe' entails in terms of output content, leaving some ambiguity about the returned information.

Complex tools with many parameters or behaviors need more documentation. 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 schema coverage is 100%. The description adds no parameter info, but none is needed. Baseline of 4 applies for no parameters.

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

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

The description clearly states the tool 'describes the DPYC ecosystem via the Oracle,' which is a specific verb and resource. While it is distinct from sibling oracle tools (like get_tax_rate or lookup_member), it could be more precise about the scope of 'describe.'

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

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

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

No annotations are provided, so the description must disclose behavior. It mentions 'Free' but does not explicitly state that the tool is read-only, has no side effects, or requires no authentication. This is insufficient for full transparency.

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

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

The description is a single clear sentence with no wasted words. It is front-loaded and efficient.

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

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

Given no parameters and an output schema, the description is adequate but minimal. It lacks any mention of prerequisites, typical usage, or behavioral notes that would aid an agent in invoking 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 tool has no parameters, so schema coverage is 100% vacuously. The description adds meaning by specifying the returned resource is the 'DPYC certification tax rate', which clarifies the output beyond the empty schema.

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

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

The description clearly states it gets the current DPYC certification tax rate, which is a specific verb+resource. It distinguishes from sibling oracle tools like schwab_oracle_lookup_member or schwab_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?

The description only says 'Free' but provides no guidance on when to use this tool versus alternatives, nor any context about prerequisites or limitations.

Agents often have multiple tools that could apply. Explicit usage 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 does not state whether the operation is read-only, requires authentication, or any other behavioral traits. The label 'Free' is irrelevant to behavior. The tool appears to be a simple retrieval, but critical details are missing.

Agents need to know what a tool does to the 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 and concise. Every word serves a purpose. However, it could be slightly more informative without losing conciseness (e.g., explaining what DPYC stands for). Still, it is appropriately sized for a parameterless tool.

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

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

Given the tool's simplicity (no parameters) and the presence of an output schema, the description is nearly complete. However, it lacks context about what 'DPYC' and 'Oracle' refer to, which may be important for an agent unfamiliar with the domain. A minimal addition would make it fully self-contained.

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

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

The input schema has zero parameters and 100% schema description coverage, so the schema already fully defines the parameter space. With no parameters, baseline is 4. The description does not need to add parameter information, and it correctly omits any.

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

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

The description clearly states the tool's purpose: 'Get DPYC onboarding instructions from the Oracle.' The verb 'get' and resource 'DPYC onboarding instructions' are specific. While it doesn't explicitly differentiate from sibling tools like 'schwab_get_operator_onboarding_status' (which retrieves status, not instructions) or 'schwab_oracle_about' (general information), the purpose is unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or exclusions. The only additional note is 'Free,' which hints at cost but offers no decision-making support.

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

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

No annotations are present, so the description carries full burden. It only mentions 'Free', which hints at no cost but fails to disclose authentication needs, error behavior, or whether it is a read-only operation.

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

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

The description is very concise at 7 words, but includes the potentially useful 'Free' qualifier. It is front-loaded with the purpose, though more detail could be added without losing conciseness.

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

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

For a simple lookup tool with one parameter and an output schema, the description is minimally adequate but lacks details like return value summary or side-effect information. It covers the basic action but not the full context.

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

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

The description mentions 'by npub', confirming the parameter's purpose, but the schema has 0% coverage and the description adds no format, examples, or constraints beyond the property name.

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

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

The description clearly states the verb 'look up' and the resource 'DPYC community member by npub'. It distinguishes from sibling tools, which include various oracle and non-oracle actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 other oracle lookups or search tools. The description does not specify prerequisites or when not to use it.

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

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

With no annotations, the description must disclose behavioral traits. It only states it gets advisories and is 'Free', lacking details on side effects, authentication requirements, rate limits, or whether it is a read-only 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 a single sentence of eight words, conveying the essential purpose without any waste. It is well front-loaded with the verb 'Get'.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 parameters and an output schema, the description adequately covers the basic function. It could mention that advisories are 'active' but the purpose is clear. The output schema likely provides return details.

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

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

The tool has zero parameters, so the description does not need to add param info. According to guidelines, baseline is 4 for no 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 'Get', the resource 'active network advisories', and the source 'from the Oracle'. It is distinct from sibling oracle tools like schwab_oracle_about or schwab_oracle_get_tax_rate.

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

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

No guidance is provided on when to use this tool versus alternatives, nor any exclusions or prerequisites. The word 'Free' hints at no cost but does not clarify usage context.

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

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

No annotations are provided, so the description bears full responsibility. It discloses that the wheel verifies the signature matches the npub, relays to public relays, and that no nsec is held. It also states it is free. While it does not cover rate limits or error behavior, the core behavioral traits are well covered.

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

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

The description is well-structured with a clear opening sentence and a concise explanation of the workflow. It uses line breaks for readability. Every sentence adds value, though it could be slightly more terse. No fluff.

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

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

Given the tool's simplicity (2 params, no required, output schema exists), the description covers the main aspects: purpose, workflow, security model, and cost. It does not detail error handling or response, but the output schema likely covers that. It is sufficiently complete for an agent.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds some workflow context (e.g., 'client-signed event', 'patron's Nostr public key') but essentially restates the schema descriptions. The added value is marginal beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Publish' and the resource 'CLIENT-SIGNED kind-0 profile to relays for an npub'. It distinguishes from sibling like 'get_nostr_profile' by emphasizing client-signing and no key custody. The purpose is specific and unambiguous.

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

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

The description explains the workflow where the frontend signs and passes the event, and that the wheel does not hold the nsec, implying usage is for client-signed profiles only. However, it does not explicitly state when not to use or mention alternatives, but given the sibling set, it's clear this is the sole publish tool.

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

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

No annotations provided, so description carries full burden. Discloses creation of invoice, payment requirement, npub proof requirement, and that the tool is free. Missing details like invoice expiration or what happens if not paid, but overall sufficient.

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

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

Three concise paragraphs, front-loaded with main action. Every sentence adds value; no fluff.

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

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

Explains the full flow, prerequisites, and that output schema (not shown) likely covers return values. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context about dpop_token requirement but does not significantly augment the schema's 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?

Description clearly states 'Buy credits via Bitcoin Lightning' with specific verb and resource. It explains the process: creates invoice, pay, then confirm. Distinguishes from siblings as it is the only purchase-credits tool.

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

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

Describes the workflow and prerequisite (Proof of npub ownership). Does not explicitly state when not to use or suggest alternatives, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage 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 details deterministic one-shot retrieval, relay drainage, DM deletion for wrong phrases, NACKing, acceptance of first match, and the fallback 'courier_not_found' result. It also explains the credential_card path bypasses relay and that no server restart is needed. Minor omission: does not mention any error conditions beyond 'not found'.

Agents need to know what a tool does to the 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 moderately long but well-structured: purpose first, then flow, then details. Each sentence provides necessary information, though some redundancy exists (e.g., 'Deterministic, one-shot retrieval' is stated both in the flow and later). Still, it is efficient for the complexity.

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

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

Given the 4 parameters with 100% schema coverage and an output schema present, the description sufficiently covers the tool's behavior, constraints, and edge cases. It explains the two execution paths (relay-based and direct redemption) and the result for no match. Minor gap: no guidance on output format, but output schema handles that.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining 'dpop_token' as the session phrase from request_credential_channel and clarifying that 'credential_card' is optional and bypasses the relay drain, going beyond the schema's default 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 picks up credentials from the Secure Courier and completes the CREDENTIAL-DELIVERY flow. It distinguishes itself from the sibling 'receive_npub_proof' by noting it is the ownership-proof counterpart, making the purpose specific and non-ambiguous.

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

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

The description explicitly says 'Call this only after the user confirms they have replied.' and warns against polling ('Do NOT poll, loop, or retry.'). It provides context for the flow and mentions the credential_card bypass path, but does not explicitly list alternatives for when not to use this tool, though the sibling reference helps.

Agents often have multiple tools that could apply. Explicit usage 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 carries the burden of behavioral disclosure. It details deterministic one-shot retrieval, draining only the pinned relay, deletion of mismatched DMs, consequences of premature calls, and token storage/handling. No contradictions exist.

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

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

The description is well-structured with clear paragraphs, and nearly every sentence adds unique value. Minor redundancy exists (e.g., repeated emphasis on not polling), but it remains efficient given the complexity.

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

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

Given the tool's complexity (part of a proof flow with relays, DMs, and tokens), the description covers all necessary aspects: when to call, how it works, side effects, return value, and downstream usage. The presence of an output schema further reduces burden, yet the description is still 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 coverage is 100%, so baseline is 3. The description adds value by explaining the provenance of dpop_token (from request_npub_proof) and the role of patron_npub, providing flow context beyond the 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: receiving npub ownership confirmation from a patron and completing the npub-OWNERSHIP-PROOF flow. It is specific and distinct from the credential-delivery counterpart 'receive_credentials', though it does not explicitly differentiate from all sibling tools.

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

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

The description provides explicit guidance: 'Call this only after the user confirms they have replied' and warns against polling, looping, or retrying. It also mentions the complementary tool 'receive_credentials', but could be more precise about when not to use this tool versus others in the flow.

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

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

With no annotations, description fully details behavior: validates window and cap, records redemption, auto-applies discount on subsequent calls, free, idempotent. 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?

Five concise sentences, each providing unique value. Front-loaded with primary action, then validation, side effects, cost, and idempotency. No unnecessary 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 presence of output schema, description covers all critical aspects: inputs, behavior, constraints, and effects. Also mentions return behavior on duplicate redemption. Complete for a redeem tool.

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

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

Schema description coverage is 0%, but description explains 'code' as the operator's shared code and 'npub' as proof identity. Does not describe 'dpop_token', but it has a default and is optional. Overall adds meaningful context 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 the action 'Claim a coupon by its name', specifying verb (redeem/claim) and resource (coupon by code). Distinguishes from sibling coupon tools like mint, delete, list, 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?

Provides context: 'Free — no credits required', 'Requires proof of npub', and 'Idempotent'. Implicitly tells when to use (when claiming a coupon). Could explicitly mention alternatives but remains 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 bears full burden. It discloses behavioral traits: costs a fee, report is public and stamped with npub, attribution to user not operator, and error handling if not configured. It also details the dpop_token format and constraints.

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

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

The description is moderately lengthy but front-loads the main purpose. Some redundancy exists (e.g., explaining dpop_token in detail could be condensed), but it remains readable and 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 5 parameters (4 required), output schema exists, and description covers outputs (repo, number, url) and error case. It also explains the fee and attribution. Completeness is high, though slightly verbose.

Complex tools with many parameters or behaviors need more documentation. 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 parameters are documented. The description adds context for dpop_token (raw JSON, constraints) but does not significantly augment other parameters beyond schema defaults. Baseline 3 is appropriate.

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

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

The description clearly states that the tool files a field report as a GitHub issue on the operator's repo. It specifies the action (file a report) and resource (GitHub issue on operator's repo), distinguishing it from sibling tools that deal with financial operations.

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

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

The description explains when to use the tool (found a tool's metadata or response wrong/confusing), prerequisites (npub, dpop_token), costs, and what happens if reporting is not configured. It lacks explicit alternatives or when-not-to-use guidance but is otherwise 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 fully covers behavioral aspects: it mints proof, delivers MCP-to-MCP, records as pending, and transitions to 'ready'. It does not discuss error cases or idempotency, but the core behavior is well explained.

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

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

The description is well-structured, starting with purpose, then restrictions, then process. While somewhat lengthy, every sentence adds necessary context. It could be slightly more concise but 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?

Given the complexity (4 params, output schema exists), the description adequately covers the workflow: restriction, proof, endpoint resolution, and status polling. The existence of an output schema means return values need not be detailed.

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

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

Schema description coverage is 100%, so the schema already documents parameters adequately. The description adds marginal value by contextualizing `authority_npub` as the target and `dpop_token` as proof, but mostly repeats or implies schema content.

Input schemas describe structure but not intent. Descriptions should explain 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 verbs ('request adoption') and identifies the resource ('Authority' and 'operator'). It clearly distinguishes from siblings like `schwab_adoption_status` by describing the action of initiating adoption rather than checking progress.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 restricts usage to the operator and requires proof of control over the npub. It advises polling `adoption_status` for progress. While it doesn't state explicit when-not conditions, the context is clear enough for appropriate use.

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

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

With no annotations provided, the description carries full burden. It discloses that the tool sends a welcome DM, requires manual human reply, is human-in-the-loop, and warns that each receive_credentials call destructively drains the relay mailbox. This adds significant behavioral context, though it could mention error handling or timeouts.

Agents need to know what a tool does to the 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 clear front-loaded purpose, followed by usage guidance and behavioral notes. Each sentence adds value, though some detail (e.g., explicit 'do not poll') could be slightly shortened. Overall, it efficiently communicates the essential information.

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

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

Given the tool's complexity and the absence of annotations, the description covers the flow, human-in-the-loop requirement, post-call actions, and warnings about destructive behavior. It could include what happens on error or timeout, but it is sufficiently 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 100%, so the baseline is 3. The description adds no new semantic information beyond what the schema already provides for both parameters (service and sender_npub). It does not elaborate on formats 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 opens a secure courier channel for credential delivery, distinguishing it from request_npub_proof and noting when not to use it (e.g., for OAuth2 services). The verb 'open' and resource 'credential channel' are specific and distinct from siblings.

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

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

The description explicitly advises when to use (credential delivery) and when not (for npub proof), references checking service_status first for dynamic services, and provides step-by-step post-call instructions: stop, tell user, wait for confirmation, avoid polling. This is comprehensive 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 fully covers behavioral traits: sends DM, requires human interaction, returns dpop_token that must be remembered, proof expires, and that receive_npub_proof destructively drains relay mailbox. 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 relatively long but well-structured with bold highlights and clear sections. Each sentence adds value; minimal redundancy. Slightly verbose but not wasteful.

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

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

Given no annotations and a complex tool with output schema, the description covers flow, return value (dpop_token), lifecycle, expiry, and operational instructions. It is complete and self-contained.

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

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

All three parameters are fully described in the input schema (100% coverage). The description adds valuable context for 'reason' (signed into attestation) and 'verify_at' (generalized OAuth verification_uri), enriching 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 requests npub ownership proof via Nostr DM, and distinguishes it from the sibling tool 'request_credential_channel' which delivers secrets. The verb 'request' and resource 'npub proof' are specific.

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

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

Explicitly states when to use (when 'proof_required' is returned), what it does not do (no service secret delivery), directs to alternative, and describes the human-in-the-loop flow with instructions to wait and not poll.

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

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

With no annotations, the description fully discloses key behaviors: it deletes all stored models, self-initializes a fresh one with tools at 0 sats and proper UUIDs, returns the new model, and is restricted to operators requiring proof. This is comprehensive for a destructive 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 concise with three short, well-structured sentences. It front-loads the main purpose, details the process, and ends with restrictions. Every sentence adds value without redundancy.

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

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