excalibur-mcp

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

With no annotations, the description carries the burden. It discloses key behaviors: it is free (no credits consumed), requires proof of npub ownership to prevent scraping, and returns specific data. It does not explicitly state read-only behavior, but the content and the return-value description strongly imply 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?

Five sentences, each with a clear role: what it does, what it returns, what it is not, cost, and auth requirement. Front-loaded with the primary verb and object; no fluff or 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 tool's moderate complexity and the rich input schema plus output schema, the description covers the essential context: purpose, return contents, exclusion of tax balance, cost, and authentication. It is complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema thoroughly documents all parameters (days, npub, dpop_token) including detailed dpop_token format and requirements. The description adds contextual flavor (e.g., 'proof of npub ownership') but does not add parameter-level semantics 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 uses a specific verb ('Generate') and resource ('patron's account statement'), and clearly lists what's included (purchase history, credit tranches, per-tool usage, daily logs). It also distinguishes itself from related tools by explicitly stating it is the patron's spending account, not the operator's Authority tax balance.

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

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

It gives clear context by contrasting with the Authority tax balance, implying when this statement tool is appropriate versus a balance-checking tool. However, it does not name alternative tools explicitly, so it stops short of full when/when-not guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses significant behaviors: it costs 1 api_sat per call, and proof is verified by debit_or_deny before cost is incurred. It also describes the content of the SVG (balance hero, metrics cards, health gauge, tranche table, tool usage breakdown). While it doesn't detail error cases or rate limits, the most important behavioral traits (cost and verification flow) are clearly communicated.

Agents need to know what a tool does to the 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 exceptionally concise: two sentences that front-load the core purpose, followed by a compact list of return contents and cost/proof details. Every sentence earns its place, and there is zero fluff or repetition. It serves as a model of efficient, informative tool documentation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 (generates an SVG, incurs a cost, requires proof verification), the description covers all critical aspects: what it produces, how it relates to the sibling data tool, the cost, and the verification step. The output schema is separate, so return-value details are already available. The description is complete for an agent to decide when and how to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the input schema already thoroughly documents all three parameters (days, npub, dpop_token) with detailed descriptions. The tool description itself does not add parameter-level semantics beyond what the schema provides. Per the scoring guide, a baseline of 3 is appropriate when schema coverage is high and the description doesn't need to compensate.

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

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

The description starts with a specific verb and resource: 'Generate a visual SVG infographic of your account statement.' It clearly distinguishes from the sibling excalibur_account_statement by stating it returns the same data but rendered as an SVG graphic. This makes the tool's purpose immediately clear and differentiates it from the likely data-only variant.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 references the sibling tool excalibur_account_statement, saying 'Returns the same data as account_statement, rendered as a dark-themed SVG graphic.' This implies when to use this tool (when a visual infographic is needed) versus the alternative (raw data). It also provides practical usage context by mentioning the cost and proof verification. However, it doesn't explicitly state exclusions or conditions when not to use the tool.

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

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

Given no annotations, the description must disclose behavior. It mentions 'free' and 'polls the Authority MCP-to-MCP' and lists possible statuses (pending/approved/rejected/provisioned). However, it does not discuss idempotency, permissions, or whether the operation is read-only.

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

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

The description is concise with three sentences and a bullet list. The main purpose is front-loaded. However, it could be slightly more structured by adding 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?

Despite having an output schema and only 2 parameters, the description lacks essential context: no parameter descriptions, no authentication requirements, no explanation of the polling behavior or expected response format. The tool's purpose is clear but incomplete for reliable agent usage.

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

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

Schema parameter coverage is 0%, and the description does not explain any parameters. 'authority_npub' is implied by 'chosen Authority' but not explicitly described, and 'dpop_token' is entirely omitted. This is a critical gap.

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

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

The description clearly states the verb 'check', the resource 'operator's adoption-request status', and the scope 'at a chosen Authority'. It distinguishes from siblings like excalibur_request_adoption and 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?

The description implies usage (checking adoption status) but does not provide explicit when-to-use or when-not-to-use guidance, nor mentions alternatives among the many sibling tools.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that the tool is free, requires proof of npub ownership, and explains the anti-DOS rationale. It also clarifies that a 'pending' check_oauth_status does not indicate a lapsed session. These details go well beyond a basic function statement and provide security-conscious 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 well-structured and front-loaded with the purpose. It contains several sentences of necessary guidance (flow, security, usage conditions). While slightly verbose, each sentence earns its place and avoids redundancy. It is not excessively long for the complexity of the OAuth flow.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 an OAuth flow and the presence of an output schema, the description is remarkably complete. It covers the authorization URL, the follow-up step, cost, security/privacy considerations, and when to invoke the tool. The mention of 'upstream_auth_refresh_needed' and the pending-status caveat addresses edge cases, making this fully sufficient for an agent to use correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no new details about parameter syntax or semantics beyond what the schema already documents. It mentions using the 'same npub' but the schema already defines both parameters comprehensively. The description does not need to compensate, thus a 3 is appropriate.

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

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

The description opens with a clear action verb and resource: 'Start the OAuth2 authorization flow.' It unambiguously states the tool's primary function and distinguishes it from the related 'check_oauth_status' by explaining the sequential relationship. This exceeds a vague purpose statement and clearly differentiates from sibling tools.

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

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

The description provides explicit when-to-use and when-not-to-use instructions: 'Do NOT call this pre-emptively... attempt the live tool call first and only begin OAuth when it fails with upstream_auth_refresh_needed.' It also names the alternative (check_oauth_status) and explains the completion flow, offering strong guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a critical behavioral trait: when the balance reaches zero, patron top-ups cannot be certified and the operator must call purchase_credits. It also notes the operation is free. However, it does not explicitly state that it is read-only, though the verb 'check' 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 extremely concise, consisting of four sentences, each adding essential information. The first sentence states the high-level purpose, the second describes the return value, the third explains the consequence of a zero balance, and the fourth clarifies ownership. No wasted words.

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

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

Given the tool has no parameters and an output schema exists, the description provides sufficient context: it explains the return value (sats available), the significance of the balance, and the next step if zero. It could marginally improve by explicitly stating it is a read-only operation, but overall it is complete.

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

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

There are zero parameters, so the baseline is 4. The description does not need to add parameter information since none exist. It correctly avoids mentioning parameters.

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

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

The description clearly states the tool checks the operator's tax balance at the Authority, specifying it returns sats available for certifying patron credit purchases. It distinguishes itself from sibling tools like excalibur_check_balance by explicitly noting this is the operator's own funding, not a patron balance.

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

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

The description explains when to use this tool: to check sats available for patron credit certification. It also provides guidance on what to do when the balance reaches zero (call purchase_credits). However, it does not explicitly mention when not to use it or provide alternatives, leaving some room for improvement.

Agents often have multiple tools that could apply. Explicit usage 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 and does so well: it discloses that the operation is free, requires proof of npub ownership, and explains the security rationale against enumeration. This goes beyond a simple read operation and gives the agent actionable behavioral expectations.

Agents need to know what a tool does to the 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 compact and front-loaded: one line for the core action, then a clarifying distinction, then cost and auth constraints. No filler or redundant repetition of schema details.

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

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

Given the output schema exists and the operation is a simple balance check, the description covers all essential context: what the balance is, which sibling tool to use for the other balance type, cost, and authentication. No critical gaps remain.

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

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

Schema coverage is 100% and both parameters have detailed descriptions. The tool description adds the context that npub ownership proof is required, which reinforces the dpop_token's purpose, but does not substantially improve on the schema's own parameter explanations.

Input schemas describe structure but not intent. Descriptions should explain 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 opens with 'Check a patron's credit balance at this operator', naming a specific verb and resource. It immediately distinguishes this from the operator-side balance check by pointing to 'authority_check_balance', making the tool's scope unmistakable.

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

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

Explicitly states when to use this tool (patron spending balance) and when not to ('For the operator's own balance... use authority_check_balance instead'). It also notes the free/no-credit requirement, which helps an agent decide cost implications.

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

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

With no annotations provided, the description carries full responsibility. It discloses that the tool exposes which upstream services a patron has connected, requires proof of npub ownership, and clarifies the meaning of 'pending.' While it doesn't mention error conditions or rate limits, the provided behavioral nuances are valuable and go beyond a basic read-operation description.

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

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

The description is front-loaded with the primary purpose and then provides focused usage guidance. The second paragraph is somewhat dense but every sentence contributes critical nuance about result interpretation and fallback behavior. It is appropriately sized for the complexity of an OAuth status check.

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

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

Given the OAuth flow complexity and the presence of an output schema, the description is complete. It covers the prerequisite (begin_oauth), the required proof of npub ownership, the meaning of 'pending,' and explicit fallback logic. This gives an agent all necessary context to use the tool correctly without redundant return-type details.

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

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

Schema description coverage is 100%, with both npub and dpop_token already well-documented. The description adds a brief security context ('Proof of npub ownership is required') but doesn't further explain the parameters since the schema handles them. This matches the baseline of 3 for high schema coverage.

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

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

The first sentence clearly states the tool's function: 'Check whether the OAuth2 authorization flow has completed.' It uses a specific verb and resource, and explicitly references the begin_oauth tool to establish a clear sequence, distinguishing it from sibling tools like excalibur_begin_oauth and excalibur_session_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 provides precise when-to-use instructions: call after opening the authorization URL from begin_oauth and completing browser login. It also gives explicit exclusions and fallback logic, noting that a 'pending' result does not imply session lapsed and directing the agent to attempt the live call, falling back to begin_oauth only on an explicit upstream_auth_refresh_needed error. This is exemplary usage guidance.

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

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

With no annotations, the description carries the burden. It discloses the auth requirement ('Proof of npub ownership is required') and its purpose, plus the free cost. However, it does not mention whether the operation is read-only, any side effects, or behavior on failure/pending statuses. The 'check' verb implies read-only, but not explicitly.

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

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

The description is two short paragraphs, front-loaded with the main purpose and followed by essential usage and auth context. Every sentence earns its place with no verbosity.

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

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

Given the tool's simplicity and the presence of an output schema, the description covers the essential pieces: purpose, timing, cost, and auth. It doesn't discuss error states or return value interpretation, but those are less critical given the output schema and the 'check' semantics.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds marginal context: it links invoice_id to purchase_credits and explains the npub/dpop_token auth purpose. But it doesn't add syntax-level detail beyond what the schema already provides.

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

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

The description opens with 'Check the payment status of a Lightning invoice' — a specific verb and resource that clearly distinguishes it from sibling tools like check_balance or check_price. It leaves no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 explicitly states when to call: 'Call after paying the invoice from purchase_credits,' and provides cost context ('Free — no credits required'). It does not explicitly mention alternatives or when not to use, but the usage context is clear enough.

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

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

With no annotations provided, the description carries the full burden. It explicitly states that the operation is free ('Free — no credits required') and uses 'Preview' and 'Shows' to indicate a read-only, non-mutating behavior. This is valuable context beyond what a schema would provide, though edge cases and side effects are not detailed.

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

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

The description is three concise sentences with no fluff. The first sentence states the core purpose, the second elaborates on what is shown, and the third adds a key behavioral note about cost. Every sentence earns its place.

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

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

Given the tool's simplicity and the presence of an output schema, the description adequately covers the purpose, key behavior, and cost implications. It does not explain return values (not needed due to output schema) but provides enough context for an agent to understand when and how to use it. Missing details about parameter formats are partly covered by the schema.

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

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

Schema description coverage is 50%; tool_id and tool_kwargs have useful descriptions in the schema, but npub and dpop_token are undocumented. The description adds some context by mentioning constraint effects, which aligns with tool_kwargs usage, but it does not explain the parameters explicitly or compensate for the undocumented ones. Overall it neither enhances nor detracts from the schema.

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

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

The description clearly states the tool's purpose with a specific verb ('Preview') and resource ('the effective cost of a tool call'). It also lists what the preview includes (base cost, constraint effects like discounts, free trials, surge pricing). This distinguishes it from sibling tools like get_pricing_model, which returns the pricing model configuration rather than a call-specific cost.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 conveys that this tool is used to preview costs before making a tool call, but it does not explicitly state when to use it versus alternatives. There is no mention of exclusions or alternative tools for similar purposes. The context is clear enough for basic use but lacks explicit guidance.

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

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

With no annotations provided, the description takes on the burden. It clearly states 'Free, no side effects — does not evict the cache or touch relays,' which is valuable safety information. It doesn't explain potential edge cases like missing tokens or cache misses, but for a simple check tool the disclosed behavior is largely 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 three sentences: purpose, use-case, and safety. It is front-loaded with the main action, every sentence adds distinct value, and there is no redundant text.

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

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

Given the tool's low complexity, the description covers purpose, usage scenario, side-effect safety, and its relationship to a sibling tool. The input schema is fully documented and an output schema exists, so the description provides sufficient context for an agent to select and invoke this 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?

Schema description coverage is 100%, so the baseline is 3. The description adds minimal param semantics beyond the schema, only implying the dpop_token is used for paid calls. It does not elaborate on parameter formats or relationships beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain 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 opens with a specific verb and resource: 'Check whether a previously-cached dpop_token is still valid.' It clearly distinguishes itself from the sibling 'check_oauth_status' by stating it mirrors that tool but for the npub-proof flow, making the purpose unambiguous.

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

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

Explicitly provides usage context: 'a calling agent can ask "will my next paid call accept this dpop_token?" before burning credits on a guaranteed failure.' It also mentions the alternative 'check_oauth_status' and positions this tool as the right choice for the npub-proof flow, offering both when-to-use and exclusion guidance.

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

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

With no annotations, the description carries the full burden. It only says 'Store a new post' and returns post_id, but does not disclose potential credit charges, the need for authentication via npub, idempotency behavior, or side effects beyond storing.

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

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

The description is a single, front-loaded sentence that clearly conveys the primary action and return value. No unnecessary words.

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

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

Despite a rich schema, the minimal description omits critical context such as the need for npub for credit billing, the requirement of publish_at for scheduled posts, and idempotency via client_req_id. The output schema exists, but the description itself is too sparse for a complex creation 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 82%, so most parameters have detailed descriptions. The tool description itself adds no parameter semantics, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool stores a new post (draft or scheduled) and returns the post_id. The word 'new' distinguishes it from update_post, though it does not explicitly name sibling alternatives.

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

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

No guidance is given on when to use this tool versus alternatives like excalibur_post_nostr_message or excalibur_update_post. It does not mention prerequisites such as npub being required or that scheduled posts need publish_at.

Agents often have multiple tools that could apply. Explicit usage 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 fully discloses the cascading deletion to patron redemptions, the no-op behavior for chain steps referencing the deleted coupon, and the operator restriction. With no annotations provided, this transparency is critical and well-executed.

Agents need to know what a tool does to the 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, consisting of three short sentences. It front-loads the main action and uses additional sentences to add necessary behavioral and access context without unnecessary words.

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

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

The description covers the core functionality, side effects, and access restrictions. An output schema exists (per context signals), so return values are not needed. Minor omissions like error handling or prerequisites are acceptable given the tool's simplicity.

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

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

The description does not mention or explain the two parameters (coupon_id and dpop_token) despite 0% schema coverage. The meaning of coupon_id is implicit from the tool name, but dpop_token remains unexplained, leaving the agent with insufficient guidance.

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

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

The description clearly states 'Delete a coupon' with a specific verb and resource, distinguishing it from other coupon tools like excalibur_mint_coupon, excalibur_list_coupons, and excalibur_update_coupon. The mention of cascading behavior and operator restriction further clarifies the tool's unique role.

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

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

The description indicates the tool is restricted to operators, providing some usage context. However, it does not explicitly compare with similar siblings like excalibur_forget_coupon or state when to use this tool over alternatives, leaving some ambiguity.

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

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

With no annotations, the description carries the full transparency burden. It discloses idempotency (already-absent fields report `removed: false`), auth requirements (nsec-signed kind-27235 or cached dpop_token), and the destructive nature ('as destructive as a write'). It also explains the keyed-on-vaulted behavior, going well beyond a minimal statement.

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

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

The description is front-loaded with a clear purpose, then uses exactly four additional sentences to cover distinctions, use cases, edge cases, auth, and destructive warnings. No filler — every sentence earns its place.

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

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

Given the tool's complexity (destructive, auth-gated, field-level vs row-level), the description addresses all critical aspects: what, when, auth requirements, idempotency, and return behavior (`removed: false`). Since an output schema exists, return-structure details are unnecessary. It is thorough for both new and returning agents.

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

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

The schema already describes both parameters at 100% coverage, so the baseline is 3. The description adds extra semantic nuance: for `field`, it clarifies that stored-but-untemplated fields are first-class and deletion is keyed on what is vaulted, not template declarations. For `dpop_token`, it details accepted proof types and rejects patron proofs. This pushes it above baseline, though not to a 5 since it doesn't provide exhaustive parameter syntax.

Input schemas describe structure but not intent. Descriptions should explain 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 opens with 'Remove a single operator secret field' — a specific verb and resource that clearly differentiates it from `forget_credentials` (which wipes the whole row) and other siblings. The focus on field-level deletion and the use-case example make the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 it is the 'field-level counterpart to forget_credentials' and gives a concrete scenario (retiring a leftover after an SDK cutover) where this tool is preferred over full re-delivery. Also notes that patron proofs are rejected, which sets the audience boundary.

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

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

No annotations are provided, so the description carries the full burden. It discloses that this is a write to a sensitive credential vault, requires ownership proof, is free, and does not affect other fields. This is solid behavioral transparency, though it omits details like error handling or 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?

Two sentences, each earning its place: the first states the purpose, the second adds scope, cost, and authentication requirements. Front-loaded and free of fluff.

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

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

The description covers purpose, side-effect scope, cost, and a key prerequisite. The presence of an output schema covers return values. For a simple single-field delete, this is adequately complete, though it could mention irreversibility or what happens if the field does not exist.

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

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

The input schema has 100% description coverage for all three parameters, so the description adds no additional parameter-level meaning. It indirectly references the dpop_token requirement but does not explain any parameter beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with 'Remove a single patron credential field' – a specific verb and resource. It clarifies scope ('Deletes one field... without affecting other fields') and explicitly uses 'patron' to distinguish from sibling tools like delete_operator_credential.

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

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

The description implies when to use (removing a single field) and includes a prerequisite ('Proof of npub ownership is required'), but does not mention alternatives or exclusions. Sibling tools like delete_operator_credential and forget_credentials are not referenced, leaving the agent to infer the correct choice from the name alone.

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

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

No annotations provided, so description carries full burden. It discloses the core behavioral difference between soft and hard delete, but lacks details on reversibility, authentication requirements, or cascading effects. 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?

Two sentences, front-loaded with purpose, second sentence explains the key parameter. No unnecessary words. Efficient and clear.

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

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

Given the availability of an output schema, return values are covered. However, the description omits authentication context (despite 'npub' and 'dpop_token' parameters) and prerequisites. For a delete tool, this is a moderate gap.

Complex tools with many parameters or behaviors need more documentation. 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 only 25% schema description coverage, the description is needed to explain parameters. It explains 'hard' well but does not describe 'npub', 'dpop_token', or 'post_id' beyond implication. Insufficient compensation 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?

The description clearly states the action (delete), the resource (stored post), and distinguishes between soft and hard deletion. It differentiates from sibling tools like excalibur_delete_coupon or excalibur_delete_snippet by specifying the resource.

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

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

The description explains when to use hard vs soft delete with the 'hard' parameter, but does not provide guidance on prerequisites (e.g., ownership, authentication) or alternatives (e.g., update tool). No explicit when-not-to-use info.

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

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

With no annotations, the description must disclose behavioral traits. It states the destructive nature ('Delete') and owner-scoping, but omits crucial details: whether deletion is irreversible, any side effects, permission requirements beyond npub, or error handling. The lack of annotation support makes this description insufficient.

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

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

The description is extremely concise, front-loading the action and ownership. However, it may be too brief, omitting important behavioral and parameter details. Every sentence earns its place, but more could be added without verbosity.

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

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

Despite having an output schema, the description does not explain what the tool returns (e.g., success message, deleted snippet). It lacks constraints, idempotency, and error scenarios. Given the simplicity of a delete operation, the description is incomplete for reliable agent use.

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

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

Schema coverage is only 33% (only npub has a description). The tool description does not add meaning to the snippet_id parameter beyond 'by id', nor does it clarify format or constraints. Since coverage is low, the description should compensate but fails to do so.

Input schemas describe structure but not intent. Descriptions should explain 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 (delete) and the resource (saved snippets by id). The phrase 'Free and owner-scoped' further specifies who can use it and at what cost. This distinguishes it from sibling tools like excalibur_save_snippet and excalibur_get_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 implies usage for deleting one's own snippets ('owner-scoped'), but does not explicitly state when to use this tool versus alternatives. No 'when not to use' or direct comparisons to siblings are provided, leaving the agent to infer appropriateness.

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

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

Since no annotations are provided, the description carries full burden. It discloses polling behavior, status transitions, owner-scoping, and watchdog re-kick of stalled jobs. It lacks mention of rate limits or potential side effects but covers key behavioral traits.

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

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

The description is a short, well-structured paragraph that front-loads the primary purpose and then details statuses and behavior. Every sentence adds value, with 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?

With output schema present, the description covers polling protocol, status meanings, and watchdog behavior. It is nearly complete for a polling tool, though it omits details like maximum poll intervals or timeouts.

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

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

Schema description coverage is only 33% (npub only). The description adds context for claim_check by linking it to resolve_dynamic_block, but does not explain npub or dpop_token beyond schema descriptions. It provides some added value but not full compensation.

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

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

The description clearly states the tool's purpose: redeeming a claim check from resolve_dynamic_block. It specifies it is free and proof-gated, and explicitly contrasts with the initial resolve_dynamic_block call, distinguishing it from siblings.

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

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

The description provides clear when-to-use guidance: poll with the claim_check until status is 'done'. It outlines different response statuses and mentions owner-scoping and watchdog behavior. It does not explicitly state when not to use, but the context is sufficient.

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

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

With no annotations, the description takes on full burden. It discloses key traits: cosmetic-only effect, re-redeemability, and authentication requirement. This goes beyond a simple action statement, though it omits idempotency or error handling 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?

Two sentences, no fluff. The most critical information (what it does, cosmetic nature, requirement) is front-loaded. 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 an output schema (handling return values), the description covers the effect and prerequisite for a simple mutation. It lacks mention of edge cases (e.g., coupon not in list) but is sufficient for typical use.

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

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

Schema coverage is 0%, so description must explain parameters. It only mentions npub as 'proof', ignoring coupon_id and dpop_token. This leaves significant gaps in understanding parameter purpose, especially 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 action ('Remove a coupon from this patron's redemption list') and specifies the resource and scope. It distinguishes itself from sibling tools like delete_coupon by emphasizing the cosmetic nature and that the coupon still exists.

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

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

The description provides context ('cosmetic only', 'requires proof of npub') but does not explicitly guide when to use this tool versus alternatives like delete_coupon or redeem_coupon. The usage is implied, not explicit.

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

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

No annotations are provided, so the description carries full burden. It explicitly states 'always requires proof of npub ownership' and 'a deletion is as destructive as a write', disclosing destructive and auth requirements. The detailed dpop_token schema further describes exact token requirements.

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

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

Two short paragraphs front-load the core action ('Delete vaulted credentials') and immediately follow with usage details. Every sentence provides necessary information without redundancy.

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

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

For a destructive tool with no annotations and a detailed auth parameter, the description covers what, when, and how. It explains the two credential contexts and the required proof, while the output schema presumably covers return values.

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

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

Schema coverage is 100%, so baseline is 3; description enriches npub semantics by explaining operator vs patron credential use. It also reinforces the dpop_token requirement via the 'always requires proof' note, adding meaning beyond raw 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?

Description clearly states 'Delete vaulted credentials for a specific service and npub', using a specific verb and resource. It distinguishes from generic 'delete' siblings by scoping to service/npub and explaining operator/patron variants.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage context by specifying which npub to pass for operator vs patron credentials. It doesn't explicitly mention alternatives like delete_operator_credential or delete_patron_credential, but the instructions imply it handles both cases.

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

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

With no annotations, the description carries the full burden. It discloses the read-only nature, public data source, and return fields including empty profile case. However, it does not explain handling of default empty npub or potential errors.

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

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

The description is very concise with two sentences, front-loaded with the main purpose, and every sentence adds value without redundancy.

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

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

Given the simple one-parameter tool with output schema, the description sufficiently covers what the tool does and returns. It lacks error information but is adequate for a straightforward read operation.

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

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

Schema coverage is 0%, so description must add context. It explains npub is a Nostr public key, but doesn't clarify the default empty value or expected format. More detail on the parameter's role would be helpful.

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

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

The description clearly states the tool reads a public Nostr profile for a given npub, specifies NIP-01 kind-0 metadata, and distinguishes from sibling write tools like excalibur_publish_nostr_profile and other read tools like excalibur_get_x_profile.

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

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

The description mentions that the tool is free and requires no proof, but does not explicitly state when to use it versus alternatives or exclude cases. The differentiation from siblings is implicit through naming and 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 of behavioral disclosure. It does not state whether the operation is read-only or has side effects, nor does it mention any prerequisites or error conditions. The word 'Generate' could suggest mutation, though it likely just computes a proof, leaving the safety profile unclear.

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

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

The description is a single, concise sentence that directly conveys the tool's purpose without any redundant or extraneous information. It is front-loaded 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?

The tool is relatively simple with two well-documented parameters and an output schema. However, the description omits important context such as the requirement that a notarization must already exist, and it doesn't clarify the relationship to 'request_npub_proof' or 'receive_npub_proof'. This leaves some practical gaps, though the presence of an output schema mitigates the need to describe return values.

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

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

The input schema already provides complete descriptions for both parameters (npub and notarization_id), covering 100% of the schema. The description adds no additional semantic information beyond what the schema fields already state, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: generating a Merkle inclusion proof for a patron's balance in a Bitcoin-notarized snapshot. It uses a specific verb ('Generate'), identifies the resource ('Merkle inclusion proof'), and provides context, making it distinct from sibling tools like list_notarizations or request_npub_proof.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage is implied by the name and parameter requirements (a notarization_id and npub) but not explicitly stated. It does not mention when to use this tool instead of alternatives, nor any prerequisites like an existing notarization. The description leaves the agent to infer the appropriate 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?

Although no annotations are provided, the description discloses the tool's behavior: it shows which settings are configured/missing and how to deliver missing values. This adds context beyond the name, but does not explicitly state whether it is read-only or any other traits. Given its simple nature, it is fairly transparent.

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

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

The description is three short sentences: first states purpose, second details output, third gives alternative. No fluff, every sentence earns its place.

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

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

Given no parameters and the existence of an output schema, the description sufficiently explains what the tool does and what it returns (configured/missing settings and delivery guidance). It is complete for a status 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 schema coverage is 100%. The description does not need to add parameter meaning, and the baseline of 3 is appropriate as no additional insight is required.

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

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

The description clearly states the tool 'reports configuration readiness' for the operator, specifying verb+resource. It distinguishes itself from the sibling tool 'get_patron_onboarding_status' by noting the different scope (operator vs. patron-level).

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

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

The description explicitly tells when to use this tool (for operator configuration readiness) and when not (for patron-level credential status, directing to 'get_patron_onboarding_status'). This provides clear guidance on alternatives.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It reveals that the tool is free, requires proof of npub ownership, never exposes values, and returns null delivered_at timestamps for vaulted secrets before timestamp recording—details beyond the schema and annotations.

Agents need to know what a tool does to the 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 compact and front-loaded with the main purpose. Each sentence earns its place: clarifying 'not values,' describing output timestamps, noting the free tier, and explaining the auth requirement and sensitivity. No redundancy or fluff.

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

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

Given the tool's low parameter count and the presence of an output schema, the description is remarkably complete. It covers purpose, output semantics, cost, authentication prerequisites, and the sensitivity rationale. There is no missing critical context typically needed 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?

Schema description coverage is 100%, so a baseline of 3 is appropriate. The description adds a brief note that npub ownership proof is required, which relates to dpop_token, but this is more behavioral context than parameter semantics. The schema's own dpop_token description is already highly 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?

The description opens with a precise verb and resource: 'List stored patron credential field names (not values).' It clearly distinguishes this read-only listing tool from sibling mutation tools like excalibur_delete_patron_credential and excalibur_update_patron_credential, and specifies the output scope (field names plus delivered_at timestamps).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 states an explicit use case: 'use this to verify which fields are configured and how old each one is.' It also implies a when-not by noting 'Values are never exposed,' but it does not explicitly name alternative tools for retrieving values, so it falls short of full when/when-not coverage.

Agents often have multiple tools that could apply. Explicit usage 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 states the tool is free, requires proof of npub ownership via dpop_token, and mentions that credential presence is sensitive information. It also describes the different behavior for set-once vs dynamic services. This goes beyond the schema and gives the agent a clear picture of the tool's operation.

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

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

The description is three sentences, each earning its place. It front-loads the primary purpose, then provides behavior details, and ends with cost and authentication notes. No filler or repetition of schema information.

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

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

Given the tool's simplicity (2 params, output schema provided), the description fully covers the necessary context: what it does for each service type, the cost, and authentication requirements. It does not need to explain return values because the output schema exists.

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

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

The schema already covers 100% of the parameters with descriptions, so the baseline is 3. The description adds meaningful context by explaining that dpop_token is proof of ownership and that it is required because the information is sensitive, which enhances understanding of why the parameter exists.

Input schemas describe structure but not intent. Descriptions should explain 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 opens with a clear verb and object: 'Report a patron's credential readiness for this operator.' It then differentiates between set-once and dynamic/OAuth2 services, which distinguishes it from sibling tools like excalibur_get_operator_onboarding_status and excalibur_check_oauth_status.

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

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

The description explains when the tool is relevant by distinguishing between service types, indicating that for set-once services it shows configured/missing secrets, and for dynamic services it reports no credentials needed. It also notes that proof of npub ownership is required, which is a usage prerequisite. However, it does not explicitly name alternative tools or state when not to use this tool.

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

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

No annotations are provided, so the description carries the full burden. It does not disclose whether the operation is read-only, safe, or idempotent. Error conditions (e.g., post not found) and authorization requirements beyond 'owner-scoped' are absent.

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

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

The description is a single sentence with no wasted words. However, it could benefit from brevity-relevant details (e.g., auth hint) without becoming verbose.

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

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

Given the existence of an output schema, return format is covered, but the description lacks usage guidance, behavioral disclosure, and parameter elaboration. The tool is simple, yet the description feels incomplete for an AI agent to invoke correctly in all contexts.

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

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

Schema description coverage is only 33% (npub documented). The description adds no semantics for post_id or dpop_token beyond implying post_id is the identifier. The phrase 'by id' does not clarify format or constraints.

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

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

The description 'Read one stored post by id (owner-scoped)' clearly states the action (Read), the resource (stored post), and the scope (by id, owner-scoped). It distinguishes from sibling tools like list_posts (multiple posts) and create/delete (write 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?

No explicit guidance on when to use this tool versus alternatives. The phrase 'owner-scoped' hints at access restrictions, but does not state when to choose get_post over list_posts, nor any prerequisites or limitations.

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

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

With no annotations, the description carries the burden. It discloses that data is append-only, ordered by capture time, and empty if not yet harvested. This is strong behavioral context, though it skips auth details (but 'Patron' implies ownership).

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

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

The description is concise: three sentences that front-load the purpose and add only essential behavioral details. No redundancy or filler.

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

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

With an output schema present, the description doesn't need to detail return shape. It adds ordering, emptiness semantics, and ownership, providing enough context for a simple read-only 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?

Schema description coverage is 67%, and the description adds no parameter details. The post_id is well-described in schema, but dpop_token is undocumented in both schema and description, leaving a gap.

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

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

The description clearly states the tool returns an append-only snapshot series for one owned post, listing specific fields and ordering. This specific verb+resource+scope distinguishes it from siblings like post_performance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 provides clear context: use for raw metric snapshots of one owned post, and notes that an empty result means the post hasn't been harvested yet. It doesn't explicitly name alternatives, but the context is unambiguous.

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

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

Despite no annotations, the description fully discloses key behavioral traits: it is free, self-initializes a scaffold if no model exists, and explicitly states 'No economic data from code.' This is comprehensive for a getter.

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

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

Two sentences, no filler. First sentence states purpose, second clarifies a special case. 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 zero parameters and existence of an output schema, the description covers the essential behavioral aspects (initialization, cost, data source). No further info needed for a low-complexity 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?

No parameters exist, so schema coverage is 100%. The description does not add parameter info beyond the schema, but the baseline for zero-parameter tools is 4.

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

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

Clearly states 'Get the active pricing model for this operator', which is a specific verb-noun combination. Distinguishes from sibling tools like set_pricing_model and reset_pricing_model by being the getter 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?

Implicitly clear when to use: querying the pricing model. Mentions free cost and self-initialization behavior, but does not explicitly state when not to use or list alternatives. However, the description provides enough 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 discloses key behaviors: the tool is owner-scoped, requires npub proof, and returns different data based on user role. It also describes the return structure and auth requirement ('Free; npub proof required'). No contradictory information.

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

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

The description is well-structured and front-loaded. It explains the tool's purpose, use case, scope rules, and return format. Every sentence adds value, though slightly verbose in places. Overall, it is concise for the amount of information conveyed.

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

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

The description is nearly complete for a read tool with three parameters and no output schema. It explains what the tool does, who can use it, what data is returned, and auth requirements. Sibling tool comparison is absent but not critical given the clear purpose.

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

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

The schema already covers two of three parameters with descriptions (npub and limit). The description adds context about how npub determines scope but does not elaborate on dpop_token. Given 67% schema coverage, the description provides marginal additional value beyond schema.

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

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

The description clearly states the tool reads 'recent scheduler-tick outcomes' from 'process_scheduled_posts' runs, distinguishing it from siblings like excalibur_process_scheduled_posts and excalibur_scheduler_status. It specifies the output is for debugging and shows heartbeat per tick and per-post outcomes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 debug worker behavior) and what it shows. It lacks explicit when-not-to-use or alternative tools, but the context signals and sibling list provide implicit guidance. The scope differentiation (owner vs other patrons) is clearly stated.

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

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

With no annotations, the description carries full burden. It discloses that the operation is read-only ('Read'), free, and owner-scoped. It also specifies the return format (success with snippet or error) but does not detail potential errors or side effects beyond 'snippet_not_found'. This is reasonably transparent 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?

The description is two sentences long with no redundancy. It efficiently conveys purpose, scope, and return format. 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 (indicated) and 3 parameters, the description covers core purpose and return format. However, it lacks parameter details and does not mention sibling tools or alternatives. It is functional but not fully comprehensive.

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

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

Schema coverage is only 33%, and the description does not add any extra meaning to the parameters. The snippet_id parameter lacks format details in both schema and description. The npub and dpop_token parameters are not explained beyond the schema defaults. For low coverage, the description should compensate, but it does not.

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

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

The description clearly states the tool reads a saved snippet by ID, and distinguishes it from sibling tools like excalibur_save_snippet, excalibur_delete_snippet, and excalibur_list_snippets. The verb 'read' and resource 'snippet' are specific, and the scope 'owner-scoped' adds clarity.

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

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

The description mentions 'Free and owner-scoped', implying it should be used by the owner for their own snippets. However, it does not explicitly state when to use this tool versus alternatives like excalibur_list_snippets or excalibur_get_post. No direct exclusions or scenarios 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?

With no annotations, the description carries full burden. It discloses that an empty Voice is returned if none saved, that it is owner-scoped, and that pricing applies. It does not detail authentication or error states but covers the key behavioral traits 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?

The description is three sentences long, front-loaded with the core action, and contains no verbose or redundant phrases. Every sentence adds value: purpose, return behavior, and pricing context.

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

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

Given the tool has an output schema, the description does not need to details return fields but explains the empty case and structure. It covers ownership and pricing adequately. Minor gap: no mention of error scenarios, but acceptable given output schema exists.

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

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

Schema coverage is 50% (npub has a description; dpop_token does not). The description does not add meaning for either parameter, missing a chance to explain dpop_token or clarify usage. With moderate coverage, the description should compensate but fails to do so.

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

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

The description clearly states the tool reads a saved writing Voice, including its components (profile blur and banned chips). It distinguishes from siblings like excalibur_save_voice and mentions owner-scoping and default empty return, 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 provides usage context: owner-scoped and priced via check_price. It implies when to use (when needing to read the Voice) but does not explicitly exclude alternatives or state when not to use it. The guidance is clear but lacks direct comparison with other tools.

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

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

No annotations are provided, so the description carries the full burden. It discloses the use of vaulted OAuth token, X API call, and return format including the unconnected state. However, it omits potential issues like token expiration, rate limits, or error conditions.

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

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

Three sentences, each earning its place: first states purpose, second explains mechanism and return format, third gives concrete use case. 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 low complexity and presence of output schema (return format explicitly listed), the description covers purpose, input (vaguely), mechanism, output, and use case. It lacks prerequisite guidance (e.g., OAuth must be linked) but is otherwise 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 50%: only `npub` is described as 'Required. Your Nostr public key'. The description does not clarify `dpop_token` at all, leaving it undocumented. The description fails to compensate for the missing parameter documentation.

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

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

The description clearly states the tool fetches the connected X account's handle and name, specifying the resource (X account) and the action (fetch). It distinguishes itself from siblings like excalibur_get_nostr_profile (Nostr profile) and excalibur_check_oauth_status (OAuth status check).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 tweet-card preview and mentions OAuth token, indicating a prerequisite, but lacks explicit when-not-to-use or alternatives. It does not guide the agent to check OAuth status first or compare with similar tools.

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

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

With no annotations provided, the description carries full responsibility and does so richly. It discloses the tool's draining behavior (mutating job rows), the data loss risk on missed cadence, the retry mechanism (5 attempts), dead-letter queue handling, the ability to requeue via requeue_dead_id, and the OAuth context requirement. These are significant behavioral traits beyond simple operation.

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

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

The description is compact but dense: a one-line summary, a detailed operation sentence, a failure-mode sentence, and an integration sentence. Every sentence adds critical information (scope, process, risk, retry, automation context) without fluff or 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 tool's complexity and the presence of an output schema, the description is remarkably complete. It covers the full operational flow, error handling, dead-letter queue, manual requeue option, and integration with process_scheduled_posts. No missing critical context is apparent.

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

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

Schema description coverage is 67% (npub and requeue_dead_id are described; dpop_token is not). The description adds context for requeue_dead_id as a dead-letter job UUID, but does not clarify dpop_token's purpose. This is above 50% coverage, so baseline 3 applies, with only marginal added value for parameters.

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

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

The description clearly states the tool performs a 'cadence-aware metrics harvest sweep' and details its specific actions: draining due metrics_harvest_job rows, fetching non_public_metrics/organic_metrics under OAuth context, and appending post_metrics_snapshot rows. It distinguishes itself from siblings by noting it runs as phase 3 of process_scheduled_posts, separating it from single-post metric fetchers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 marks the tool as 'Operator-only' and describes its cadence-aware batch behavior, implying when it should be used (for harvest sweeps) vs. per-post metric retrieval. It also mentions it runs automatically as phase 3 of process_scheduled_posts, giving context on manual vs. automatic usage. However, it does not explicitly list alternative tools or exclusion criteria.

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

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

Despite no annotations being provided, the description fully discloses behavior: it notes 'Free, no side effects,' explains that renamed functions change mcp_name but keep tool_id, and details the registered:false/unregistered semantics for deployment drift detection. It even references issue numbers (#174, #175) for context. This is rich behavioral disclosure that carries the entire burden absent annotations.

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

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

The description is well-structured with clear paragraphs covering purpose, consumers, canonical-UUID design, and wire-surface diffing, ending with 'Free, no side effects.' It's slightly verbose with some redundancy ('flag deploy drift' appears twice, the canonical-UUID point is reiterated), but each sentence earns its place and there's 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?

For a zero-parameter tool with an output schema present, the description is thorough. It explains the return structure (registered flags, unregistered array), the semantics of tool_id stability across renames, and the drift-detection value. Given no params to document and an output schema exists, the description fully covers what an agent needs to use this correctly.

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

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

The tool has zero parameters and 100% schema coverage (effectively empty schema, nothing to document). With 0 params, the baseline is 4. The description adds value by explaining what the output contains (registered:false, unregistered array) which orients expectations even though no parameter semantics are needed.

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

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

The description clearly states the tool returns canonical (tool_id, mcp_name, ...) for every exposed tool, which is a specific verb+resource+deliverable. It distinguishes itself from siblings by directly positioning it as the authoritative source for identity resolution, unlike list_coupons, list_posts, etc. which list domain data.

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

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

The description names concrete consumers ('Studio, agents, FE') and specific use cases ('Reconcile uses this output to UUID-join against the stored pricing model'). It explicitly states when NOT to use it ('no name-based UUID derivation, no guessing') and explains what the authoritative-canonical design solves. This gives an agent clear decision context for when this tool is the appropriate choice.

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

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

No annotations are provided, so the description carries full burden. It discloses the tool is free and does not consume credits, which is valuable beyond the obvious 'list' operation. It does not mention authentication or potential errors, but given the simplicity, this is adequate.

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

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

The description is two sentences: first states the purpose, second adds details about output. No redundant words, front-loaded for quick understanding.

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

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

The tool is simple with no parameters and an output schema. The description explains what is returned and that it is free. This is complete for a query tool of this nature.

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

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

The input schema has zero parameters, and schema coverage is 100%. The description does not need to add parameter meaning, and it briefly lists what each constraint includes (type, category, etc.), adding 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?

The description clearly states the tool lists all available constraint types and their parameter schemas, specifying what data is returned (type, category, description, parameter specs). It distinguishes itself from sibling tools by focusing on constraint enumeration for pricing pipelines.

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

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

The description indicates the tool is for listing constraints usable in a pricing pipeline, providing clear context. While it does not explicitly mention when not to use it or alternatives, there are no closely related sibling tools that might cause confusion.

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

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

With no annotations provided, the description carries full burden. It discloses ordering and the auth restriction, but does not mention read-only nature, rate limits, or other behavioral details. Adds some value beyond the name.

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

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

Three short sentences with no redundancy. Purpose, data field, and restriction are efficiently conveyed. Highly concise and well-structured.

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

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

Given the presence of an output schema, return values are not needed. However, the description lacks details on error conditions, pagination, or the meaning of 'requires proof'. For a simple list tool, it is adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. 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 only parameter (dpop_token) has 0% schema description coverage, and the tool description does not explain its purpose or usage. The description adds no value for 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?

Clearly states it lists coupons minted by the operator, ordered newest first. Provides context about the 'times_redeemed' field. However, does not distinguish from the sibling tool 'excalibur_list_my_coupons', which likely has a different scope.

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

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

Mentions 'RESTRICTED to operator – requires proof', indicating a prerequisite. No explicit when-to-use or when-not-to-use guidance, and no alternatives referenced. The constraint is noted but not elaborated.

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

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

With no annotations provided, the description carries the full burden. It discloses that both active and exhausted redemptions are returned, and explains the status field values. It also notes it is free, providing clear 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 with three sentences, front-loaded with the main action, and each sentence adds value without redundancy.

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

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

Given the presence of an output schema, the description sufficiently covers purpose, usage, behavior, and parameter requirement, providing complete context for a simple list tool.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions the npub parameter as required, but does not explain the dpop_token parameter. This partially adds meaning but lacks full parameter documentation.

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

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

The description clearly states the verb 'list' and resource 'coupons', and specifies the scope 'this patron has redeemed on this operator', distinguishing it from similar tools like 'excalibur_list_coupons'.

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

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

The description mentions the prerequisite 'requires proof of npub', which guides usage, but does not explicitly state when not to use or list alternatives.

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

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

There are no annotations, so the description has the full burden of behavioral disclosure. It only states 'List recent,' implying a read-only operation, but does not disclose scope (e.g., own records vs all), ordering, pagination behavior, authentication requirements, or any side effects.

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

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

The description is a single, front-loaded sentence that uses every word meaningfully: verb, object, and scope. No redundancy or filler.

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

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

For a simple list tool with an output schema and complete parameter schema, the description covers the core purpose but leaves gaps in usage guidance and behavioral context. It does not explain what qualifies as 'recent' or how this tool relates to other notarization lookup tools, which would be expected given the lack of annotations.

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

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

The input schema has 100% coverage: both 'limit' and 'status' have descriptions with defaults and examples. The description adds no parameter semantics, but the baseline is 3 because the schema fully documents them.

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

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

The description uses a specific verb 'List' and a clear resource 'Bitcoin notarization records,' with 'recent' scoping. This distinguishes it from sibling tools like exacalibur_get_notarization_proof, which targets a single proof, and exacalibur_notarize_ledger, which creates a record.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use guidance is provided, and no alternatives are mentioned. The description does not indicate when to choose this tool over related ones like exacalibur_get_notarization_proof or exacalibur_check_proof_status, nor any exclusions.

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

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

With no annotations provided, the description carries the full burden — and it excels. It discloses precise edge-case semantics: UTC-calendar day is end-inclusive while ISO instants impose an exclusive upper bound, status is set-membership matched, sent_hour matches local wall-hour in a timezone, and page is 0-indexed. It also reveals the filter-reflected total behavior in the return contract — substantive behavioral detail far beyond what structured fields could convey.

Agents need to know what a tool does to the 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 an excellent one-sentence summary before diving into parameter details, and every sentence earns its place given the tool's complexity. However, the body is a dense wall-of-text with minor grammatical slips ('Bound the date_field column' should be 'Bounds...'), and the sent_hour sentence crams three clauses into one long construction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 14-parameter tool with zero annotations and minimal schema help, the description is remarkably complete: it covers defaults, allowed values, edge cases, timezone behavior, and result shape across all meaningful dimensions. The output schema existing means the return value explanation is unnecessary. Minor deduction for the unaddressed dpop_token parameter and silence on pagination edge cases (e.g., behavior past the last page).

Complex tools with many parameters or behaviors need more documentation. 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 schema coverage at a paltry 7% (only npub documented), the description carries the entire semantic burden and succeeds admirably. It explains 12 of 14 parameters with exact allowed values (created|updated|status|scheduled), defaults, validation constraints (page_size 1..100, sent_hour 0-23), date-format disambiguation (bare YYYY-MM-DD vs ISO instant), and matching rules (regex, set membership, wall-hour equality). Only dpop_token is left undocumented in both schema and prose.

Input schemas describe structure but not intent. Descriptions should explain 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 opening sentence — 'List your stored posts, server-side sorted, filtered, and offset-paginated' — uses a specific verb+resource and clearly scopes the tool to user posts with rich server-side processing. It implicitly distinguishes itself from sibling list tools (list_coupons, list_snippets, list_notarizations) by resource type, though it never explicitly names alternatives or contrasts itself the way the get_calls example does.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tools are named (e.g., nothing like 'for a single post, use get_post'). However, the extensive parameter semantics strongly imply the tool's use cases (time-of-day deep-links, template filtering, date-range queries), giving clear contextual usage context without ever stating exclusions 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 carries the full burden. It thoroughly discloses behavior: server-side sorting/filtering, sort column and direction options, case-insensitive regex search, date parsing rules (including end-inclusive behavior), date field binding, pagination specifics (0-indexed page, page_size range), and the return shape. It also notes 'Free, owner-scoped,' which is useful 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 front-loaded with its primary purpose and contains dense, relevant information. However, it is a single lengthy paragraph that could benefit from bullet points or section breaks for readability. Every sentence earns its place, but the structure is slightly overwhelming.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 annotations, low schema coverage (10%), and an output schema that is not shown, the description provides a complete picture for a list operation. It covers all parameters, return shape, filtering semantics, pagination, and scope, making it quite complete for the task.

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

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

Schema description coverage is only 10% (only npub has an inline description). The description compensates fully by explaining every meaningful parameter: sort_col, sort_dir, search, date_from/date_to, date_field, page, page_size, and even mentions dpop_token indirectly as part of the auth context. It provides valid values, defaults, and semantic details like case-insensitivity and date formats.

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

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

The description clearly states the tool's function: 'List your saved post snippets, server-side sorted, filtered, and offset-paginated.' It uses a specific verb and resource, and the context of listing snippets clearly distinguishes it from sibling tools like excalibur_get_snippet, excalibur_save_snippet, and excalibur_delete_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 provides clear context on when to use the tool—for listing, searching, and paginating through saved post snippets—and adds scope details ('owner-scoped'). However, it does not explicitly name alternative tools or say when not to use it, so it lacks explicit exclusion guidance.

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

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

With no annotations, the description carries full burden for behavioral disclosure. It mentions 'operator-owned' but does not explain side effects, permissions, idempotency, or error behavior. The description is too vague for a mutation tool, providing minimal context beyond the basic action.

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

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

The description is a single, front-loaded sentence with zero wasted words. It efficiently conveys the core purpose without redundancy, making it appropriately 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?

Despite having 7 parameters and an output schema, the description is minimal and lacks critical contextual details such as ownership implications, authentication requirements, or lifecycle context. Compared to similar tools, this description under-delivers for a creation tool with no annotations.

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

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

Schema description coverage is 86%, which is high, so the baseline is 3. The description itself adds no parameter-specific details beyond what the schema already provides, so it does not exceed the baseline.

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

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

The description 'Create a new operator-owned discount coupon' clearly specifies a creation action, the resource (discount coupon), and ownership (operator-owned). It distinguishes from sibling tools like 'excalibur_update_coupon' and 'excalibur_delete_coupon' by focusing on 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?

The description implies usage via the verb 'Create' but does not explicitly state when to use this tool versus alternatives like 'excalibur_update_coupon' or 'excalibur_redeem_coupon'. It lacks explicit context about prerequisites or scenarios where this tool is appropriate.

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

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

Given no annotations, the description fairly discloses the key behavioral traits: it's a background task, Bitcoin confirmation takes 1-6 hours, and it's free. However, it doesn't mention idempotency or potential 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?

Three concise sentences with zero wasted words, efficiently conveying purpose, usage context, and cost.

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

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

The description explains the purpose, timing, and who can use it. With an output schema available, it doesn't need to detail return values, but could mention what triggers the task or if it's idempotent.

Complex tools with many parameters or behaviors need more documentation. 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 the baseline of 4 applies; the description adds no parameter info which is acceptable.

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

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

The description clearly states the tool builds a Merkle tree of patron balances and submits the root to Bitcoin via OpenTimestamps, with a specific verb and resource, distinguishing it from the many sibling tools.

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

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

It specifies it's an operator-only background task, indicating who should use it, but lacks explicit guidance on 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?

No annotations are provided, so the description must fully disclose behavioral traits. It only says 'Free', which hints at no cost but does not address side effects, authentication needs, rate limits, or whether the description is static or dynamic. This is insufficient for a tool with no annotations.

Agents need to know what a tool does to the 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 no wasted words, but it is under-specified. It could be expanded to add more clarity without becoming verbose. A sentence that explains what the output contains would improve it.

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

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

Given the tool has no parameters and an output schema exists, the description is minimal. It does not explain what the Oracle provides or what the output format is. While the output schema may fill gaps, the description should offer more context for users to understand the tool's purpose.

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

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

There are no parameters, and schema coverage is trivially 100%. The description adds no meaning beyond the schema, which already declares no parameters. A baseline of 3 is appropriate because the schema covers everything.

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

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

The description states 'Describe the DPYC ecosystem via the Oracle', which clearly indicates the verb 'describe' and the resource 'DPYC ecosystem'. However, it lacks specificity about what aspect of the ecosystem is covered, and the term 'Oracle' is not explained. It distinguishes from sibling tools like excalibur_oracle_get_tax_rate or excalibur_oracle_lookup_member, but 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?

No guidance on when to use this tool versus alternatives. Among many sibling oracle tools (e.g., excalibur_oracle_how_to_join, excalibur_oracle_network_advisory), the description provides no context for when to choose this one.

Agents often have multiple tools that could apply. Explicit usage 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 only mentions 'Free' which hints at no cost, but lacks details on read-only nature, idempotency, or any side effects. For a tool with no annotations, more behavioral context is expected.

Agents need to know what a tool does to the 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 a single sentence. Every word is meaningful and there is no extraneous content.

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

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

Given the simplicity (no parameters, simple output), the description is adequate but could be improved by stating what the tax rate is applied to or any prerequisite conditions. The mention of 'Free' adds value, but more context like 'read-only' or 'call anytime' would enhance completeness.

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

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

The input schema has zero parameters, so there is no need for parameter descriptions. According to the baseline rule for 0 parameters, a score of 4 is appropriate as the description doesn't need to add extra 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 tool's function: getting the current DPYC certification tax rate. The word 'Free' provides additional context. However, it does not explicitly distinguish this tool from sibling tools like excalibur_oracle_network_advisory or excalibur_check_price.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, typical contexts, or situations where a different tool would be more appropriate.

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

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

With no annotations provided, the description carries full burden. It only mentions the tool returns instructions and is 'Free', but does not disclose any behavioral traits like whether it requires authentication or how it behaves.

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

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

Extremely concise: 6 words in one sentence. Front-loaded with the key action and resource. 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 zero parameters and an output schema, the description adequately identifies the tool's purpose. However, it could briefly clarify what 'DPYC' stands for or what type of instructions are provided.

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

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

No parameters exist, so baseline is 4. The description adds no parameter meaning but is not required to.

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

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

The description clearly states the verb 'Get' and the resource 'DPYC onboarding instructions from the Oracle'. It distinguishes itself from sibling Oracle tools like 'oracle_about' and 'oracle_lookup_member' by focusing on onboarding instructions.

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

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

No guidelines on when to use this tool versus alternatives. The description does not mention prerequisites, context, or when not to use it.

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

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

With no annotations, the description must disclose behavior. It only mentions it's free, but omits authentication requirements, rate limits, error handling (e.g., invalid npub, member not found), and whether it has side effects.

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

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

The description is a single concise sentence, front-loaded with the core action. However, it could include additional context without becoming verbose, so it doesn't achieve absolute efficiency.

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

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

Given the tool's simplicity (one parameter, lookup), the description covers the basics. However, it lacks context on input validation, response format (though output schema exists), and edge cases. It is minimally viable but not 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 description for npub). The description merely repeats the parameter name without explaining what an npub is or its expected format (e.g., hex, bech32). This fails to compensate for the missing schema documentation.

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

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

The description clearly states the action 'Look up', the resource 'DPYC community member', the key identifier 'npub', and adds a bonus feature 'Free'. It effectively distinguishes from sibling tools like excalibur_oracle_about or excalibur_get_nostr_profile.

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

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

No guidance is provided on when to use this tool versus alternatives. With a large set of sibling tools, the agent would benefit from conditions like 'Use this for DPYC members, use excalibur_get_nostr_profile for general Nostr profiles.'

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

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

With no annotations, the description must disclose behavioral traits. It only mentions that the tool is 'Free', implying no cost, but provides no information on idempotency, side effects, permissions, or error handling. This is insufficient for informed invocation.

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

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

The description is extremely concise, consisting of two short sentences. Key information (action, resource, cost) is front-loaded with no filler. Every word earns its place.

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

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

Given the absence of parameters and the presence of an output schema, the description does not need to explain return values. However, it fails to clarify what 'network advisories' entail or how the output is structured, leaving some contextual gaps for a tool with many siblings.

Complex tools with many parameters or behaviors need more documentation. 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 schema coverage is trivially 100%. Per the baseline rule, a score of 4 is appropriate since there is no need for the description 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 the action (get) and resource (active network advisories), identifying the tool's primary function. It distinguishes from sibling oracle tools like 'oracle_about' and 'oracle_get_tax_rate', but does not define what constitutes a 'network advisory', leaving some ambiguity.

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

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

No guidance is provided on when to use this tool versus alternatives. The description lacks any conditions, prerequisites, or exclusions, forcing the agent to rely solely on the tool name and 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 and delivers exceptionally: it discloses that eXcalibur cannot sign as the user, mints an ephemeral scribe keypair, p-tags the user's npub, publishes to the DPYC relay set, and succeeds if at least one relay accepts. It also explains the response contents and the disowning ability.

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

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

The description is four paragraphs and somewhat repetitive about the author being the proven npub, but each sentence carries meaningful behavioral or contextual information. It is not bloated with irrelevant details, though a more condensed version could earn a 5.

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

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

The description thoroughly covers signing, authorship provenance, relay behavior, and the success/failure condition, which is impressive for a complex tool. Minor gaps include no explanation of dpop_token, no explicit statement about zero-relay failure behavior, and no mention of prerequisites like authentication or billing.

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

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

The schema description already covers npub and message, and the description adds valuable context for npub (proven, session-bound, billing correlation, never free-form). However, dpop_token is completely unexplained in both schema and description, and with 67% coverage, the description does not fully compensate for that 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 opens with 'Publish a public Nostr note (kind 1) authored by your proven npub,' which is a specific verb+resource+scope. It clearly distinguishes this from sibling tools like excalibur_post_tweet or excalibur_create_post by specifying Nostr note, kind 1, and the author constraint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 constraints and mechanics, but never explicitly says when to use this tool versus alternatives such as excalibur_post_tweet or excalibur_create_post. It implies usage through the name and context, but provides no exclusions or direct comparisons to sibling tools.

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

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

With no annotations, the description carries full responsibility. It discloses the data source (durable snapshot store), a data limitation (suppressed below 5 posts), and clarifies that it is derived rather than a direct API proxy. This is substantial behavioral context, though it omits auth requirements 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 relatively short (two sentences) and the first sentence front-loads the purpose. However, the second sentence is dense with jargon and includes marketing fluff like 'owning the curve', which does not add functional clarity. Some phrases could be simplified without loss of 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?

The description covers key computational aspects and mentions a suppression threshold, and an output schema exists so return values need not be described. Yet it is vague about the overall output structure, data freshness, and prerequisites beyond having a harvested corpus, leaving some gaps for a complex analytics 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 provides no information about the two parameters (npub, dpop_token) and does not explain dpop_token's role. Schema coverage is only 50% (npub described, dpop_token not), so the description fails to compensate for the gap, leaving the token parameter ambiguous.

Input schemas describe structure but not intent. Descriptions should explain 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 computes derived reach scores across a harvested post corpus, enumerating specific metrics (escape velocity, breakout ratio, link-placement cohort medians, snippet/voice attribution). The verb+resource are present, and the mention of 'not proxying a single X endpoint' distinguishes it from direct metric tools, though it could be more explicit about the overall 'post performance' scope.

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

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

The description implies usage for aggregated, derived analytics across multiple posts and contrasts with 'proxying a single X endpoint', giving a sense of when it's appropriate. However, it does not explicitly name alternative tools or state when to use this instead of excalibur_get_post_metrics or excalibur_harvest_metrics, and no exclusions are mentioned.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions it 'Mirrors account_statement_infographic' and lists included metrics (corpus size, median t+15m impressions, etc.), but it does not state whether the tool is read-only, whether it requires OAuth or patron credentials, what side effects occur, or how the SVG is returned. The 'Patron:' prefix hints at access restrictions but is ambiguous.

Agents need to know what a tool does to the 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 that front-load the purpose and then add relevant detail about theme and content. Every sentence contributes value, with no redundant filler or vague jargon.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 gives a good overview of the output content and theme, but it omits critical context about authentication, prerequisites, and parameter usage. While the presence of an output schema reduces the need to describe return values, the tool still requires npub and dpop_token, and the description doesn't explain how these are used or why they are needed. This leaves the tool somewhat incomplete for an agent to invoke confidently.

Complex tools with many parameters or behaviors need more documentation. 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 provides no explanation of the 'npub' and 'dpop_token' parameters beyond what the schema already gives for npub. The 'dpop_token' parameter is entirely undocumented in both the schema and description, leaving a significant gap. Since schema coverage is only 50%, the description should have clarified the role of the token but did not.

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

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

The description clearly states this tool produces an 'SVG infographic of post performance' with a specific gold-steel theme, which identifies the resource and output type. It also references the sibling 'account_statement_infographic' to give context, but it doesn't explicitly state the action verb (e.g., 'generate' or 'create') nor directly contrast with 'excalibur_post_performance' for data vs. infographic.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 similarity to 'account_statement_infographic' but provides no explicit guidance on when to use this tool versus alternatives like 'excalibur_post_performance' or other infographic tools. There is no mention of scenarios, prerequisites (e.g., being a patron), or exclusions, leaving the agent to infer usage context.

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

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

With no annotations provided, the description carries the transparency burden. It discloses the markdown-to-Unicode conversion behavior and gives examples, which is valuable. However, it omits any mention of authentication requirements, credit billing, or the fact that tweeting is a permanent public action. The npub billing detail appears only in the schema, not the description.

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

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

The description is compact and front-loaded, leading with the core purpose and following with a concise explanation and examples. Every sentence earns its place, and the use of a code block makes the markdown conversion rules clear 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 tool has an output schema, so return values need no description. The main behavior (markdown conversion) is thoroughly explained. However, for a mutation tool with billing implications, one might expect mention of prerequisites like authentication or credit balance, though the npub parameter in the schema hints at billing. The description is mostly complete for its intended use case.

Complex tools with many parameters or behaviors need more documentation. 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 67% (npub and text described, dpop_token not). The description adds meaningful semantics for the 'text' parameter by explaining markdown formatting and showing conversion examples. However, it provides no help for the undocumented dpop_token, and the npub description is already in the schema. Overall, the description adds some value but does not fully compensate for the coverage gap.

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

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

The description uses a specific verb ('Post') with a clear resource ('text tweet') and adds the unique behavior of converting markdown to Unicode Mathematical Alphanumeric Symbols. This clearly distinguishes it from sibling tools like excalibur_post_tweet_image (image tweet) and excalibur_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?

The description implies usage for text tweets requiring markdown formatting, but it does not explicitly state when to choose this tool over alternatives like excalibur_create_post or excalibur_post_nostr_message. No exclusions or alternative comparisons 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?

With no annotations, the description carries the burden of behavioral disclosure. It reveals that image_url is fetched and attached, and banner_svg is rendered to PNG, adding value beyond the schema. However, it does not disclose authentication requirements, side effects, or behavior when both image parameters are provided, which is a gap for a mutating 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 two sentences, front-loaded with the primary purpose and immediately followed by actionable image option instructions. Every sentence earns its place 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?

Given the tool has 5 parameters, an output schema, and a large sibling set, the description provides the core workflow and references post_tweet for formatting. It does not mention the npub billing requirement (though the schema does) or what happens if both image_url and banner_svg are supplied, but overall it is sufficiently complete for an agent to invoke correctly.

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

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

Schema description coverage is high (80%), so the baseline is 3. The description adds meaningful semantics for the two image parameters by explaining they are 'fetched and attached' and 'rendered to PNG and attached', which goes beyond the schema's simple 'URL of an image to attach' and 'SVG markup string'. It does not explain dpop_token, but that is a minor 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 states 'Post a tweet with a hero banner image to X/Twitter' with a specific verb and resource, clearly distinguishing itself from the sibling post_tweet by the hero banner image addition. It also specifies the two image source options, making the purpose unambiguous.

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

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

The description gives clear usage instructions: 'Provide either an image_url (fetched and attached) or banner_svg (rendered to PNG and attached)' and references post_tweet for formatting. It clearly implies this is the image-attaching variant, but does not explicitly state when not to use it or compare it to alternatives beyond the format reference.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool claims posts atomically, starts background publishers, returns immediately, and that the actual publishing may take minutes. It also specifies the return format and the operator requirement. This is highly 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 succinct and front-loaded with the core action. Each sentence adds essential information (operator-only, atomic claim, async behavior, outcome retrieval, return format). No unnecessary words or 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 tool's complexity and the presence of an output schema (implied by description of return format), the description covers all critical aspects: purpose, prerequisites, behavior, outcomes, and caveats. It is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 50%, with only npub having a description. The description adds value by stating 'Requires the operator's npub proof', reinforcing the schema. However, dpop_token is undocumented in both the schema and description. The description compensates partially but not fully for the low coverage.

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

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

The description clearly states the tool launches a publisher for every due post, operator-only. It specifies the action (selecting, claiming, starting publishers) and distinguishes from the actual publishing process, which is done by a separate publisher. This differentiates it from sibling tools that handle other tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (for due scheduled posts) and what it does not do (publishing). It also mentions that outcomes can be read from get_scheduler_log or post rows, providing guidance for follow-up. While it does not explicitly list alternatives, the context is sufficient for an AI agent to understand 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 carries the full burden and does well: it discloses the server never holds the nsec, verifies the event signature against the npub, relays to public relays, and that authorization comes purely from the signature. It stops short of describing failure modes or relay selection, but the core behaviors are transparent.

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

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

The description is concise and front-loaded with the main purpose. The three sentences each add essential information: what it does, how the signed event is provided, and why the signature is sufficient. No wasted words.

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

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

Given the tool's moderate complexity and the presence of an output schema, the description covers the key aspects: the publishing flow, the security model, and the authorization mechanism. It does not explain return values or error cases, but the output schema likely handles that, and the description is adequate for a straightforward publish action.

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

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

Schema description coverage is 100%, so both npub and signed_event are already clearly described in the schema. The description adds context about the signature-checking relationship between them, but does not offer significant new parameter-level semantics beyond that.

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

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

The description clearly states the tool publishes a client-signed kind-0 Nostr profile to relays for a given npub. It uses a specific verb ('publish') and resource ('kind-0 profile'), and the client-signed nature distinguishes it from other Nostr publishing tools like excalibur_post_nostr_message.

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

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

The description explains the expected workflow: the frontend signs the kind-0 event and passes it here, with the server verifying the signature. It also clarifies the security constraint ('The wheel never holds a patron nsec'), implying this tool is for scenarios where key custody is avoided. However, it does not explicitly name alternatives or state when not to use it.

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

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

With no annotations, the description carries the full burden. It discloses that the tool creates an invoice (not immediate credit), requires proof of npub ownership, and is free. It also indicates that payment is confirmed via check_payment, which is important behavioral context not in the schema.

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