excalibur-mcp

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

Discloses key behavioral traits: free (no credits consumed), requires dpop_token for authentication, and returns a structured statement. Since no annotations are present, the description carries full burden and adequately conveys that it is a read-only, authenticated query. Could mention rate limits or idempotency but not required.

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

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

Moderately concise with clear structure (intro, differentiation, cost note, auth note, then arg list). However, the arg list could be integrated more succinctly, and the 'Free — no credits consumed' sentence could be combined with the note about proof.

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

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

Given that an output schema exists, the description need not explain return format. It already details the returned data (purchase history, credit tranches, per-tool usage, daily logs) and provides authentication context. No gaps in information needed 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?

Adds significant meaning beyond the schema: explains npub as Nostr public key format, dpop_token as a kind-27235 event signed by the npub, and days as number of daily usage history days with a default of 30. All three parameters are fully described despite 0% schema description 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?

Clearly states the tool generates a patron's account statement and lists the content returned. Distinguishes from the operator's Authority tax balance. However, does not explicitly differentiate from the sibling tool 'excalibur_account_statement_infographic', which likely produces a formatted infographic instead of raw 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?

Mentions that the tool is free and requires proof of npub ownership via a dpop_token, implying authentication needs. Provides some context for when to use (e.g., not for Authority balance), but no explicit when-to-use or when-not-to-use guidance relative to sibling tools like the infographic version.

Agents often have multiple tools that could apply. Explicit usage 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 discloses output components, cost, and verification mechanism fully. 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?

Efficiently front-loaded with summary, followed by output details, cost, and parameter list. No 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?

Covers purpose, parameters, output nature, cost, verification. Output schema exists, so return values not needed. Complete for this tool.

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

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

Schema coverage is 0%, but description provides complete parameter explanations with meaning and defaults, adding substantial 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?

Starts with 'Generate a visual SVG infographic of your account statement', clearly stating verb and resource. Distinguishes from sibling 'excalibur_account_statement' which likely returns raw 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?

Implies use for visual output instead of raw data, mentions cost and verification, but lacks explicit when-not or alternatives beyond the sibling.

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

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

With no annotations, the description carries full burden. It discloses it is a polling operation (network call) and lists possible statuses. However, it does not mention side effects, authorization requirements (dpop_token unexplained), error behavior, or rate limits. Adequate but not comprehensive.

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

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

Two short, front-loaded sentences with no unnecessary text. Every word adds value: verb, resource, notable characteristics (free, poll, statuses). Ideal conciseness.

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

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

Given an output schema exists (not shown), return values are covered. However, parameter details (especially dpop_token) are missing, and prerequisites or error conditions are not mentioned. Adequate for a simple tool but lacking nuance.

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

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

Schema description coverage is 0%; the description partially compensates by implying authority_npub refers to a 'chosen Authority', but does not explain format or purpose of dpop_token (which has a default). Incomplete parameter documentation beyond inferred context.

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

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

The description clearly states the verb 'Check' and the resource 'adoption-request status' with specific context of 'chosen Authority'. It enumerates possible statuses (pending/approved/rejected/provisioned), uniquely identifying this tool among siblings like 'excalibur_get_operator_onboarding_status'.

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

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

Minimal usage guidance: the description mentions it is 'Free' and 'Polls the Authority', but does not specify when to use versus alternatives (e.g., similar status checks) or provide explicit when-not conditions. No sibling differentiation beyond the name.

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

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

Discloses that the tool is free and requires proof of npub ownership to prevent DOS. However, it does not mention expiration of the authorization URL or specific error handling beyond what is stated. Without annotations, the description carries full burden and does a good job but lacks some details.

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

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

Description is concise with front-loaded purpose. Each sentence adds value: purpose, flow, cost, security note, and usage guidelines. 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 simplicity and the presence of an output schema, the description covers the essential aspects: purpose, parameters, usage conditions, and next steps. It is adequately complete but could mention URL expiry or error responses.

Complex tools with many parameters or behaviors need more documentation. 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%, but description adds meaning: npub is 'Your DPYC patron npub (npub1...)' and dpop_token is 'A kind-27235 Nostr event signed by npub for this tool'. This provides helpful context 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?

Clearly states 'Start the OAuth2 authorization flow' and explains the flow including returning a URL and calling check_oauth_status. Distinguishes itself from sibling check_oauth_status by explicitly mentioning it as the next 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?

Provides explicit guidance: do not call pre-emptively, try live tool call first and only begin OAuth when it fails with 'upstream_auth_refresh_needed'. Also clarifies that a pending check_oauth_status is not evidence of a lapsed session.

Agents often have multiple tools that could apply. Explicit usage 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 returns available sats, the effect of zero balance, and clarifies it's operator's own funding (not patron balance). It also notes 'Free,' indicating no cost. Since no annotations are provided, the description carries the full burden and does so well, though it could mention idempotency.

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

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

The description is front-loaded with the main action and consists of four concise sentences, each adding essential information: purpose, return value, business implication, and clarification. No redundant words.

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

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

Given no parameters and an existing output schema, the description covers the purpose, return value, business context, and common pitfalls. It is fully sufficient for an agent to understand when and how to use this tool.

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

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

The tool has zero parameters, so the description need not explain parameters. The instruction states baseline 4 for 0 params, and the description adds no parameter information, 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?

The description clearly states 'Check this operator's tax balance at the Authority,' specifying the exact resource and action. It distinguishes from siblings like 'excalibur_check_balance' by focusing on the authority tax balance and its role in certifying patron credits.

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

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

The description implies when to use this tool (to check operator funding for patron credits) and mentions a consequence when balance is zero, but does not explicitly state when not to use it or compare with alternatives like 'excalibur_check_balance' or 'excalibur_check_payment'.

Agents often have multiple tools that could apply. Explicit usage 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 key behavioral traits: it is a read operation (check balance), it is free (no credits required), and requires authentication via dpop_token. However, it does not mention error handling for invalid tokens or nonexistent npubs. Given no annotations, the description does well.

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

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

The description is well-structured with paragraphs and an Args section, front-loading the core purpose. It is informative without being verbose, though minor redundancy exists (e.g., re-explaining dpop_token in Args).

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 input, authentication, and distinction from sibling. Given output schema exists, it is sufficient for a balance check tool. It could mention the unit of balance, but the output schema likely handles that.

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

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

Schema coverage is 0%, but the description adds full semantic meaning: npub is the Nostr public key whose balance to check, and dpop_token is a kind-27235 Nostr event signed by npub for this tool. This adds substantial value over the bare 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 checks a patron's credit balance at the operator, distinguishing it from sibling authority_check_balance by specifying it is the spending balance. The verb 'check' and resource 'credit balance' are 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 provides explicit when-to-use guidance, clarifying that this tool is for patron balance and not for operator's authority balance, with a direct alternative named (authority_check_balance). It also notes that tool is free and requires proof of npub ownership.

Agents often have multiple tools that could apply. Explicit usage 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 discloses important behaviors: it is free, requires proof of npub ownership, and explains the interpretation of results. It does not explicitly label itself as read-only, but the context strongly implies it.

Agents need to know what a tool does to the 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 purpose, usage, clarification, and parameter docs. It is slightly lengthy but every sentence adds value; could be trimmed slightly but remains effective.

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

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

Given the tool has an output schema, the description covers purpose, usage, nuances, and parameter meanings. It lacks explicit error handling or authentication details but is sufficient for the OAuth 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?

Despite 0% schema coverage, the description fully explains both parameters: npub must match the one used in begin_oauth, and dpop_token is a Nostr event. This adds essential meaning beyond the schema.

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

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

The description clearly states the action: 'Check whether the OAuth2 authorization flow has completed.' It distinguishes from sibling tools like begin_oauth and session_status by specifying the context and what it does not indicate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 to call after completing login from begin_oauth, and clarifies that a 'pending' result does not imply session lapse, recommending fallback only on specific errors. Provides clear when-to-use and alternatives.

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

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

No annotations provided; description discloses free usage, proof-of-npub ownership requirement, and dpop_token rationale. Could specify return value details or error cases.

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

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

Structured with intro and Args section, each sentence adds value. Slightly verbose in dpop_token justification but overall concise.

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

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

Has output schema, so return values need no explanation. Description covers tool purpose, usage timing, and all parameter details sufficiently.

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

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

Input schema has 0% description coverage, but the description compensates fully by explaining each parameter (invoice_id, npub, dpop_token) including their source and purpose.

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

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

The description clearly states the tool checks Lightning invoice payment status, specifies it should be called after purchase_credits, and distinguishes it from siblings like excalibur_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 ownership, dpop token). Lacks explicit when-not-to-use but provides adequate 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?

Description reveals it is free and shows base cost and constraint effects. However, it does not mention any prerequisites, potential errors, or whether authentication is needed. Annotations are absent, so description carries full burden.

Agents need to know what a tool does to the 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, well-structured with an Args section. Every sentence adds value, no fluff. Efficiently communicates purpose and parameter details.

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

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

Adequately explains what the tool does and how parameters work. Output schema exists (though not shown), so return format is covered. Could mention that it is a read-only preview, but overall sufficient for its 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?

Explains tool_id as UUID or capability string, and tool_kwargs as optional JSON for pricing preview. This adds meaning beyond schema types. npub and dpop_token have defaults but are not described, but overall good coverage for key parameters.

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

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

Clearly states it previews the effective cost of a tool call, including base cost and constraint effects. Distinct from sibling tools that handle other operations like balance checks or post creation.

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

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

Implied usage for checking cost before calling a tool, but no explicit guidance on when to use this vs other related tools like excalibur_check_balance or excalibur_check_payment. Lacks when-not-to-use or alternatives.

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

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

With no annotations provided, the description fully discloses behavior: 'Free, no side effects — does not evict the cache or touch relays.' This adds important context for an agent. Could be slightly more explicit about the return value format, but it's sufficient for a status check.

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

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

The description is concise, front-loading the purpose in the first sentence. The Args section is structured but not overly verbose. One could argue the code-block formatting is slightly redundant with the schema, but overall it's well-organized and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 need not detail return values. It covers purpose, usage timing, parameters, and behavioral traits (free, no side effects). For a simple status-checking tool, this is fully complete.

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

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

Schema coverage is 0% (no parameter descriptions), but the description adds thorough details: both parameters are labeled required (contrary to schema defaults), 'patron_npub' is described as npub1... format, and 'dpop_token' is connected to specific tool outputs (request_npub_proof/receive_npub_proof). This adds significant meaning beyond the schema.

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

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

The description clearly states the tool checks if a cached dpop_token is still valid, using verb 'check' and specific resource. It distinguishes from sibling 'check_oauth_status' by noting this is for the npub-proof flow, making purpose clear and differentiated.

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

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

The description provides explicit usage context: 'ask if next paid call will accept dpop_token before burning credits on guaranteed failure.' It also mentions it mirrors check_oauth_status and is free with no side effects. However, it does not explicitly list when not to use or alternative tools, though the flow is implied.

Agents often have multiple tools that could apply. Explicit usage 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. Description covers idempotency with client_req_id and billing implication, but omits details on authorization, error handling, or side effects of creating a post. Adequate but not thorough.

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

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

Description is structured as a docstring with clear sections and front-loaded purpose. While slightly long for the parameter count, each sentence adds value. 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 11 parameters, 1 required, and nested objects, the description explains most parameters and key conditions (e.g., publish_at for scheduled status). Output schema exists but isn't detailed in description, which is acceptable. Lacks error scenarios.

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

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

Schema coverage is only 9%, but description provides meaningful explanations for most parameters in Args section (e.g., doc, text_cache, publish_at, recurrence, client_req_id). However, tweet_url and dpop_token are not described, leaving gaps.

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

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

Description clearly states it creates a new post (draft or scheduled) and returns its post_id. However, it does not explicitly distinguish from the sibling tool excalibur_update_post for updates, leaving slight 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?

No explicit guidance on when to use this tool vs alternatives. Given the sibling excalibur_update_post exists for updates and excalibur_process_scheduled_posts for processing, the description lacks contextual cues for selection.

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

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

With no annotations, the description carries the full burden. It discloses cascading deletion, effect on chain steps (no-op with neutral constraint), and that the Studio shows orphan warnings. It clearly implies destructive behavior, though it does not mention idempotency or error handling.

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

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

The description is three concise sentences. It front-loads the purpose, then explains side effects, and concludes with access restrictions. No extraneous information.

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

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

Considering the tool has only two parameters and an output schema (not shown), the description covers the critical behavioral aspects. However, it omits explanation of the dpop_token parameter and does not describe return values or error states, which is a gap for completeness.

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

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

Schema description coverage is 0%. The description only implicitly covers coupon_id ('Delete a coupon') but provides no explanation for the dpop_token parameter. Users must infer its purpose from context, which is 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 'Delete a coupon' with a specific verb and resource. It also mentions cascading to all patron redemptions, which distinguishes it from other coupon-related tools like excalibur_forget_coupon or excalibur_update_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?

The description indicates that this tool is 'RESTRICTED to operator' and 'requires proof', implying authorization requirements. It implicitly warns of severe effects (cascade), but does not explicitly compare to alternatives like excalibur_forget_coupon for when to use which.

Agents often have multiple tools that could apply. Explicit usage 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 the tool is a write operation to a sensitive vault, is free, requires proof of ownership, and deletes without affecting other fields. This covers key behavioral aspects adequately.

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

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

The description is brief, front-loads the action, and uses clear bullet points for arguments. No unnecessary 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?

For a simple delete operation, the description covers purpose, usage, behavior, and parameters completely. An output schema exists, so return values need not be described. No gaps.

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

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

Schema coverage is 0%, so the description compensates by explaining each parameter: npub format (npub1...), dpop_token as a kind-27235 Nostr event, and field as a credential field name. This adds significant meaning beyond the raw schema.

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

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

The description clearly states the tool removes a single patron credential field, distinguishing it from sibling tools like excalibur_forget_credentials (removes all) and excalibur_update_patron_credential (updates). The verb 'remove' and resource 'patron credential field' 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?

The description specifies when to use (delete a credential field) and a prerequisite (proof of npub ownership via dpop_token). It does not explicitly list alternatives, but the sibling tools provide context. The guidance is clear enough for typical use.

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

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

With no annotations provided, the description clearly discloses the two deletion modes and that soft delete sets status='archived'. It does not cover authentication or error conditions but is adequate for the core 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?

Two sentences, no fluff. The first sentence immediately states the tool's purpose, and the second explains the parameter distinction. Efficient 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 covers the main action and parameter distinction. Missing are prerequisites (e.g., post must exist) and potential errors, but these are minor omissions 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?

The description adds significant meaning to the 'hard' parameter, explaining its effect. The npub parameter is already described in the schema (credit billing). Post_id and dpop_token lack clarification, but the key behavioral parameter is well explained.

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

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

The description explicitly states the tool deletes a stored post, with a clear distinction between soft delete (archiving) and hard delete (permanent removal). This differentiates it from sibling tools like update_post or create_post.

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

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

It explains the default behavior (soft delete) and how to perform a hard delete via the 'hard' parameter. However, no explicit guidance is given on when to use delete versus other tools like update_post for archiving.

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

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

No annotations provided, so description carries full burden. Only mentions 'Free and owner-scoped' but omits details like irreversibility, side effects, or rate limits.

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

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

Two concise sentences with no waste. Could be more structured but effective for a simple operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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. The description is adequate for a simple delete with one required param, but lacks detail on optional params.

Complex tools with many parameters or behaviors need more documentation. 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 33% (only npub described). Description adds no meaning for npub, dpop_token, or snippet_id beyond the tool action, failing to compensate for low coverage.

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

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

Description clearly states verb (delete), resource (snippets), and condition (by id). It differentiates from siblings like save_snippet, get_snippet, list_snippets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 says 'owner-scoped' implying use only on own snippets, but no explicit guidance on when to use vs alternatives or when not to use.

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

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

Provides detailed behavioral information: polling expectation, statuses (running, error with refund, expired), owner scoping, and watchdog re-kick behavior. No annotations provided, so the description carries the full burden and does so thoroughly.

Agents need to know what a tool does to the 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 focused paragraph that front-loads the core purpose, uses code formatting for readability, and every sentence adds necessary detail without fluff.

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

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

Despite an output schema existing, the description still covers return format via status examples and covers all key aspects: usage pattern, statuses, owner restriction, and watchdog behavior.

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

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

Schema description coverage is low (33%), and the description adds meaning to claim_check (source from resolve_dynamic_block) but does not explain npub or dpop_token beyond the minimal 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 verb+resource ('Redeem a resolve_dynamic_block claim check'), effectively differentiating it from its sibling resolve_dynamic_block, which creates the claim.

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

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

The description specifies that the claim_check comes from resolve_dynamic_block and that the tool is owner-scoped, but it does not explicitly exclude alternative uses or mention when not to use it.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the operation is cosmetic (non-destructive), the coupon still exists at the operator, re-redeem is possible, and it requires proof of npub. This is sufficient for this relatively simple tool.

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

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

The description is three sentences long, each providing essential information. It is front-loaded with the main action and additional details are concise and relevant. No superfluous words.

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

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

Given that an output schema exists (though not shown), the description need not explain return values. The tool's purpose is simple removal from a list, and the description covers behavior, limitations, and prerequisites. It is complete enough for an agent to use correctly.

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

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

Schema description coverage is 0%, so the description must explain parameters. It mentions npub but does not explain coupon_id or dpop_token. The names are somewhat self-explanatory, but dpop_token's purpose is unclear. The description fails to add semantic meaning beyond the schema.

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

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

The description clearly states the action ('Remove a coupon from this patron's redemption list'), which is specific and distinguishes from sibling tools like delete_coupon (which likely deletes the coupon entirely) and redeem_coupon (which adds a 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?

The description provides context: it is cosmetic only, the coupon still exists, and the patron can re-redeem later. It also mentions the requirement for npub. However, it does not explicitly state when not to use it or name alternatives like delete_coupon for permanent deletion.

Agents often have multiple tools that could apply. Explicit usage 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 crucial behavioral traits: deletion is destructive ('as destructive as a write') and requires proof of npub ownership via dpop_token. With no annotations provided, the description adequately shoulders the transparency burden by highlighting these risks.

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

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

Concise yet comprehensive: five sentences plus structured Args. Every sentence adds value—no redundancy. Front-loaded with the core action, followed by clarifying instructions. Highly efficient.

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

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

Covers essential aspects: what the tool does, how to use parameters, destructive nature, and auth requirement. With an output schema present, return values are likely covered. Missing error conditions, but overall complete enough for safe 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?

Adds meaningful context to all three parameters beyond the empty schema: explains that 'npub' can be operator or patron, 'service' is the credential service, and 'dpop_token' is a kind-27235 event. This compensates for the 0% schema description 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?

Clearly states the action 'Delete vaulted credentials' and specifies the scope 'for a specific service and npub'. Distinguishes between operator and patron credentials, providing precise context. The tool name 'forget_credentials' is distinct among siblings, and the description reinforces this uniqueness.

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

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

Provides explicit guidance on when to use operator vs. patron npub, and emphasizes the necessity of the dpop_token for proof of ownership. Although it does not directly mention alternatives, the instructions are clear enough to prevent misuse.

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

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

With no annotations, description discloses it reads public data without side effects and lists returned fields. Lacks details on error handling (invalid npub) or relay dependency, but adequately covers basic 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?

Two sentences: first defines purpose and reference, second explains cost and response. Concise, no redundant information, well-structured.

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

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

Given low complexity, one optional parameter, and output schema present, description covers enough: purpose, input, cost, and return behavior. Minor omission of error conditions, but overall 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 0%, so description must compensate. Describes 'npub' as a Nostr public key but does not specify format (bech32) or constraints. Adds some meaning but not fully detailed.

Input schemas describe structure but not intent. Descriptions should explain 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 reads a Nostr profile using an npub, specifying the resource and verb. Distinguishes from sibling tools like excalibur_publish_nostr_profile (write) and excalibur_get_x_profile (Twitter/X).

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

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

Mentions it is free and requires no proof, implying it can be used freely for public data. However, does not explicitly state when not to use or provide alternatives, leaving usage somewhat 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?

No annotations are provided, so the description carries the full burden. It describes the tool as generating a proof, which is likely a read-only operation, but it does not disclose side effects, rate limits, or authorization requirements. Basic transparency is present but could be richer.

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

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

The description is concise and well-structured: a brief sentence explaining the purpose, followed by an 'Args' section for parameters. Every sentence adds value, and the purpose is front-loaded. There is no unnecessary text.

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

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

Given that an output schema exists (documenting return values) and the tool is relatively simple, the description is mostly complete. However, it could benefit from a usage hint (e.g., 'Use after notarization') to improve context but is sufficient for an agent with sibling tool awareness.

Complex tools with many parameters or behaviors need more documentation. 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 the tool description provides brief, clear explanations for both parameters ('notarization_id' and 'npub'), adding meaning beyond the raw schema types. This helps the agent understand what values to provide, though format constraints are not discussed.

Input schemas describe structure but not intent. Descriptions should explain 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 object 'Merkle inclusion proof' are specific and distinguish it from related tools like listing notarizations or checking proof status.

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

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

The description does not explicitly state when to use this tool versus alternatives (e.g., after notarization, for verification). The context is implied but not spelled out, leaving room for confusion about prerequisites or typical use cases.

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

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

With no annotations provided, the description carries the full burden. It indicates a read-only reporting operation. The term 'Free' suggests no cost. It does not disclose authorization or error handling, but for a simple status check with no parameters, the description is fairly transparent.

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

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

The description is three sentences with no fluff. It front-loads the core purpose and immediately adds actionable detail about what is reported and when to use an alternative.

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

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

Given there are no parameters and an output schema exists, the description is complete. It effectively describes what the tool does and distinguishes from a sibling, leaving no obvious gaps.

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

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

The input schema has zero parameters, so the baseline is 4. The description adds meaning by explaining what will be reported (configured/missing settings), compensating for the lack of parameter details.

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

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

The description clearly states the verb 'report' and resource 'operator configuration readiness'. It explicitly lists what the tool shows (configured/missing settings and how to deliver) and distinguishes it from the sibling tool 'get_patron_onboarding_status' for patron-level status.

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

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

The description tells the agent when to use this tool (to check operator readiness) and explicitly points to the alternative sibling for patron-level status. However, it does not provide broader context like when not to use it or other possible 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?

Despite no annotations, the description discloses key behaviors: read-only (never exposes values), requires proof of ownership via dpop_token, is free, and notes the sensitivity of exposed field names. This fully informs the agent of behavioral traits.

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

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

Description is concise with no wasted words. Front-loads the main action and uses a clear structure with 'Args:' for parameters. Every sentence earns its place.

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

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

For a tool with 2 parameters, no annotations, and an output schema, the description is complete: covers purpose, safety, authentication, parameter details. With output schema present, return values are adequately handled.

Complex tools with many parameters or behaviors need more documentation. 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 the description adds inline parameter explanations: npub as 'The patron's Nostr public key (npub1...)' and dpop_token as 'A kind-27235 Nostr event signed by npub for this tool.' This adds significant semantic meaning.

Input schemas describe structure but not intent. Descriptions should explain 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 stored patron credential field names, explicitly noting that values are not exposed, and differentiates from siblings by focusing on credential fields. The verb 'list' and resource 'patron credential field names' 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?

Provides clear context on when to use: 'use this to verify which fields are configured.' Mentions that values are never exposed, implying proper use. Does not explicitly exclude alternatives or mention siblings, but context is sufficient.

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

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

No annotations are provided, so the description fully bears the burden. It explains that the operation is read-only, free, and requires a dpop_token for authentication. It also explains why proof of ownership is needed due to sensitivity.

Agents need to know what a tool does to the 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 summary first, then details, then parameter definitions. Every sentence adds value without unnecessary repetition.

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

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

Given the presence of an output schema, the description covers all essential aspects: purpose, usage scenarios, behavioral requirements, and parameter semantics. It is sufficiently complete for an AI agent to understand and invoke the 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?

With 0% schema coverage, the description compensates fully by defining each parameter in the Args section, including format and purpose for patron_npub and dpop_token. This adds significant meaning beyond the schema's basic type info.

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

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

The description clearly states the tool reports a patron's credential readiness for the operator, with specific details for set-once vs dynamic services. It distinguishes itself from sibling tools by focusing on readiness rather than updates or credential management.

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

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

The description explains when to use the tool (to check credential readiness) and notes that proof of npub ownership is required. It does not explicitly mention when not to use or compare to 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 states it's a read operation (non-destructive) and owner-scoped, but fails to disclose authentication requirements (npub needed), error behavior (e.g., missing post), or rate limits.

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

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

Single concise sentence front-loaded with verb and resource. Every word earns its place; no redundancy.

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

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

Output schema exists, so return values are covered. Description gives basic purpose but lacks context on npub usage, owner-scoping implications, or typical use cases. Adequate for a simple tool but could be richer.

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

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

Schema description coverage is 33% (only npub has a description). Description does not add any parameter details beyond the schema, leaving post_id and dpop_token meaning unclear. Baseline for moderate coverage is 3, but lack of compensation reduces score.

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

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

Description clearly states verb 'Read', resource 'one stored post', and scoping 'by id (owner-scoped)'. This distinguishes it from sibling tools like excalibur_list_posts (list) and excalibur_create_post (create).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 implies usage (reading a single post by ID) but does not explicitly state when to use it vs. alternatives (e.g., excalibur_list_posts) or any preconditions like authentication.

Agents often have multiple tools that could apply. Explicit usage 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 self-initialization side effect when no model exists and notes it's free. However, 'No economic data from code' is unclear, and the description does not explicitly state the tool is read-only despite having a side effect. Annotations are absent, so the description carries full burden but falls short.

Agents need to know what a tool does to the 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 covering purpose, default behavior, and an additional note. Front-loaded with main action. The third sentence is slightly cryptic but overall efficient and concise.

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

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

Given no parameters, the description covers key behaviors (free, self-initializing) and implies a read operation. An output schema exists, so explaining return values is not required. Adequate for a simple getter.

Complex tools with many parameters or behaviors need more documentation. 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 100%), and the description adds meaningful context about the tool's behavior (self-initialization, free) beyond what the schema provides. Baseline 4 for zero parameters is appropriate.

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

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

The description clearly states it retrieves the active pricing model for the operator, with specific verbs 'get' and 'active'. It distinguishes from siblings like set_pricing_model and reset_pricing_model by implying a read-only retrieval operation.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., set_pricing_model or reset_pricing_model). The description implies it's for viewing, but lacks direct differentiation or usage context.

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

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

With no annotations, the description carries the burden. It discloses scoping rules, required identity proof, and the return structure ({runs:[{run_at, summary}], scope}). It does not mention mutation effects, rate limits, or error conditions, but as a read tool, the description is sufficiently 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 efficiently structured: it starts with the main purpose, then explains details, scoping, and return format. Every sentence adds value without unnecessary verbosity.

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

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

The description covers the tool's purpose, behavior, scoping, and return structure. With an output schema present (signaled in context), the lack of explicit return format documentation is acceptable. Minor gaps (e.g., error handling) but overall sufficient 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?

Input schema covers 67% of parameters with descriptions (npub, limit). The description adds context like 'npub proof required' for npub and does not enhance the dpop_token parameter. Since the schema already provides clear descriptions for most parameters, the description adds marginal value.

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

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

The description clearly states the tool reads 'recent scheduler-tick outcomes' from process_scheduled_posts runs. It specifies the verb 'read', the resource 'scheduler log', and differentiates it from siblings by focusing on debug logging for the Worker.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 who sees what (owner sees full; proven patrons see limited) and prerequisites ('npub proof required'). It implicitly advises when to use the tool (to debug scheduler logs), though it does not explicitly mention when not to use or provide 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 burden. It discloses the operation is read-only ('Read'), free, and owner-scoped, and mentions the return format. However, it does not detail idempotency, authentication requirements (beyond npub in schema), or potential errors beyond 'snippet_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 three sentences with no redundancy. It front-loads the purpose and adds scope and return details efficiently. 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, the description adequately outlines the return shape and error. However, the gap in parameter explanation and lack of behavioral details (like idempotency) keep it from being fully complete.

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

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

Schema description coverage is low (33%). The tool description mentions 'by id' for snippet_id but does not explain npub (only described in schema) or dpop_token. It adds minimal value beyond the schema, which has a poor description for npub and none for dpop_token.

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

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

The description clearly states the verb 'Read' and the resource 'saved snippets by id', including scope ('owner-scoped' and 'Free'). It distinguishes from sibling tools like excalibur_list_snippets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 it is for reading a single snippet by ID, is free, and restricted to the owner. It does not explicitly mention when not to use it or alternatives, but the context and sibling tools make it 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, description carries full burden. Discloses empty default behavior (important), pricing model reference, and owner-scoping. Lacks details on potential error cases or permissions, but adequate 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?

Concise, front-loaded with purpose. Includes essential details on default, pricing, and scope. Slightly verbose with the chip structure explanation, but overall efficient.

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

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

Given output schema exists, description provides sufficient context: return values (profile, bans), empty default, owner-scope, pricing. Adequate for a simple read tool with many siblings; minimal risk of misuse.

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

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

Schema covers 50% of parameters (npub described as required). Description does not add meaning for dpop_token, and only reaffirms npub's role. Baseline 3 due to moderate coverage, but description missed opportunity to explain dpop_token.

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

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

Description clearly states it reads a saved writing Voice (profile blurb + banned construction chips) and distinguishes from siblings like save_voice and refine_post_region. Also explains the empty default case, making purpose unambiguous.

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

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

Mentions owner-scoped and priced (use check_price), and notes empty default instead of error. Does not explicitly state when to use vs alternatives, but context is clear for a read tool. Sibling save_voice implied for writes.

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

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

With no annotations, the description carries full burden. It discloses the technical method (calls X's /users/me), the return shape for both connected and unconnected states, and mentions it's free. It does not mention side effects, rate limits, or authentication prerequisites beyond the token, which are minor gaps.

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

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

Three sentences, front-loaded with purpose, then technical details, then concrete use case. No unnecessary words. Efficient and well-structured.

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

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

The description covers purpose, return shape, and use case. Output schema exists (not shown) which likely documents return fields further. However, it lacks explanation of how to obtain required parameters (npub, dpop_token) and does not discuss error scenarios. For a simple get tool, it is mostly complete.

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

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

Schema coverage is 50% (npub has description, dpop_token has none). The tool description does not explain either parameter; it only mentions 'vaulted X OAuth token' in prose without mapping to dpop_token. Thus the description adds no semantic value beyond the schema and 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?

Description clearly states the tool fetches the connected X account's handle and name, distinguishing it from sibling tool excalibur_get_nostr_profile which fetches Nostr profiles. The verb 'Fetch' and resource 'X account info' are specific, and the return fields are listed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 clear use case: 'Used to show the real @handle on the editor's tweet-card preview.' It implies the tool requires prior OAuth (vaulted X OAuth token) but does not explicitly contrast with alternatives like excalibur_begin_oauth or excalibur_check_oauth_status, nor state when not to use it.

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

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

No annotations are provided, so the description carries full burden. It explicitly states 'Free, no side effects' and explains the stability of tool_id vs mcp_name. This is sufficient behavioral disclosure, though absence of annotations means it could be more explicitly flagged as 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?

The description is well-structured with clear sentences, but it is slightly verbose. Each sentence adds value, but some phrases could be tightened. Overall, it is concise and front-loaded with the main purpose.

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

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

The tool has an output schema (not shown but noted), so the description need not detail return values. It adequately describes the purpose, usage, and behavioral aspects. Given the complexity of a listing tool with no parameters, the description is complete enough.

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

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

The tool has zero parameters, and the schema coverage is 100% (empty schema). The description adds no parameter details because none are needed. This is appropriate; the description focuses on the output and usage.

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

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

The description clearly states it returns canonical identities (tool_id, mcp_name) for every registered tool. It specifies the verb 'return' and the resource 'canonical identities', distinguishing it from sibling tools that deal with specific entities like posts, coupons, or snippets.

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

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

The description explicitly states it is the authoritative source for clients needing to know how the MCP identifies its tools, and mentions Reconcile uses this output for UUID-joining against a pricing model. It also warns against name-based UUID derivation, providing clear when-to-use and when-not-to-use guidance.

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

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

No annotations provided, so description carries full burden. Indicates read-only listing behavior and cost-free nature. Could mention authentication needs, but overall clear.

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

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

Three concise sentences covering purpose, returned data, and cost. No wasted words; front-loaded with key 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?

Complete for a parameterless tool with an output schema (not provided but implied). Describes return fields adequately; no gaps given simplicity.

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

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

Zero parameters with 100% schema coverage; baseline is 4. Description adds context about return values and cost, but parameter semantics are irrelevant.

Input schemas describe structure but not intent. Descriptions should explain 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 lists all available constraint types and their parameter schemas, specifying returned fields (type, category, description, parameter specs). Differentiates from siblings as no other tool lists constraint types.

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

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

Mentions 'Free — no credits required', providing a usage note. No explicit when-to-use vs alternatives, but no competing sibling exists, so clarity is sufficient.

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

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

No annotations provided, so description carries full burden. It discloses ordering (newest first), relevant data fields (times_redeemed, total_uses), and access restriction. Lacks explicit statement of read-only nature, but listing implies idempotence.

Agents need to know what a tool does to the 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, each adding distinct value: purpose+ordering, data detail, restriction. 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 one parameter and output schema existing, the description covers main purpose and usage restriction. However, it omits parameter documentation and does not guide which sibling to use vs avoid, leaving some context 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?

Only parameter dpop_token has 0% schema coverage, and the description provides no explanation for it. The description adds zero meaning beyond the schema.

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

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

Description clearly states it lists every coupon minted by the operator, ordered newest first. Verb 'list' with resource 'coupons' and scope 'operator-minted' is specific. Distinguishes from sibling tools like excalibur_list_my_coupons and excalibur_delete_coupon.

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

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

Explicitly states 'RESTRICTED to operator — requires proof,' giving clear context for when to use. However, does not mention when not to use or provide alternative sibling names.

Agents often have multiple tools that could apply. Explicit usage 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 returns both active and exhausted redemptions with status indicators, and that it is free with npub proof requirement. No annotations exist, so the description carries full burden; it covers read-only nature and result details but omits potential pagination, ordering, or other runtime behaviors.

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

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

The description is concise: two focused sentences with a valuable list of status values. Every sentence adds unique information, and the first sentence immediately conveys the tool's purpose.

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

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

Given the lack of parameter explanations and no explicit differentiation from sibling tools, the description is incomplete. Although an output schema exists and the tool is simple, the missing parameter semantics and usage guidance leave gaps for effective tool selection.

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

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

Schema description coverage is 0%, and the description does not explain the meaning of the 'npub' or 'dpop_token' parameters. It only implies npub is an identifier via 'requires proof of npub'. Without parameter descriptions, the agent gains little beyond parameter names.

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

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

The description clearly states the tool lists coupons redeemed by a patron on this operator, with specific status values. It distinguishes itself from sibling tools like 'excalibur_list_coupons' by specifying 'my' (patron-scoped) vs operator-wide listing.

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

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

The description mentions it is free and requires proof of npub, providing basic usage context. However, it does not explicitly state when to use this tool vs alternatives (e.g., excalibur_list_coupons, excalibur_redeem_coupon) or when not to use it.

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

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

No annotations are provided, so the description must convey behavioral traits. It states 'List' which implies a read-only operation, but it does not explicitly confirm idempotency, authentication needs, or side effects. The description also does not mention pagination behavior or rate limits.

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

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

The description is extremely concise: a single sentence plus bullet points for parameters. Every word serves a purpose, and the structure is clean and easy to parse.

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

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

Given the presence of an output schema (not shown), the description can omit return value details. However, it lacks information about ordering (e.g., by date descending), whether results are paginated, and the exact time range for 'recent'. These gaps reduce completeness for a list 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?

The description adds value beyond the schema by explaining the purpose of 'limit' (maximum records, default 20) and providing example values for 'status' (e.g., 'submitted', 'confirmed'). This compensates for the 0% schema description coverage. However, it does not list all possible status values.

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

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

The description clearly states the action (list) and resource (recent Bitcoin notarization records). It distinguishes itself from sibling tools like excalibur_get_notarization_proof (for a specific record) and excalibur_notarize_ledger (for creating). However, 'recent' is vague and could be more 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?

The description implies usage for listing notarizations but lacks explicit guidance on when to use this tool versus alternatives or when to apply filters like status. No when-not-to-use or 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; description fully discloses behavior: sorted, filtered, offset-paginated, return format {posts, total, page, page_size}, and per-row fields (is_recurring, has_dynamic, template_id). 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?

Slightly dense but well-structured: summary sentence followed by parameter details. Every sentence adds value, though could be slightly more compact (e.g., combine parameter explanations).

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 12 parameters and no output schema provided, description covers all key behaviors and return structure. Excellent completeness—comparable to high-quality API documentation.

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

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

Schema coverage only 8%; description compensates by explaining all key parameters: status (comma-separated set), sort_col/sort_dir, search (regex), date_from/to with date_field, template_id, page (0-indexed), page_size (1-100). Adds meaning 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 'List your stored posts' and details server-side sorting, filtering, and pagination. Distinguishes from siblings like get_post (single) and create_post (write).

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

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

Does not explicitly list when not to use, but thoroughly describes filtering options (status, search, date, template) so agent can infer appropriate context. Could add note about alternatives like get_post for single posts.

Agents often have multiple tools that could apply. Explicit usage 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 server-side sorting, filtering, pagination, return format, and scope ('Free, owner-scoped'). This is thorough and provides necessary behavioral context.

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

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

The description is concise (4 sentences) and well-structured: first sentence states purpose and general behavior, then lists parameter details in a compact format. Every sentence adds information without redundancy.

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

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

Given 10 parameters, no annotations, and an output schema, the description covers all key aspects: input parameters, defaults, valid ranges, and return shape. It is self-contained and sufficient for an agent to use correctly.

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

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

Despite low schema description coverage (10%), the description explains nearly all parameters: sort_col values, sort_dir, search regex, date_from/date_to format and inclusivity, page index, page_size range, and date_field options. It adds significant value beyond the schema, though it omits npub and dpop_token semantics.

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

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

The description clearly states the tool lists saved post snippets with sorting, filtering, and pagination. It uses specific verbs and parameters (e.g., 'list', 'sorted', 'filtered', 'offset-paginated') and distinguishes from sibling tools like get_snippet, delete_snippet, and save_snippet.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (listing snippets with advanced querying) and implicitly contrasts with single-snippet tools (get_snippet) and mutation tools (save/delete). It could explicitly mention not to use for retrieving a single snippet, 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?

With no annotations, the description carries full behavioral disclosure burden. It explains the creation behavior, return of new coupon row, operator restriction, and parameter specifics like uniqueness and defaults. Minor omission: does not describe error behavior on duplicate name or other failures.

Agents need to know what a tool does to the 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 heading, bullet-like Args listing, and a returns line. It is front-loaded with the purpose. Slightly lengthy due to parameter descriptions, but each sentence adds value. Could be more concise by omitting redundant parameter name repetition.

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

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

For a creation tool with an output schema, the description covers auth requirements, parameter constraints, and uniqueness. It does not explicitly mention error handling or idempotency, but overall provides 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?

Despite 0% schema description coverage, the description provides detailed explanations for all 7 parameters, including the unique constraint on name, percentage range, ISO-8601 format for dates, and defaults for uses_per_patron and total_uses. This adds substantial meaning beyond the schema.

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

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

The first line clearly states 'Create a new operator-owned discount coupon.' Verb 'create' and resource 'operator-owned discount coupon' precisely define the action. Among sibling tools, this uniquely identifies the creation function, distinguishing it from update, delete, and list 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 explicitly states the tool is 'RESTRICTED to operator' and requires specific authentication (nsec-signed kind-27235 or cached dpop_token). This provides clear context on when to use it. However, it does not explicitly mention when not to use it or suggest alternatives like update_coupon for existing coupons.

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

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

No annotations are provided, so the description bears full responsibility. It discloses the task is a background operation, free, and takes 1-6 hours, but does not explain side effects (e.g., irreversibility, multiple calls) or the exact nature of the return (though output schema may cover that). More behavioral details would improve 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 extremely concise: three sentences, front-loaded with the primary action, and every sentence adds value (action, operator/background context, timing, cost). 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 moderate complexity (blockchain interaction) and existence of an output schema (which can explain return values), the description covers key points: what it does, who can use it, timing, and cost. It lacks prerequisites (e.g., being an operator) but 'Operator-only' implies the caller must be authenticated as an operator. Slightly incomplete, but adequate.

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

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

There are no parameters (0 params, 100% schema coverage). The baseline for 0 parameters is 4, and the description does not need to add parameter info, which it correctly avoids.

Input schemas describe structure but not intent. Descriptions should explain 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 its root to Bitcoin via OpenTimestamps. It uses a specific verb ('Build', 'submit') and resource ('Merkle tree', 'root to Bitcoin'), and distinguishes from sibling tools like excalibur_get_notarization_proof and excalibur_list_notarizations which are queries, not 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?

Description specifies it is an 'Operator-only background task' and mentions 'Bitcoin confirmation takes 1-6 hours', providing clear context for when to use it. However, it does not explicitly state when not to use or list alternatives, but given the unique operation, the context is sufficient.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It only states 'Free,' which could imply no cost but does not confirm read-only behavior, idempotency, speed, or lack of side effects. The absence of parameters suggests it is a simple query, but this is not explicitly stated.

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

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

The description is extremely concise (two short phrases). It front-loads the core action ('Describe the DPYC ecosystem') and adds one additional token ('Free'). No unnecessary words are present, though the brevity sacrifices helpful 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?

Despite having an output schema (capturing return values), the description lacks context about what aspects of the ecosystem are described (e.g., overview, stats, key features). It does not differentiate from sibling oracle tools that also describe parts of the ecosystem, nor does it clarify the scope or format of the output.

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

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

The input schema has zero parameters, so the description does not need to explain parameter usage. It adds no parameter-specific information, but given 100% schema coverage (no params to cover), a baseline of 4 is appropriate.

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

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

The description uses a specific verb ('Describe') and resource ('DPYC ecosystem'), and the 'via the Oracle' phrasing distinguishes it from sibling oracle tools like 'excalibur_oracle_how_to_join' (which explains joining) and 'excalibur_oracle_network_advisory' (which gives advice). It is not a tautology and clearly indicates the tool provides an overview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 offers no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when to prefer 'oracle_about' over other oracle tools (e.g., for specific queries vs. general overview), or when not to use it. The word 'Free' is ambiguous and 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?

With no annotations, the description carries the full burden. It adds 'Free' indicating no monetary cost, but does not explicitly state that it is a read-only, non-destructive operation. The behavior is simple, but the description falls short of fully disclosing side-effect-free nature.

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

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

The description is extremely concise with two words for purpose and one word for cost. Every part earns its place; no wasted words. It is front-loaded and clear.

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

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

With zero parameters and an output schema available, the description is nearly complete. It identifies the resource (DPYC certification tax rate) and hints at cost. Could marginally improve by noting public access or read-only nature, but adequate for this 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?

Zero parameters mean schema coverage is 100% trivially. Baseline is 4 per rules. No param information needed; the description does not add nor need to add parameter semantics.

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

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

The description clearly states 'Get the current DPYC certification tax rate' – a specific verb and resource. It distinguishes from sibling tools by targeting a unique entity (tax rate) not covered by any other excalibur 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?

No guidance on when to use this tool versus alternatives. The word 'Free' hints at no cost but does not specify context or prerequisites. Sibling tools like excalibur_check_price or excalibur_check_balance exist but there is no differentiation.

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

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

No annotations are provided, and the description is minimal. It does not disclose any behavioral traits such as side effects, permissions, rate limits, or return format beyond the implicit 'free'.

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

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

The description is extremely concise: one sentence plus 'Free.' Every word serves a purpose, and it is front-loaded.

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

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

Given no parameters and the existence of an output schema, the description is adequate but could be more complete by explaining what DPYC stands for or summarizing the output content.

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

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

No parameters exist, so description adds nothing beyond the schema. Baseline of 4 is appropriate for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain 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 'DPYC onboarding instructions', and the source 'from the Oracle'. This distinguishes it from sibling tools like excalibur_oracle_about or excalibur_oracle_lookup_member.

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

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

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

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

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

No annotations provided. The description only adds 'Free', but does not disclose side effects, permissions, rate limits, or error behavior. With no annotations, the description should provide more behavioral context.

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

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

The description is two short, front-loaded sentences. No unnecessary words or redundant information. Efficient and to the point.

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

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

Given the tool's simplicity (one parameter, has output schema), the description is adequate but minimal. It does not explain what a DPYC community member is or provide context for the output. Could be more informative without being 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 0%, so the parameter 'npub' has no description. The tool description mentions 'by npub' but does not explain the format, constraints, or examples. The meaning is insufficiently conveyed.

Input schemas describe structure but not intent. Descriptions should explain 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 tool looks up a DPYC community member by npub. The verb 'look up' and resource 'DPYC community member' are specific. The sibling tools include other oracle lookups (e.g., excalibur_oracle_about) but this one is distinct in 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 guidance on when to use this tool over others, such as excalibur_get_nostr_profile or other oracle tools. Description lacks context for appropriate usage.

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

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

With no annotations provided, the description bears the full burden but only states the action and cost. It omits key behavioral traits such as authentication requirements, rate limits, or what the advisories contain. This is insufficient for a no-annotation tool.

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

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

The description is extremely concise (two sentences) and front-loaded with the primary purpose. Every word serves a purpose, with 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?

Despite having an output schema, the description provides no context about what 'network advisories' entails, whether they are time-sensitive, or how to interpret the response. The lack of behavioral and usage details makes it incomplete 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?

There are no parameters (schema coverage 100% with an empty object), so the baseline is 4. The description does not need to add parameter meaning.

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

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

The description clearly states the verb 'Get' and the resource 'active network advisories from the Oracle', making the purpose specific and distinct from sibling tools. No parameter details are needed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 mentions 'Free' but provides no guidance on when to use this tool versus alternatives. There is no context for eligibility, prerequisites, or comparison with other oracle tools.

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

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

The description discloses the markdown-to-Unicode conversion behavior but omits side effects (e.g., irreversibility), authentication requirements (beyond npub), or rate limits. With no annotations, the description partially carries the burden but leaves gaps.

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

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

The description is well-structured with a clear header, markdown examples, and parameter list. It is slightly verbose due to the table but remains readable 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 (not shown), the description does not need to detail return values. It adequately covers the tool's purpose and key parameters, though it could mention any returned tweet identifier.

Complex tools with many parameters or behaviors need more documentation. 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 explains 'text' (tweet content) and 'npub' (credit attribution), but fails to mention 'dpop_token' present in the schema. Schema coverage is low (33%), and the description compensates for two of three parameters, missing one, resulting in a partial 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 explicitly states it posts a text tweet with markdown-to-Unicode conversion, clearly distinguishing from sibling tools like excalibur_post_tweet_image. The verb 'post' and resource 'tweet' are precise, and the markdown conversion detail adds specificity.

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

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

The description implies usage for text-only tweets but does not explicitly contrast with alternatives like excalibur_create_post or excalibur_post_tweet_image. No guidance on when not to use or required prerequisites (e.g., authentication) is provided.

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

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

No annotations provided, so description carries full burden. It discloses that image_url is fetched and attached, banner_svg is rendered to PNG, and npub is for credit attribution. It does not mention side effects or rate limits, but the core behavior is transparent.

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

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

The description is well-structured, starting with the main purpose and then detailing parameters in an Args section. It is mostly concise, though the Args section partially repeats schema info. No filler sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 and the presence of an output schema, the description covers key behaviors and parameters adequately. It could mention error scenarios or prerequisites but is complete enough for an agent to use correctly.

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

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

Schema coverage is only 20% (one param described). The description adds meaning: explains that text supports markdown, image_url is fetched, banner_svg is rendered to PNG, and npub is for credit attribution. This compensates well for low schema coverage, though dpop_token remains unexplained.

Input schemas describe structure but not intent. Descriptions should explain 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 posts a tweet with a hero banner image to X/Twitter, using either an image URL or SVG. It distinguishes from sibling tools like 'excalibur_post_tweet' (likely text-only) and 'excalibur_create_post' (likely creating without publishing).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 each parameter (image_url vs banner_svg) and mentions the same markdown formatting as 'post_tweet', implying its alternative. However, it does not explicitly state when not to use this tool (e.g., for text-only tweets).

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

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

Even without annotations, the description fully discloses side effects: billing the owner for post_tweet, stamping last_sent_at, handling recurrence/retirement, and the requirement for operator npub proof. It also mentions the trigger is free and returns a detailed counts object.

Agents need to know what a tool does to the 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 well-structured sentences. The first sentence states the core action, and the second details the process, constraints, and return value without unnecessary 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?

For a tool with moderate complexity, the description covers the complete lifecycle of scheduled post publishing, including billing, timestamping, recurrence logic, and operator authorization. The presence of an output schema reduces the need to describe return values, and the description fills all other gaps.

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

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

The description reinforces the npub parameter as 'operator's npub proof', but the dpop_token parameter is completely undocumented in both schema and description. With only 50% schema coverage, the description does not compensate for the missing parameter info.

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

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

The description clearly states the tool publishes due scheduled posts and explains the process step-by-step. It also identifies itself as operator-only, distinguishing it from other posting tools like excalibur_create_post or excalibur_post_tweet.

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

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

The description specifies this tool is operator-only and intended for processing scheduled posts, providing solid context for when to use it. However, it does not explicitly mention when not to use it or point to alternative tools for non-scheduled posting.

Agents often have multiple tools that could apply. Explicit usage 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 wheel never stores nsec, the frontend signs the event, and the wheel verifies the signature before relaying. It explains the authorization model (signature as proof) and mentions the service is free. This is thorough for a publish tool, though it omits potential failure modes or error handling.

Agents need to know what a tool does to the 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 that states the core purpose, followed by a concise explanation of security model and parameter listing. It is front-loaded and every sentence adds value, though the security explanation could be slightly shortened without losing meaning.

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

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

Given that an output schema exists (context signals indicate `has output schema: true`), the description appropriately focuses on input and behavior. It covers all necessary information for an agent to invoke the tool correctly, including the security model, parameter meanings, and the verification process. No critical gaps are evident.

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

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

The schema has 0% coverage, but the description compensates by clearly defining both parameters: `npub` as the public key the event must be signed by, and `signed_event` as a JSON-encoded, client-signed kind-0 event. This adds essential semantics beyond the schema's default values and type definitions.

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

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

The description clearly states the tool's action ('Publish a CLIENT-SIGNED kind-0 profile') and the target resource ('for an npub'). It distinguishes itself from sibling tools like `excalibur_get_nostr_profile` by emphasizing client-signing and publishing, making the purpose specific and unambiguous.

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

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

The description explains when to use the tool: when a client has signed a kind-0 event and wants to publish it. It implicitly rules out use cases where the wheel holds private keys (explicitly stating it never holds an nsec). However, it does not explicitly contrast with alternatives like `excalibur_get_nostr_profile` or list prerequisites, though the context is clear from the description.

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

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

No annotations provided, so description carries full burden. Discloses creation of a Lightning invoice (write operation), required dpop_token for proof, and that it's free. Does not mention any destructive behavior or side effects, which is appropriate.

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

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

Compact yet complete: a one-line summary, three-line workflow, and clear Args section. No redundant sentences; every part serves a purpose.

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

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

Given the tool's complexity (3 params, output schema exists), the description covers the workflow and parameters adequately. Does not describe return value, but output schema covers that. Minor lack of error handling details 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 coverage is 0%, so description fully explains each parameter: npub as 'Nostr public key', dpop_token as 'kind-27235 Nostr event', amount_sats as 'Satoshis' with default 1000. Adds meaning beyond schema's type-only info.

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

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

Clearly states 'Buy credits via Bitcoin Lightning' and 'Creates a Lightning invoice.' The verb 'buy' and resource 'credits' are specific. Among many siblings, no other tool duplicates this function, so it stands out.

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

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

Provides explicit steps: 'Pay it with any Lightning wallet, then call check_payment to confirm.' Mentions prerequisite 'Proof of npub ownership' and that it's free. Does not explicitly contrast with alternatives but context is clear.

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

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

No annotations provided, so description carries full burden. Describes one-shot retrieval, relay drainage, deletion of wrong DMs with NACK, acceptance of first match, and credential_card path. Fully transparent about 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?

Well-structured with intro, condition, details, and parameter list. Front-loaded with purpose. Slightly lengthy but each part adds value; the 'Free.' at end is minor extraneous.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 0% schema coverage and no annotations, description covers all necessary aspects: flow, two paths, behavior on mismatch, reinitialization. Output schema not described per rules, but complete for tool usage.

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

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

Schema coverage is 0% so description must compensate. Every parameter is explained with purpose and usage notes (e.g., dpop_token not needed for credential_card path). Adds significant meaning beyond the schema.

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

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

Clearly states the tool picks up credentials from Secure Courier and completes the CREDENTIAL-DELIVERY flow. Distinguishes from sibling tool receive_npub_proof by mentioning it as the ownership-proof counterpart.

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

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

Explicitly states to call only after user confirms reply and warns against polling/looping/retrying. Context is clear, but no explicit when-not-to-use or alternative tools beyond the one mentioned.

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

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

With no annotations, the description fully discloses behavior: deterministic one-shot retrieval, drains only pinned relay, stops at matching DM, deletes mismatched DMs without revealing phrase, and explains the security model (signed DM proves ownership, token stored as hash).

Agents need to know what a tool does to the 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 sections, but it is somewhat lengthy. However, it is front-loaded with the main purpose and uses clear formatting. Minor improvement possible.

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

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

Given the complexity of the flow (multi-step, relay interaction, security considerations), the description is complete: covers when to call, what happens, side effects, and output. An output schema is present, but the description still explains return value.

Complex tools with many parameters or behaviors need more documentation. 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, but the description explains both parameters: patron_npub is the patron's npub, dpop_token is the token from request_npub_proof, adding essential meaning beyond the schema.

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

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

The description clearly states the tool receives npub ownership confirmation from a patron, specifies it completes the npub-OWNERSHIP-PROOF flow, and distinguishes it from the sibling tool receive_credentials.

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

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

The description provides explicit usage guidelines: call only after user confirms reply, do not poll/loop/retry, and contrasts with receive_credentials.

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

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

With no annotations, description discloses key behaviors: lookup, validation, recording, idempotency, free usage, and requirement for npub proof. Does not detail failure modes or specific validation errors, but covers main 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?

Five sentences with no redundancy. Front-loaded with core purpose, followed by technical details. Every sentence adds value.

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

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

Given the presence of an output schema (not shown) and sibling tools, description covers purpose, behavior, idempotency, and cost. Minor gap in parameter explanation for dpop_token, but overall sufficient for correct 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?

Schema coverage is 0%, description explains 'code' as the operator-shared name and associates 'npub' with proof requirement. However, the optional dpop_token parameter is not mentioned, leaving its purpose unclear.

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

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

Description clearly states 'Claim a coupon by its name', specifies the operation as redemption with validation and recording. It distinguishes from sibling tools like mint_coupon, list_coupons, delete_coupon, forget_coupon by focusing on claiming an existing 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?

Description implies usage for claiming coupons and mentions subsequent auto-application of discount, but does not explicitly state when not to use or name alternatives. Provides context on idempotency and free nature, 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 carries the full burden of behavioral disclosure. It reveals that the operation is server-side, the Anthropic key stays secure, AI costs are metered and potentially refundable, and the output is a JSON with suggestions. It doesn't mention rate limits or error handling, but for a suggestion-based tool, this 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 well-structured: it starts with the core purpose, then explains the server-side key handling, lists parameters in a clear 'Args' section, and ends with output and billing details. It is front-loaded with the most important information. While it could be slightly more concise by reducing redundancy with the schema, it is generally efficient.

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

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

Given the complexity (7 parameters, output schema exists), the description is fairly complete. It covers inputs, output format, and billing/refund policy. It could elaborate on error cases or required auth (npub is mentioned but not fully explained), but it provides enough context for an AI agent to use the tool effectively.

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

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

Although the input schema has only 14% description coverage (only npub documented), the description's 'Args' section explicitly explains each parameter: region, full_text, instruction, voice, bans, and npub, including their purpose and optionality. This compensates well for the schema gaps, adding significant meaning beyond the raw schema.

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

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

The description clearly states the tool's purpose: 'Refine a flagged region of a post with Claude — server-side.' It specifies the verb (refine) and resource (flagged region of a post), and it distinguishes this from sibling tools like create_post or update_post by its specific refinement function and server-side key handling.

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

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

The description provides clear context on when to use the tool: to refine a flagged region with optional instructions, voice, and bans. It also explains the billing mechanism and refund policy. However, it does not explicitly state when not to use it or contrast it with alternatives, missing some guidance for agent decision-making.

Agents often have multiple tools that could apply. Explicit usage 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 discloses key behaviors: restricted to operator, requires npub proof, resolves endpoint, mints proof, delivers MCP-to-MCP. It does not detail error scenarios or side effects.

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

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

Description is detailed but well-structured with paragraphs and bullet points. Slightly verbose but clear and front-loaded with key purpose.

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

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

Given an output schema exists (not shown), description does not need to cover return values. It covers the full flow, parameters, and next steps (poll adoption_status). Complete for a request 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 includes an Args section explaining each parameter (authority_npub, dpop_token, service_url, note), adding essential meaning beyond the schema.

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

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

Description clearly states the tool's purpose: requesting adoption of an operator by an Authority, using a deferred courtship metaphor. It distinguishes from siblings like 'adoption_status' which polls for 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?

Description explains the process and suggests polling 'adoption_status' for progress, but lacks explicit when-to-use vs alternatives or conditions to avoid.

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