roastify-mcp

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

With no annotations present, the description carries the full transparency burden. It discloses that the tool is free and consumes no credits, that proof of npub ownership is required, and that its purpose is to prevent statement-scraping. It does not explicitly state read-only status, but 'Returns...' plus the cost disclosure make the safety profile reasonably clear.

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

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

The description is compact and front-loaded. The first sentence states the core action, the second lists return contents, the third provides a key semantic distinction, and the fourth covers cost and authentication. Every sentence earns its place with no 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?

Given the tool's moderate complexity, the presence of an output schema, and fully documented parameters, the description provides enough context to invoke the tool correctly. It covers purpose, return content, cost, and auth requirements. It is missing only explicit read-only confirmation and explicit routing guidance to alternatives.

Complex tools with many parameters or behaviors need more documentation. 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 schema already thoroughly documents npub, dpop_token, and days. The description adds some context by framing dpop_token as 'proof of npub ownership' and implying days affects 'recent daily usage logs,' but it does not materially extend parameter 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 starts with a specific verb-object pair, 'Generate a patron's account statement,' and then enumerates the exact contents: purchase history, active credit tranches, per-tool usage breakdown, and daily usage logs. It also distinguishes itself from the operator's Authority tax balance, which is especially useful given the sibling tool roastify_check_authority_balance.

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

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

The intended use is implied by the description, but it never explicitly states when to use this tool versus alternatives. It includes a 'not the operator's Authority tax balance' clarification, but it does not name a sibling alternative or give an explicit when-to-use / when-not-to-use rule.

Agents often have multiple tools that could apply. Explicit usage 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 correctly carries the behavioral burden. It discloses that the call costs 1 api_sat, that proof is verified by debit_or_deny before any cost is incurred, and that output is a dark-themed SVG with specific visual components. This is meaningful behavioral context beyond the schema.

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

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

The description is compact and front-loaded. The first sentence states the core purpose, and the second adds only high-value behavioral facts: cost, proof verification, and visual components. Every sentence earns its place with no filler or 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?

For a tool with cost implications and a specialized auth token, the description covers the essential operational details: output format, cost, and verification flow. An output schema exists, so return-value details are not required. A minor gap is the lack of an explicit 'use this tool vs. account_statement' statement, but the wording makes that inferable.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning, but the schema already thoroughly documents npub, dpop_token (including the exact required format), and days with default. No further elaboration is necessary in the description.

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

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

The description opens with a specific verb and object: 'Generate a visual SVG infographic of your account statement.' It clearly differentiates itself from the sibling roastify_account_statement by stating it returns the same data but rendered as a dark-themed SVG graphic, so an agent knows exactly what this tool produces.

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

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

The description implies when to use this tool: when a visual SVG infographic is needed rather than the raw account statement. It references account_statement as the alternative with the same data but non-visual form. It does not explicitly say 'use account_statement for raw data,' but the contrast is clear enough.

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

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

With no annotations, the description fully carries the behavioral burden, and it does so thoroughly. It discloses commit-to-same-design behavior, server-side placement validation with REFUSAL, panel/sheet containment rules, overlap collision behavior, typography inheritance, and image src reuse without new uploads. This gives the agent a realistic model of side effects and constraints.

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

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

The description is dense and front-loaded, with the core action in the first sentence and valuable behavioral details following. It earns its length given the tool's complexity, though it would be more scannable with bullet points or clearer separation between placement rules, image behavior, and typography behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 nearly all non-obvious behavioral context: versioned commits, placement validation, Tubes/sheet fallback, overlap refusal, related follow-up tools, and image src constraints. Since an output schema exists, return values need no description. A minor gap is that DPoP token and credit-billing context are left entirely to the schema, but the schema is mostly rich enough to compensate.

Complex tools with many parameters or behaviors need more documentation. 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 94%, so the baseline is 3, but the description adds meaningful cross-parameter guidance beyond the schema: how kind interacts with src_from/src, how position can be absolute or relative, and how text inherits typography via style_from. It does not explain the undocumented dpop_token, but the schema covers most parameter meaning already.

Input schemas describe structure but not intent. Descriptions should explain 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 states a specific action: 'Add a new element (text or image) to a design and commit a new version of it.' This clearly identifies the tool as an add/create operation and distinguishes it from related operations like update_design_text and move_elements. The resource and scope are 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 practical routing context: after adding, the returned id enables editing via update_design_text or moving via move_elements. It also explains when to use absolute vs relative positioning and when image src reuse applies. However, it does not explicitly state when not to use this tool or list exclusions between 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 provided, the description carries the behavioral burden. It says the operation is free and polls for status, implying a read-only check, but it does not explicitly state side-effect behavior, authentication needs, or whether repeated polling has any limitations. This is adequate but not richly 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 two sentences with no filler. The core purpose is front-loaded, and the extra details ('Free', 'polls MCP-to-MCP', possible statuses) are useful and compact.

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

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

An output schema exists, so return values are covered. The description provides the core purpose, target authority, and possible statuses, but it omits dpop_token semantics and any relationship to the adoption request flow. It is usable but not fully complete.

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

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

Schema description coverage is 0%, so the description must explain the parameters. It maps authority_npub to 'chosen Authority', but it never explains dpop_token, which remains ambiguous. This is only partial compensation 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 a specific verb ('Check'), a resource ('adoption-request status'), and a target ('at a chosen Authority'). It distinguishes itself from related siblings like roastify_request_adoption and roastify_get_operator_onboarding_status by naming the exact 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 gives clear context: it is for checking an operator's adoption-request status at an Authority by polling MCP-to-MCP. It does not explicitly list exclusions or alternatives, but the use case is evident enough to route an agent correctly.

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

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

With no annotations, the description carries the behavioral burden. It discloses the cost model ('Free — polling never costs anything') and the two terminal result states ('finished job carries artwork_url; a failed one carries error'). It does not explicitly state read-only behavior, but 'Check' and 'polling' 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?

The description is three short sentences, front-loaded with the core purpose, followed by a cost note and terminal outcome summary. Every sentence earns its place; there is no fluff 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?

The description covers the essential behavioral context: what the tool does, that polling is free, and what a caller can expect in success and failure returns. With an output schema present, return-value details need not be spelled out. It could optionally mention the pending/processing state, but that is a minor 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?

Schema coverage is 67%, so the schema already documents job_id and npub; the description adds no direct parameter semantics. The remaining dpop_token parameter is undocumented, but the description's cost and result-state guidance partially compensates by clarifying what the job_id is used for.

Input schemas describe structure but not intent. Descriptions should explain 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 Roastify artwork job' — a specific verb and resource that clearly identifies the tool's purpose. It is easily distinguished from sibling status tools like adoption_status, service_status, or session_status by the 'artwork job' 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 phrase 'Free — polling never costs anything' gives clear usage context: this is safe to poll repeatedly. It does not explicitly name alternative status tools, but the artwork-job specificity and polling guidance provide enough direction without needing exclusions.

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

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

With no annotations, the description carries the disclosure burden and goes beyond a generic browse statement. It reveals that plan-gated items are returned with their tier marked rather than hidden, and it warns that origin, altitude, processing, and varietal data are absent from the catalog, while clarifying that roast level and decaf status come from the blend.

Agents need to know what a tool does to the 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 short and front-loaded with the action, and each additional sentence conveys non-obvious behavior or data caveats rather than restating schema fields. There is no filler or redundancy.

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

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

For a simple 2-parameter tool with an output schema, the description is nearly complete: it covers plan-gating behavior and data-availability caveats that shape how results should be interpreted. The main gaps are the undocumented dpop_token and the lack of explicit sibling routing, but the output schema and low input complexity reduce the burden on the description.

Complex tools with many parameters or behaviors need more documentation. 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 50%: npub is documented in the schema, but dpop_token is an empty string with no description, and the tool description itself adds no parameter semantics at all. The schema's claim that npub is 'Required' is also undercut by the default value and the absence of required fields, which the description does not resolve.

Input schemas describe structure but not intent. Descriptions should explain 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 names a specific verb—'Browse'—and a clear resource: the Roastify catalog, with scope explicitly defined as 'products and coffee blends together.' This distinguishes it from the focused sibling tools like roastify_get_catalog_product and roastify_get_blend even without naming them.

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

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

The description establishes catalog-wide browsing as the use context, which implies a broad listing tool rather than a single-item getter. However, it never explicitly names alternatives such as roastify_get_catalog_product or roastify_get_blend, nor states when one should be preferred over the other.

Agents often have multiple tools that could apply. Explicit usage 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 adds meaningful behavioral context: what the balance is used for, what happens when it reaches zero, that it is the operator's own funding rather than a patron balance, and that it is free. A read-only implication is present but not explicitly stated.

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

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

The description is four short sentences, front-loaded with the core purpose, and every sentence contributes either to meaning, consequences, or clarification. There is no filler or redundant wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 read-style tool with an output schema, the description is fully sufficient. It explains what the value represents, what the failure condition is, how to remediate it, and who owns the balance.

Complex tools with many parameters or behaviors need more documentation. 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, so the baseline of 4 applies. The description adds relevant semantic context about what is being queried, even though there are no parameters to document.

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

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

The description names a specific verb ('Check'), a specific resource ('this operator's tax balance at the Authority'), and clarifies what the returned value means ('sats available for certifying patron credit purchases'). It explicitly distinguishes this from a patron balance, which separates it from related balance-checking 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 context for when this check matters and names the follow-up action ('call purchase_credits on the Authority') when the balance hits zero. It does not explicitly say when not to use this tool versus other check tools, but the context and the alternative action are clear enough.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the operation is free, requires proof of npub ownership, and explains the privacy rationale (preventing enumeration). This goes well beyond a bare 'check balance' and gives the agent meaningful 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 compact and front-loaded with the main purpose, then provides differentiation, cost, and authentication requirements. Every sentence contributes distinct, necessary information with no 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?

The description covers purpose, the alternative tool, cost, and authentication prerequisites, while the schema covers exact parameter formatting and an output schema is present. The only notable gap is the imprecise alternative tool name, which slightly weakens tool-selection completeness.

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

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

Schema coverage is 100%, and the dpop_token description in the schema is already extremely detailed regarding event type, framing, `u` tag, timestamps, and nonce. The tool description adds only a high-level ownership-proof requirement, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: checking a patron's credit balance at this operator. It clearly differentiates this from the operator's own Authority balance, so an agent knows exactly what object is being queried.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 explicit when-not guidance: for the operator's own Authority balance, use authority_check_balance instead. It also notes that the tool is free and requires proof of npub ownership, which sets clear usage context. Minor deduction because the named alternative does not exactly match the sibling tool name roastify_check_authority_balance.

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

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

With no annotations provided, the description carries the transparency burden. It discloses the cost model ('Free — no credits required') and an important security requirement ('Proof of npub ownership is required to prevent credit-grant front-running'). This goes beyond a generic read operation, though it does not describe all possible side effects or response behavior.

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

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

The description is compact and front-loaded with the core purpose, followed by a single usage directive and two key behavioral constraints. Every sentence earns its place with no redundant phrasing.

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

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

The combination of a clear purpose, explicit sequencing after purchase_credits, cost information, authentication context, and a complete input schema is sufficient for correct invocation. The presence of an output schema reduces the need to describe return values. Minor missing details like polling behavior or possible statuses are covered by the output schema.

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

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

Schema description coverage is 100%, so the parameters are already fully documented. The description adds contextual value by tying the call to purchase_credits and mentioning proof of ownership, but it does not need to restate the parameter details. This meets the baseline 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 description states a specific action: 'Check the payment status of a Lightning invoice.' It further anchors the tool in a concrete workflow by saying 'Call after paying the invoice from purchase_credits', which distinguishes it from sibling status/check tools like check_balance, check_price, and check_proof_status.

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

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

The description gives explicit when-to-use guidance: 'Call after paying the invoice from purchase_credits.' It also adds practical constraints such as being free and requiring proof of npub ownership. It does not explicitly name alternatives or exclusions, but the workflow placement is clear enough.

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

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

With no annotations, the description carries the behavioral burden itself. It clearly discloses that the tool is a preview (not an execution), that it shows base cost and constraint effects, and that it consumes no credits. It does not cover auth requirements or edge cases, but the core side-effect and safety profile is well 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 compact and well structured: the core purpose is front-loaded in the first sentence, followed by two short sentences that add necessary detail about cost components and the free nature of the call. Every sentence earns its place.

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

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

For a read-only preview tool with an output schema present, the description covers the essential purpose, what cost components are shown, and the fact that no credits are required. The main gaps are lack of explicit routing against pricing siblings and explanation of the optional auth-related parameters, but these are not blocking for a basic correct invocation.

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

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

The schema already documents tool_id and tool_kwargs, and the description adds useful context that tool_kwargs feed constraint-effect calculations. However, the optional npub and dpop_token parameters remain undocumented in both the schema and the description, so the description only partially compensates for the 50% schema description coverage.

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

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

Uses a specific verb ('Preview') and a clear resource ('effective cost of a tool call'), and goes on to specify that it reflects base cost plus constraint effects like discounts and surge pricing. This makes it clearly distinct from sibling tools like get_pricing_model or check_balance.

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

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

The 'Free — no credits required' line and the word 'Preview' imply this is a safe, non-executing estimation tool to use before a paid call. However, it never explicitly says when to use this tool versus related siblings such as roastify_get_pricing_model or roastify_list_constraint_types, so the guidance remains implied rather than explicit.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It explicitly states the call is free, has no side effects, does not evict the cache, and does not touch relays. This is meaningful beyond the tool's name and purpose.

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

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

The description is compact and front-loaded: the core function appears first, followed by the sibling comparison, the practical use case, and the side-effect guarantee. Every sentence earns its place with no 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 status-check tool, the description covers purpose, when to call it, and behavioral guarantees. It does not describe the return value format, but the phrase 'Check whether... is still valid' and the example use case make the expected result reasonably clear.

Complex tools with many parameters or behaviors need more documentation. 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 strong descriptions for both parameters, including requiredness and provenance of the dpop_token and the npub format. The description adds little parameter-level detail, so the schema's high coverage earns the baseline of 3.

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

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

Description opens with a specific verb and resource: 'Check whether a previously-cached dpop_token is still valid.' It further distinguishes itself from the sibling check_oauth_status by explicitly positioning itself as the npub-proof-flow mirror, so an agent can tell them apart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidance on when to use this tool: before a paid call, to avoid 'burning credits on a guaranteed failure.' It names check_oauth_status as the analogous sibling, but does not explicitly state when not to use it or list other alternatives.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Check stock' without mentioning that using the tool requires a Nostr public key for credit billing, or whether this operation is read-only and what the response contains. This under-disclosure leaves important behavioral context to the agent.

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

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

The description is a single efficient sentence that front-loads the action and scope. It contains no redundant phrases and is appropriately sized for the tool's apparent simplicity.

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

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

While an output schema exists and can handle return values, the description omits critical context: the npub parameter is described as required and tied to credit billing, yet this is not surfaced in the description or via annotations. The tool also lacks any mention of authentication prerequisites, making the definition incomplete 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 67%, so the baseline is 3. The description's phrase 'one SKU, or the whole stock list' echoes the sku parameter description rather than adding new meaning. It does not explain npub's billing purpose or dpop_token, leaving the schema to carry most 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 identifies a specific verb ('Check') and a specific resource ('Roastify stock'), and states the scope ('one SKU, or the whole stock list'). It distinguishes itself from stock-unrelated siblings, though it does not clarify what aspect of stock is returned (e.g., quantity, availability).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 no guidance on when to use this tool versus alternatives like roastify_check_price or roastify_get_catalog_product. It only implies usage through the resource name, and does not mention prerequisites such as the required npub for credit billing.

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

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

With no annotations provided, the description fully bears the behavioral burden. It discloses cascade deletion, neutral constraints on unknown ids, no-op behavior for referencing chain steps, Studio warnings for orphan references, and the operator proof requirement.

Agents need to know what a tool does to the 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 tight: the core action is front-loaded, followed by the cascade consequence, reference-handling details, and access restriction. Every sentence conveys necessary information with no 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 destructive operator-gated tool, it covers side effects, dangling references, and access requirements, and the presence of an output schema means return values don't need described. The only notable gap is the exact mechanics of the required proof/token.

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

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

Schema description coverage is 0%, so the description must explain both coupon_id and dpop_token. It clarifies coupon_id as the identifier being deleted and hints at proof via 'requires proof,' but it never explicitly ties dpop_token to that proof or explains how to obtain it.

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

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

The description begins with 'Delete a coupon,' specifying a concrete verb and resource, and the cascade behavior clarifies it is the destructive removal tool. It is clearly distinct from update_coupon, but it does not explicitly contrast with semantically adjacent roastify_forget_coupon.

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

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

It gives clear operational context: cascading to redemptions, no-op chain steps, and the operator-only restriction. However, it never names an alternative or states when not to use this tool, so the when-to-use guidance relies on inference from the named effects.

Agents often have multiple tools that could apply. Explicit usage 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 of behavioral disclosure. It states the operation is a delete, implying destructive action, but it does not mention irreversibility, whether related data or versions are affected, authentication/authorization requirements, billing implications, or response behavior. This is a meaningful gap for a mutation tool.

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

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

One short, front-loaded sentence that states exactly what the tool does with no filler. The description is appropriately sized for a simple delete operation, and 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?

For a destructive tool with no annotations, the description is too minimal. It omits important contextual details such as irreversibility, whether the design_id must come from roastify_list_designs (stated only in the schema, not the description), and any billing side effects. The presence of an output schema helps, but the description alone does not make the tool's usage fully transparent.

Complex tools with many parameters or behaviors need more documentation. 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 contributes no parameter-level meaning beyond what the input schema already provides. The schema documents design_id and npub, but dpop_token remains unexplained, and the description does not clarify billing, ownership, or how the design is identified. The schema's own 'Required.' note on npub also conflicts with the actual required array, which is confusing.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Delete') and a clear resource ('one of your stored designs'), distinguishing this tool from sibling delete tools like delete_coupon, delete_operator_credential, and delete_patron_credential. It is immediately clear what entity the tool acts on and that it operates on the caller's own stored designs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 phrase 'one of your stored designs' provides clear context that this tool is for removing designs owned by the user, not for other delete operations among the siblings. It does not explicitly enumerate when not to use it or mention alternatives, but the resource distinction is clear enough for selection.

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

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

With no annotations provided, the description carries the full behavioral burden, and it excels: it discloses idempotency ('already-absent fields report removed: false without rewriting the vault'), keying semantics ('what is vaulted, not what the current template declares'), and destructiveness ('as destructive as a write'). The proof requirements and rejection of patron proofs are also clearly stated.

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

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

The first sentence delivers the core action, and each subsequent sentence adds a distinct, non-redundant fact: scope, use case, idempotency, privilege, and destructiveness. The length is justified by the tool's security- and semantics-rich nature; nothing feels padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 sensitive mutation tool with no annotations, the description covers invocation intent, preconditions, security requirements, edge behavior, and side effects. The presence of an output schema means return-format explanation is unnecessary. An agent has everything needed to select and 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?

Although the input schema covers basics, the description adds deep meaning: 'field' is explicitly templated-or-not and vaulted-or-templated, while 'dpop_token' is enriched with concrete proof forms (nsec-signed kind-27235 or cached dpop_token phrase). This goes well beyond the schema's one-line descriptions.

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

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

The description opens with a precise verb-object pair — 'Remove a single operator secret field' — and immediately clarifies it deletes one key from the encrypted credential blob. It explicitly distinguishes itself from the sibling 'forget_credentials' (whole-row wipe) and from patron-credential tools by emphasizing operator scope. This is a model example of sibling differentiation.

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

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

It names the exact scenario — retiring leftovers after an SDK cutover, like a Prefect key after Modal or an untemplated orphan — and contrasts with 'forget_credentials' for full re-delivery. It also declares eligibility constraints: operator-only, requires specific proof, and patron proofs are rejected. The agent knows when to call it and when not to.

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

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

There are no annotations, so the description carries the full burden. It discloses that this is a write to a sensitive credential vault, requires proof of npub ownership, is free, and only affects one field. It could additionally mention irreversibility or behavior when the field does not exist, but the key behavioral traits are present.

Agents need to know what a tool does to the 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 with no filler. The core action is front-loaded, followed by necessary caveats about scope, cost, and proof of ownership. Every sentence adds useful information.

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

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

Given the full parameter schema and an output schema, the description covers the essential context: what is deleted, what is not affected, the ownership proof requirement, and that it is a sensitive write. It is complete enough for an agent to call this tool correctly, though it could mention checking available fields via a sibling tool.

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

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

Schema description coverage is 100%, and the schema already documents npub, dpop_token, and field in detail. The description adds context about ownership proof and the sensitive nature of the vault, but does not need to repeat parameter mechanics. 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 uses a specific verb ('Remove') and resource ('a single patron credential field'), and clearly distinguishes the scope: deleting one field without affecting other fields. This differentiates it from sibling tools like update_patron_credential or forget_credentials.

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

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

It gives clear context for when to use the tool: removing exactly one credential field from a patron's stored credentials. It also flags an important prerequisite (proof of npub ownership). However, it does not explicitly name alternatives or conditions when the agent should prefer update_patron_credential or get_patron_credential_fields.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It does add one meaningful behavior — images being re-inlined — but it omits important behavioral traits such as the credit-billing requirement tied to npub, version selection via ref, and any auth/dpop 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 a single, front-loaded sentence with no filler. It states the action and the key transformation in a compact way, which is exactly what conciseness should look like.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 presence of an output schema and reasonably detailed parameter descriptions makes the tool invocable, but the description is too thin on its own to fully prepare an agent. Missing context includes when to use versioned fetches vs latest, the billing side effect tied to npub, and how this differs from a plain list result.

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

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

The description adds no parameter-level meaning, but the schema already covers most parameters with descriptions for design_id, ref, and npub, yielding roughly 75% coverage. The dpop_token remains effectively undocumented, so the description does not need to do all the work, but it also does not 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 uses a specific verb ('Fetch') and resource ('one of your stored designs'), and the phrase 'in full, with its images re-inlined' clearly differentiates this from list-oriented siblings like roastify_list_designs. It is concrete and not a tautology of the tool name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 choose this tool over alternatives such as roastify_list_designs or roastify_list_design_versions. It also does not state prerequisites like needing a design id or owning the design. Usage context must be inferred entirely from the name and schema.

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

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

With no annotations provided, the description fully carries the behavioral burden. It clearly states what happens (removal from redemption list), what does not happen (coupon still exists), that re-redemption is possible, that the operation is free, and that proof of npub is required.

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

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

The description is compact and front-loaded: the action, the cosmetic limitation, and the cost/auth prerequisite each appear in their own short segment. Every sentence adds value and nothing merely repeats the tool name or schema.

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

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

For a simple three-parameter mutation with an output schema and no annotations, the description covers the core semantics, side effects, cost, and auth prerequisite. Minor gaps remain: no explicit pointer to the permanent-deletion sibling and no explanation of the optional dpop_token parameter.

Complex tools with many parameters or behaviors need more documentation. 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 for all three parameters. It adds only indirect context for npub (patron identity/proof) and for the coupon itself, while coupon_id and especially dpop_token receive no useful semantic explanation.

Input schemas describe structure but not intent. Descriptions should explain 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 names a specific verb ('Remove') and a specific resource ('a coupon from this patron's redemption list'). The 'Cosmetic only' clarification immediately distinguishes it from destructive coupon operations like roastify_delete_coupon.

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

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

The description gives clear usage context: use it to remove a coupon from a patron's redemption list, it is free, and it requires proof of npub. It also implies a key exclusion — this is not a permanent deletion — but it does not explicitly name an alternative such as roastify_delete_coupon.

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

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

With no annotations provided, the description carries the full safety burden and explicitly warns that deletion is 'as destructive as a write' and that proof of npub ownership is always required. This is substantive and helps an agent treat the operation as sensitive. It could add explicit irreversibility details, but the disclosed destructive/auth profile is strong.

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

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

Three short sentences with no filler: core action first, then operator/patron clarification, then the safety warning. Every sentence earns its place.

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

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

For a destructive three-parameter tool with a rich input schema and an output schema present, the description covers what is deleted, who can be targeted, and the proof/auth requirement. The main missing piece is explicit tool-selection guidance relative to the delete_*_credential siblings, but the direct call requirements are otherwise complete.

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

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

The input schema already documents all three parameters at 100% coverage, including a detailed dpop_token format, so the baseline is 3. The description adds operator-vs-patron meaning for npub, but it does not add substantive meaning for service or dpop_token beyond the schema.

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

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

The description states a specific action ('Delete vaulted credentials') and resource ('for a specific service and npub'), so it is far from a tautology. It adds operator/patron nuance, but it does not explicitly distinguish this tool from the sibling roastify_delete_operator_credential and roastify_delete_patron_credential 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 gives clear usage context: pass the operator's own npub for operator credentials and the patron's npub for patron credentials, and always require proof of npub ownership. However, it names no alternatives and gives no exclusions, leaving the relationship to the credential-deletion siblings ambiguous.

Agents often have multiple tools that could apply. Explicit usage 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, and it does so well: it reveals asynchronous rendering (returns a job id, not artwork), the need to poll status, the non-persistence of the artwork to a product, and the limitation to template personalization. This goes well beyond a generic 'generate artwork' 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?

Three short paragraphs, each earning its place: purpose, constraints/limitations, and async behavior with the follow-up pointer. Information is front-loaded in the first sentence, and there is no wasted prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 large sibling set and the presence of an output schema, the description covers the essentials: what the tool can and cannot do, the prerequisite (saved design), the async workflow, and the exact follow-up tool. An agent can select and invoke this tool correctly without additional research.

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

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

Schema coverage is 80%, and the description adds meaningful semantics for the key parameters: product_id is sourced from list_my_products, fields is explained with an inline structure example and the https requirement for image values, and client_req_id's idempotency behavior is described. Only dpop_token is left unexplained, preventing a 5.

Input schemas describe structure but not intent. Descriptions should explain 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+resource: 'Generate packaging artwork from one of your saved Design Studio designs.' It then clarifies that the tool rewrites placeholders in an existing template rather than authoring from scratch, which distinguishes it from design-creation siblings like roastify_add_design_element or roastify_update_design_text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 it — when you have a saved Design Studio design to personalize — and what it cannot do ('cannot author a design from scratch', 'NOT attached to a product', 'no product-create or storefront-sync surface'). It also names the exact follow-up tool and its cost profile: 'Check it with roastify_artwork_status, which is free.'

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

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

No annotations are present, and the description only describes a read operation. It does not disclose the billing/credit implications implied by the npub parameter, potential side effects, or any limitations. 'Get' suggests non-destructive but does not fully confirm behavior.

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

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

One concise sentence that front-loads the core purpose and then gives the key returned attributes. Every word is useful and there is no 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?

Adequate for a simple getter with an output schema, but missing usage context (when to call relative to browse_catalog) and behavioral disclosure (billing/credit implications). With no annotations, the description should carry more weight than it does.

Complex tools with many parameters or behaviors need more documentation. 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 input-parameter meaning. The listed attributes (roast level, decaf status, variants) describe output, not how to provide blend_id, npub, or dpop_token. The schema already does most of the param explanation.

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

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

States a specific verb ('Get') and resource ('one coffee blend'), and lists the returned attributes (roast level, decaf status, variants). It clearly implies a single-item fetch versus catalog browsing, though it does not explicitly distinguish from sibling get_* tools.

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

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

No explicit when-to-use or alternative guidance is given. The schema's blend_id note 'from browse_catalog' implies a prerequisite step, but this is only implied rather than stated in the description.

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

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

With no annotations, the description carries the behavioral burden, and the "Get" verb at least signals a read operation while the payload list explains what data is returned. However, it does not state whether the call is side-effect-free, whether it consumes credits via npub, or how not-found cases behave, so some behavioral transparency is still missing.

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

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

A single sentence front-loads the verb and unique content scope with no filler. Every word contributes to understanding what the tool returns.

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

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

The presence of an output schema and the simple read operation mean the description does not need to explain return structure. But given the large sibling set, it lacks the usage routing that would make it fully self-sufficient for an agent deciding between browse_catalog, get_catalog_product, and get_my_product.

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

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

The description adds no parameter-level meaning; it only enumerates the returned product fields. The schema already documents product_id ("from browse_catalog") and npub (credit billing), so coverage is moderate at 67%, leaving the undocumented dpop_token without clarification.

Input schemas describe structure but not intent. Descriptions should explain 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 a specific verb and resource: "Get one catalog product with its variants, sizes, prices, and dieline." This clearly differentiates it from browse_catalog (a listing operation) and from get_my_product/list_my_products by emphasizing the catalog product context and its full detail set.

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

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

The description provides no explicit when-to-use guidance or exclusions, and does not name alternatives such as browse_catalog or get_my_product. The only usage signal is indirect, in the schema, where product_id is described as coming from browse_catalog; that is not present in the description itself.

Agents often have multiple tools that could apply. Explicit usage 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 behavioral burden and succeeds richly. It discloses that there is no visibility flag, that stash labels reflect intent rather than content, that width is a fixed wrap frame while height re-measures, that text grows rather than clips, and that z is paint order. These are genuinely non-obvious behaviors an agent needs to know.

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

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

Although long, the description is well-structured and front-loaded: purpose first, then return fields, then geometry, then caveats, then related tools. Each paragraph earns its place by adding operational knowledge rather than repeating schema content. The use of code-formatted field names aids scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 design-inspection tool with many quirks, the description is remarkably complete: it covers text layers, non-text elements, fonts, panels, sheet geometry, face assignment, measurement semantics, paint order, caveats about missing visibility, and the associated write-back tools. An agent has enough context to call this tool correctly and interpret its results safely.

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

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

Schema coverage is 67%, so the baseline applies; the description adds no additional parameter-level meaning beyond what the schema already says. design_id is documented in the schema as 'The id from roastify_list_designs,' and npub is already explained, but the description does not elaborate on dpop_token or further clarify parameter usage.

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

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

Opens with a precise verb+resource description: 'List the editable text layers of a stored design — the fields you can change.' It clarifies scope by explicitly excluding images and emphasizes that this is for reasoning over editable content, distinguishing it from related tools like roastify_fetch_design and roastify_update_design_text.

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

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

Provides explicit, actionable usage guidance: read this before judging a design, pair with roastify_update_design_text to save text changes, use roastify_move_elements for geometry/style changes, and use roastify_set_product_description for store-page prose. It also warns against treating missing text as a defect, which prevents misuse.

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

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

With no annotations, the description carries the behavioral disclosure burden. It discloses an important hidden behavior: the blend identity is not a named field and must be decoded from the variant SKU, and a product's title may be misleading. It does not explicitly state that the operation is read-only, but the verb 'Get' and absence of mutation language make that reasonably inferable.

Agents need to know what a tool does to the 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 core purpose is front-loaded in one clear sentence, and the second paragraph earns its place by warning about SKU decoding with a concrete example. It is slightly verbose, but the extra detail is high-value and not redundant.

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

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

The description covers the tool's main hidden complexity (SKU-encoded identity) and the output schema covers return-value details. It does not elaborate on authentication prerequisites or explicitly differentiate from siblings like get_catalog_product, but the essential context for using the tool correctly is present.

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

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

The description adds essentially no meaning about the input parameters beyond what the schema already provides. Schema coverage is 67%: product_id and npub are described in the schema, but dpop_token is not described anywhere, and the description does not clarify how to obtain or populate it.

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

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

The description clearly states the operation ('Get one of your saved product designs in full, with all its variants') with a specific verb and resource. It indicates the tool is for your own saved designs, which helps distinguish it from catalog-style siblings, though it does not explicitly name an alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 phrase 'one of your saved product designs' gives clear context that this tool is for retrieving an agent's own saved product, and the schema adds that product_id comes from list_my_products. It does not explicitly discuss when not to use it or name sibling alternatives, but the intended use is reasonably clear.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the operation is a public read, requires no proof, returns the latest metadata fields, and returns an empty profile when none is published. This gives an agent a solid behavioral model beyond the tool 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?

Two short, purposeful sentences. The core action is front-loaded, the access caveat is directly relevant, and the return behavior is summarized without padding. Every sentence earns its place.

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

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

For a single-parameter public read with an output schema, this is complete: it explains access requirements, return content, and the no-profile edge case. There is no meaningful gap that would prevent an agent from invoking it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that npub identifies the account whose profile is read, but it does not define the npub format, how an invalid value behaves, or what the empty-string default means. This is partial compensation, not full.

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

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

Describes a specific verb ('Read'), a specific resource ('an npub's public Nostr profile'), and even pinpoints the protocol detail (NIP-01 kind-0 metadata). This clearly separates it from sibling tools like roastify_publish_nostr_profile and the proof-related Nostr 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?

States the key usage condition: 'Free, no proof — the data is already public on relays,' which tells an agent this tool can be used without credentials or proof. It does not explicitly name alternatives or when not to use it, but the context is clear enough for a simple public read.

Agents often have multiple tools that could apply. Explicit usage 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 carry the behavioral burden. It explains that a Merkle proof is generated from a notarization and a patron key, but it does not disclose whether this has any state-changing side effects, whether a notarization must already exist, or any failure conditions. The get-style name suggests read-only behavior, but that is not explicit.

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

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

One sentence with no filler, front-loading the action and clarifying the exact purpose. Every word contributes 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?

For a two-parameter tool with an output schema and fully described parameters, the overview is largely sufficient. It lacks only an explicit linkage to related proof tools and prerequisites, which would help an agent new to the domain.

Complex tools with many parameters or behaviors need more documentation. 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 npub and notarization_id are already documented in the schema. The description adds domain context but does not enrich the meaning of either parameter beyond what the schema contains, hitting the baseline for fully covered schemas.

Input schemas describe structure but not intent. Descriptions should explain 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'), a clear resource ('Merkle inclusion proof'), and a domain context ('patron's balance ... Bitcoin-notarized snapshot'). It does not explicitly contrast with sibling tools like roastify_receive_npub_proof or roastify_request_npub_proof, so it misses full differentiation.

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

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

The intended use—generating a proof for a notarized patron balance—is implied from the purpose statement, but the description does not state when to choose this tool over related siblings or mention any exclusions/prerequisites. This leaves the agent to infer the selection criteria.

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

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

No annotations are provided, so the description carries the burden of behavior. 'Report' and 'Shows' signal a non-mutating inspection, and 'Free' adds an explicit cost/revenue behavior not visible elsewhere. It could be more explicit about side effects, but for a zero-parameter read-only status tool this is sufficient.

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

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

The description is compact and front-loaded: the main purpose comes first, then what it shows, then the routing alternative, then the free cost signal. Every sentence earns its place with no redundancy.

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

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

For a no-parameter status-reporting tool with an output schema, the description is complete: it explains what is reported, what the report covers, how missing values are handled, which sibling to use instead, and the cost implication. The output schema presumably covers the return details, so no further explanation is needed.

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

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

The tool has zero parameters and an empty input schema, so there is no parameter burden for the description to carry. The description appropriately focuses on what the tool reports rather than inputs.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Report this operator's configuration readiness.' It clearly says what the tool does and distinguishes itself from get_patron_onboarding_status by naming that sibling directly for patron-level status.

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

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

The description gives an explicit when-not and alternative: 'For patron-level credential status, use get_patron_onboarding_status instead.' This directly routes an agent to the correct sibling tool when the target is patron-level rather than operator-level.

Agents often have multiple tools that could apply. Explicit usage 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, and it does well: it discloses that values are never exposed, that the tool is free, that proof of npub ownership is required, and that delivered_at may be null for older vaulted secrets. It does not explicitly say the operation is side-effect-free, but the read-only nature is strongly implied by 'List' and 'Values are never exposed.'

Agents need to know what a tool does to the 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, front-loaded with the core purpose, and every sentence earns its place. It covers output format, null behavior, cost, security sensitivity, and authorization without padding. The slight repetition of 'not values' and 'values never exposed' reinforces the most important distinction without being wasteful.

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

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

Given the output schema exists and the description already explains return contents, null behavior, auth prerequisites, cost, and sensitivity, nothing critical is missing. The description is complete for a fairly simple list-style tool and provides enough context to call it correctly even without 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?

Input schema coverage is 100% and the schema already provides strong descriptions for npub and dpop_token. The description adds meaningful context by explaining that the configured field list itself is sensitive and that proof of ownership is required, reinforcing why the dpop_token is needed. This goes slightly beyond the baseline provided by 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 opens with a specific verb and resource: 'List stored patron credential field names (not values).' It clearly distinguishes itself from siblings by emphasizing that values are never exposed and that it returns field names plus delivered_at timestamps, so an agent can separate this from update/delete/receive credential 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 gives an explicit intended use: 'use this to verify which fields are configured and how old each one is.' It also notes the sensitivity of the operation and the ownership proof requirement. It does not name alternative tools or when-not-to-use conditions, but the context is clear enough for selection.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It does well by explaining that credential presence is sensitive, why proof of npub ownership is required, and what the tool returns for different service types. It also notes the tool is 'Free,' adding a useful operational detail. It does not explicitly state that the operation is read-only, though the verb 'Report' and tool name 'get_' 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?

The description is well-structured and front-loaded: the first sentence states the purpose immediately. The following sentences earn their place by explaining the two service-type cases and the auth requirement. There is no fluff or repetition, and the 'Free.' note is compact but informative.

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

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

For a read-only status tool with a rich output schema (not shown but indicated as present), the description covers the important semantics: what is reported, how it varies by service type, and the required authorization. It lacks explicit statements about absence of side effects or error conditions, but these are minor given the tool's clear 'report' nature and the presence of an output schema.

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

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

The input schema already provides 100% description coverage for both parameters: patron_npub is the patron's Nostr public key, and dpop_token is a kind-27235 event signed by patron_npub. The description adds context about why the dpop_token is required (proof of ownership because credential presence is sensitive), but does not significantly extend parameter-level semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Report a patron's credential readiness for this operator.' It then clarifies the meaning by distinguishing set-once services (eXcalibur, TheBrain) from dynamic/OAuth2 services (Schwab), making the tool's exact scope clear. This differentiates it from sibling tools like get_operator_onboarding_status without needing to read their schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 conditional context: for set-once services it reports configured/missing secrets; for dynamic/OAuth2 services it reports no credentials are needed. It also states the prerequisite of npub ownership proof. However, it does not explicitly name alternative tools or state when not to use this tool, so the guidance is strong but not exhaustive.

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

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

With no annotations, the description carries the behavioral burden. It discloses a notable side effect: self-initializing a scaffold when no model exists. This is valuable beyond the simple 'get' name, and the note 'No economic data from code' adds further 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?

Three short sentences, front-loaded with the core purpose, followed by important behavioral caveats. Every sentence earns its place 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?

The tool has no parameters, an output schema is present, and the description covers purpose, cost, and initialization behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

The input schema has zero parameters, so there is nothing to document. The description appropriately adds no parameter information; the schema already fully covers this dimension.

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

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

States a specific verb ('Get') and resource ('active pricing model for this operator'), clearly identifying what is returned. It distinguishes itself from sibling tools like roastify_set_pricing_model and roastify_reset_pricing_model by focusing on retrieval rather than modification.

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

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

Provides clear context: the operation is free, and if no model exists it self-initializes a scaffold. It does not explicitly name alternatives or exclusion conditions, but the usage context is unambiguous for a read operation.

Agents often have multiple tools that could apply. Explicit usage 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 and meets it well. It explicitly says 'Free, no side effects,' explains how unregistered tools appear, distinguishes registry-seeded tools from @paid_tool UUIDs, and documents the live wire-surface diff. This goes well beyond what the tool name alone would imply.

Agents need to know what a tool does to the 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 longer than average, but nearly every sentence adds distinct meaning: canonical identity, register/unregistered behavior, rename semantics, and drift detection. It loses a point for repeating the 'Reconcile can flag deploy drift' idea in two separate paragraphs, which is slightly redundant.

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

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

The output schema covers the return structure, freeing the description to explain semantics, provenance, unregistered behavior, and the use case. It addresses why this tool exists, how to interpret its results, and what side effects it has. Nothing critical is missing for an agent deciding whether and how to call it.

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

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

The input schema has zero parameters and 100% schema description coverage, so the baseline is 4. The description adds no parameter-specific semantics, but none are needed since the tool takes no arguments.

Input schemas describe structure but not intent. Descriptions should explain 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 action and resource: 'Return canonical (tool_id, mcp_name, …) for every tool the wheel exposes.' It clearly distinguishes this from the many list_* siblings by framing it as the authoritative identity source for tool identification, not a domain-data list.

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

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

The description gives explicit consumers and use cases: 'any client (Studio, agents, FE)' and Reconcile's UUID-join workflow. It does not spell out when not to use it or name an alternative, but the positioning as the authoritative identity source makes the intended context unmistakable.

Agents often have multiple tools that could apply. Explicit usage 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 burden of behavioral disclosure. It explicitly states that the call is free and requires no credits, and it summarizes the returned fields. The 'List' wording implies a read-only operation, which is adequate for a zero-parameter lookup 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?

Two concise sentences: the first states the action and resource, the second describes the returned content and the no-credit requirement. All information is useful and front-loaded with no fluff.

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

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

For a zero-parameter listing tool with an output schema, the description is complete: it explains what is listed, what fields are returned, and the cost behavior. Nothing essential is missing for an agent to know when and how to call it.

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

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

The tool has zero parameters, so there is nothing for the description to explain beyond what the empty input schema already shows. The description adds no parameter-specific semantics because none 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 names a specific verb ('List') and resource ('constraint types and their parameter schemas'), and clarifies that these are constraints usable in a pricing pipeline. This distinguishes it clearly from the many other list_* sibling tools, all of which target different resources.

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

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

The description gives clear context: this is the reference listing for constraint types available to pricing pipelines. It does not explicitly name alternatives or exclusions, but no sibling tool appears to serve the same purpose, so the omission is not harmful.

Agents often have multiple tools that could apply. Explicit usage 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, but the description discloses key behaviors: newest-first ordering, the times_redeemed vs total_uses row semantics, and the proof requirement. It could add pagination or failure behavior, but it covers the essentials for a list endpoint.

Agents need to know what a tool does to the 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, each earning its place: scope and ordering, row-level data semantics, and access restriction. 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?

The output schema is present, and the description provides ordering, row counters, and access rules. However, the undocumented dpop_token and the unresolved distinction from list_my_coupons leave gaps for an agent selecting and invoking the tool correctly.

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

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

The schema has only dpop_token with 0% description coverage, and the description never names or explains this parameter. 'Requires proof' hints at authentication but does not explicitly map the proof requirement to dpop_token, leaving the agent uncertain about whether and how to provide it.

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

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

The description clearly states the operation: list every coupon this operator has minted, ordered newest first. It identifies the resource and scope, though it doesn't explicitly differentiate itself from the sibling tool list_my_coupons.

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

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

The description explicitly restricts usage to the operator role and warns that proof is required. It doesn't name alternatives or give when-to-use guidance beyond that, but the restriction provides clear context for who should call it.

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

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

With no annotations provided, the description carries the full burden. It discloses useful behavior: the operation returns metadata only and is ordered newest first. However, it does not explicitly confirm a read-only operation, mention authentication or billing implications of the npub parameter, or describe pagination or error behavior, leaving gaps.

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

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

A single, front-loaded sentence with no filler. 'List your stored designs' is clear, and the em-dash efficiently adds key behavioral details. Every word contributes to 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 presence of an output schema reduces the need to describe return values, and the description covers the core operation, ordering, and metadata-only nature. But with no annotations, no parameter clarification, and minimal usage guidance, the definition is adequate but leaves meaningful contextual gaps.

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

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

The description provides no parameter information. Schema description coverage is 50%, with dpop_token lacking any description and npub stated as 'Required' in its description while the schema's required array is empty. The tool description adds no value beyond the incomplete schema, so agent understanding of parameters remains weak.

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

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

States a specific verb and resource: 'List your stored designs' clearly identifies what the tool does. Adding 'metadata only, newest first' distinguishes it from siblings like fetch_design and list_design_versions, so an agent can understand its 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 implies the tool is for retrieving an overview of stored designs as metadata, but it does not explicitly state when to prefer this over related tools like fetch_design or list_design_versions. There is no exclusionary guidance or mention of alternatives, so the usage context is only implicit.

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

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

With no annotations, the description carries the behavioral burden. It discloses the ordering ('newest first'), the read-only nature ('List... committed versions'), and the exact fields returned (`sha`, `short_sha`, `date`, `message`, `tag`, `commit_url`). It does not discuss pagination or error conditions, but for a version-listing read operation this is a solid, non-misleading disclosure.

Agents need to know what a tool does to the 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 first sentence front-loads the core purpose in a compact, scannable way. The second sentence adds only high-value output-field details and a forward pointer to roastify_fetch_design. There is no fluff or repetition of schema 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?

For a moderate-complexity list tool with an output schema and clear input schema, the description covers the essential context: what is listed, in what order, what each entry contains, and how the result feeds into a sibling tool. It omits minor details like pagination or failure behavior, but nothing critical prevents an agent from invoking it correctly.

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

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

Schema description coverage is 67%, with `design_id` described as 'The id from roastify_list_designs.' The description reinforces that relationship by saying the versions belong to a stored design, but it adds no new meaning for `npub` or `dpop_token`. Since the schema already documents most parameters, the description neither significantly helps nor hurts parameter understanding.

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

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

The description uses a specific verb ('List'), a clear resource ('a stored design's committed versions'), and an ordering detail ('newest first'). The 'git history' metaphor and the mention of fetching exact versions via roastify_fetch_design make it easy to distinguish from siblings like roastify_list_designs.

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

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

The description provides clear context for when this tool is useful — to inspect committed version history before fetching a specific version. It explicitly tells the agent to pass the returned `sha` (or `tag`) as the `ref` to roastify_fetch_design, which effectively routes to the next step. It does not explicitly list exclusions or alternative tools, but the inter-tool guidance is strong enough.

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

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

No annotations are provided, so the description carries the burden. It discloses that the call is free, requires proof of npub, and returns both active and exhausted redemptions with a per-row status. It does not explicitly state side effects or read-only behavior, but 'List' plus the returned statuses implies a non-mutating 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 short sentences with no filler. The primary purpose is front-loaded, followed by the useful return-status detail and the free/auth prerequisite. 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?

The description covers the core purpose, return status semantics, cost, and an authentication prerequisite, and an output schema exists. However, the dpop_token parameter is left completely unexplained, and the meaning of 'proof of npub' is ambiguous relative to the schema parameters. This leaves minor but real gaps for an agent trying to invoke the tool correctly.

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

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

Schema description coverage is 0%, yet the description only loosely ties npub to 'proof of npub'. It does not explain what format npub should take, and it never mentions the dpop_token parameter at all. For a low-coverage schema, the description must compensate more than this.

Input schemas describe structure but not intent. Descriptions should explain 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 a specific verb and resource: 'List the coupons this patron has redeemed on this operator.' It goes on to describe the returned statuses, and its patron/operator scoping differentiates it from siblings like roastify_list_coupons. The agent knows exactly 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?

The description gives a clear context for when to use the tool: when listing a patron's redeemed coupons on the operator. It does not explicitly name alternatives or exclusion conditions, but the scope is precise enough that the intended use 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?

With no annotations, the description bears the behavioral burden. It usefully discloses the paginated, one-page-at-a-time behavior and the has_next_page/end_cursor contract. However, it does not explicitly state that the operation is read-only, mention auth or credit-billing implications, or describe rate limits or failure behavior.

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

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

Two short sentences: the first states the purpose and scope, the second adds essential pagination behavior. There is no filler, and the most important information is front-loaded.

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

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

For a simple read-only paginated list, the description covers scope, pagination, and the returned cursor contract. The output schema exists and the parameter schema covers most inputs. It is slightly incomplete only in not addressing sibling selection or the undocumented dpop_token, but it is sufficient for correct invocation in most cases.

Complex tools with many parameters or behaviors need more documentation. 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 documents npub, limit, and cursor with clear descriptions, covering 75% of parameters. The description adds no new parameter-level meaning beyond mentioning pagination cursors, and the undocumented dpop_token parameter is not compensated for.

Input schemas describe structure but not intent. Descriptions should explain 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 a specific verb ('List') and resource ('your own saved Roastify product designs'), and the 'own saved' scope distinguishes it from catalog or design-list tools. However, it does not explicitly name or contrast sibling tools like list_designs or browse_catalog, so it falls just short of full differentiation.

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

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

The phrase 'your own saved ... product designs' implies this is for paginated access to the caller's own designs rather than all designs or the public catalog. There is no explicit guidance about when to choose this over siblings or when not to use it, leaving the agent to infer from context.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It only says 'List recent...' which implies a read operation, but it does not explicitly state that it is non-destructive, how records are ordered, or what 'recent' means.

Agents need to know what a tool does to the 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 one concise sentence with no filler words and the core action is front-loaded. It is appropriately short for a simple list tool, though it omits useful context that could justify a higher completeness score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 and both optional parameters documented in the schema, the description is minimally viable for calling the tool. However, the lack of annotations and absence of any usage guidance leave gaps around expected behavior and when this tool should be selected.

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

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

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

The description states a specific verb and resource: it lists recent Bitcoin notarization records. The 'list' verb differentiates it from related tools like roastify_get_notarization_proof and roastify_notarize_ledger, though it does not name them or elaborate on 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 provides no guidance on when to use this tool versus alternatives, such as retrieving a single proof or creating a notarization. There are no explicit usage conditions or exclusions.

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

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

With no annotations, the description carries the full burden for behavioral disclosure, but it only says 'Create'. It does not disclose side effects, duplicate-name handling, ownership requirements, idempotency, or whether minting has costs or authority constraints. The schema hints at operator-scoped uniqueness, but the description leaves the behavioral consequences opaque.

Agents need to know what a tool does to the 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 compact sentence with no redundant wording, and the key ownership qualifier 'operator-owned' is front-loaded. It is efficient, though it could carry more useful context without becoming bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 7-parameter mutation tool with no annotations and no usage guidance, this description is too thin. It gives the basic purpose but omits lifecycle context, uniqueness conflict behavior, and the relationship to sibling tools like update_coupon, delete_coupon, list_my_coupons, and redeem_coupon. The presence of an output schema covers return-shape expectations, but not the operational context an agent needs.

Complex tools with many parameters or behaviors need more documentation. 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%, so the input schema already explains most parameters. The description adds no parameter-level meaning beyond the schema, including for the undocumented dpop_token field. A baseline 3 is appropriate because the schema carries the heavy lifting.

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

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

The description states a specific verb and resource — 'Create a new operator-owned discount coupon' — and the 'operator-owned' qualifier distinguishes it from patron-facing coupon actions. It is immediately distinguishable from sibling tools like update_coupon, delete_coupon, and redeem_coupon.

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

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

The word 'new' implies this is for minting rather than updating an existing coupon, but there is no explicit when-to-use guidance or mention of alternatives. It does not tell the agent to prefer update_coupon for existing coupons or explain any prerequisites for minting.

Agents often have multiple tools that could apply. Explicit usage 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 transparency burden, and it delivers: it discloses the commit/versioning behavior ("edit is committed back to the SAME design_id"), the absence of bounds validation ("the caller owns the coordinates"), and a safe default ("The heavy background image is never moved unless you name its id"). It does not explicitly address reversibility or auth side effects, but the version-commit framing and risk warnings are substantial.

Agents need to know what a tool does to the 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 core purpose and uses three short paragraphs, each earning its place: motivation, mechanism/commit semantics, and validation caveats. There is minor redundancy with the schema (e.g., commit/version details appear in both places), but the prose is efficient and readable for the tool's complexity.

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

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

For a complex mutating tool with no annotations and an output schema present, the description covers the key contextual gaps: when to use it, why it exists, how edits behave, what is not validated, and where to find input ids. It does not mention the closely related roastify_update_design_text for text-only cases, but the high parameter-level detail and output schema make the definition sufficiently complete for an agent to invoke it correctly.

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

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

Schema coverage is high at 86%, so the baseline is 3, but the description adds real parameter-level meaning beyond the schema: it tells the caller that coordinates are not validated and are the caller's responsibility, that the background image id should generally not be included, and that element ids/current geometry should be sourced from roastify_get_design_text. These are practical semantics an agent could not infer from the JSON schema alone.

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

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

The opening sentence states a specific verb and resource: "Move a group of elements together and/or resize elements; commit a new version." It also differentiates itself from siblings by explicitly contrasting with add_design_element ("Nothing is validated against panel bounds here") and by describing the unique rigid-block relocking use case. An agent can distinguish this from the many design-manipulation siblings without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 a concrete triggering scenario ("a block of layered content ... drifts out of alignment"), explains that this tool relocks the block, and explicitly names an alternative: "unlike add_design_element." It also tells the caller to source ids from roastify_get_design_text. It does not, however, clarify when the related roastify_update_design_text would be preferred for text-only edits, so the guidance is strong but not fully exhaustive.

Agents often have multiple tools that could apply. Explicit usage 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 behavioral disclosure burden. It does a good job: it reveals this is asynchronous, takes 1-6 hours for Bitcoin confirmation, is operator-only, and is free/no credits. It does not mention return behavior or failure modes, but the main behavioral traits are disclosed.

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

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

Three tight sentences: the core action is first, then operator/background constraint, then timing and cost. No filler or repetition, and every sentence adds relevant information.

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

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

For a zero-parameter background task with an output schema available, the description covers the essential operational context: what it does, who should run it, how long it takes, and that it costs nothing. Nothing necessary for an agent to invoke it correctly is missing.

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

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

There are zero parameters, so the schema is already fully complete. The description adds the meaningful context that the tool operates over all patron balances with no inputs, which is consistent with the empty schema. Baseline 4 for zero parameters is appropriate.

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

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

The description states a specific verb-resource pair: 'Build a Merkle tree of all patron balances and submit the root to Bitcoin via OpenTimestamps.' This is unambiguous and clearly distinct from the many sibling tools, none of which describe this blockchain notarization action.

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

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

The description clearly frames when this is appropriate: it is an operator-only background task, and it notes the long confirmation delay. It does not explicitly name sibling alternatives or exclusions, but the operator-only and background context is enough to guide appropriate selection.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, but it only adds 'via the Oracle' and 'Free.' It does not state whether the operation is read-only, whether it has side effects, or what kind of response to expect beyond the output schema. This is a thin behavioral profile for an agent.

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

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

The description is ten words, front-loaded with the verb and object, and contains no fluff. The final 'Free.' sentence earns its place by signaling cost-relevant behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 informational tool with an output schema, the description is sufficient for an agent to invoke it. It lacks explicit differentiation from sibling oracle tools and any mention of limitations, but given the tool's simplicity this is a minor 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?

The input schema has zero properties, so there are no parameters to document. The description appropriately adds nothing about parameters, and with no params the baseline is a pass.

Input schemas describe structure but not intent. Descriptions should explain 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 a clear verb ('Describe') and a resource ('the DPYC ecosystem'), so an agent can recognize it as a general informational tool. It does not explicitly distinguish itself from sibling oracle_* tools, but the name 'about' and the generic scope make the intent reasonably clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 about when to use this tool versus sibling tools such as roastify_oracle_get_tax_rate, roastify_oracle_how_to_join, or roastify_oracle_lookup_member. The description leaves usage routing entirely to inference from the tool name.

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

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

With no annotations, the description carries the behavioral burden. 'Get' conveys a read-only action and 'current' implies a live value, but nothing is disclosed about data source, staleness, rate limits, or error behavior. The 'Free' note is a small behavioral clue about cost but is not enough for full transparency.

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

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

The description is front-loaded and extremely short: the core purpose appears in the first clause. 'Free.' is arguably unnecessary and mildly ambiguous, but the overall density is good for a parameterless getter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 read with an output schema, the definition is close to sufficient, but it leaves DPYC undefined and does not explain how this tax rate relates to the oracle/pricing siblings. The output schema may cover the return shape, but contextual meaning is still thin.

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

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

The tool has zero parameters and the schema coverage is 100%, so there are no parameter semantics to explain. Per the rubric, a zero-parameter tool gets a baseline of 4; the description does not need to add parameter detail.

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

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

The description uses a specific verb and resource ('Get the current DPYC certification tax rate'), making the tool's purpose immediately identifiable. It is distinguishable from siblings like check_price and get_pricing_model by the tax-rate scope, although the DPYC acronym is never expanded and the standalone 'Free.' adds no functional detail.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidance about when to call this oracle versus the many related sibling tools (e.g., check_price, get_pricing_model, oracle_about). The word 'Free' hints at cost but does not state conditions, alternatives, or exclusions.

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

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

No annotations are provided, so the description is the sole source of behavioral context. 'Free' usefully signals that the call is cost-free, and 'Get ... instructions' implies a read-only information retrieval, but the description does not mention side effects, access requirements, or what the Oracle returns. For a no-parameter informational tool this is acceptable but not rich.

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

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

The description is two short sentences with no filler. It front-loads the primary purpose and appends a single relevant detail ('Free'). 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 tool takes no parameters and has an output schema, the description is nearly complete for invocation. The only slight gap is that 'DPYC' and 'the Oracle' are domain-specific and not elaborated, but the surrounding sibling-tool context makes the intent recoverable.

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

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

There are no parameters, so there is nothing for the description to explain beyond the invocation itself. The baseline for a zero-parameter tool is high, and no semantic gap 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 states a specific action ('Get ... instructions'), the resource ('DPYC onboarding instructions'), and the source ('from the Oracle'). It is distinguishable from related siblings like roastify_get_operator_onboarding_status because it provides a how-to-join guide rather than a 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 intent is clear: this should be used when the agent needs DPYC onboarding/joining instructions. However, it does not explicitly name alternative tools or state when not to use it, so it stops one step short of full routing 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?

There are no annotations, so the description carries the behavioral transparency burden. 'Look up' strongly implies a non-mutating read, and 'Free' adds a cost-related behavior, but the description does not explicitly mention read-only semantics, authentication needs, or not-found behavior. Still, for a simple lookup, the verb provides reasonable behavioral clarity.

Agents need to know what a tool does to the 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 sentences with no fluff. The core action and key are front-loaded, and 'Free.' is an efficient extra signal. Nothing in the description wastes an agent's attention.

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

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

For a single-parameter lookup with an output schema, the description is minimally workable: an agent knows to pass an npub and expect a DPYC member. However, it omits usage differentiation and any parameter semantics beyond the name, so it is not fully complete for confident tool selection among many similar sibling tools.

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

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

The only parameter, 'npub', has no schema description (0% coverage), and the description merely says 'by npub,' which basically restates the parameter name. It does not explain what an npub is, what format is expected, or how it identifies a DPYC member, so it 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 states a specific verb ('look up'), a concrete resource ('DPYC community member'), and the lookup key ('npub'). This clearly distinguishes it from sibling tools like roastify_get_nostr_profile by narrowing the scope to DPYC members. 'Free' is extra but does not obscure the purpose.

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

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

The description gives no guidance on when to use this tool versus alternatives such as roastify_get_nostr_profile or other oracle_* tools. There are no preconditions, exclusions, or hints about which scenario selects this tool over its siblings.

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

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

No annotations exist, so the description carries the behavioral burden. The verb 'Get' implies a non-mutating read and 'Free' adds cost context, but the description does not disclose staleness, authorization requirements, or what 'active' means beyond what the output schema likely covers.

Agents need to know what a tool does to the 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 sentences with no filler. The core action and resource are front-loaded, and 'Free' is a compact, useful addition for a zero-parameter read tool.

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

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

For a zero-parameter read with an output schema present, the description sufficiently communicates the source and scope. Minor gaps remain—such as data freshness or relation to service status—but they are not critical for basic invocation.

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

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

The input schema has zero parameters with 100% schema description coverage, so there is nothing for the description to add about parameter semantics. Baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain 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 a specific verb ('Get'), a specific resource ('active network advisories'), and a source ('the Oracle'), which clearly distinguishes it from siblings like roastify_oracle_about and roastify_oracle_get_tax_rate. There is no ambiguity about what action this tool performs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 purpose implies when an agent would use this tool—whenever active network advisories are needed—but it does not explicitly say when to prefer it over alternatives such as roastify_service_status. 'Free' hints at access cost, but there is no when-not-to-use or alternative routing 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 disclosure burden — and it delivers: it reveals that the wheel never holds the patron's nsec, that it verifies the signature against the npub before relaying, that the signature itself is the authorization (no proof token), and that the operation is free. This is exceptional behavioral transparency for a publish 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 first sentence is a front-loaded TL;DR stating the essential decision information. Every subsequent sentence earns its place with a distinct fact — key custody, signing mechanism, verification, auth model, cost — and there is zero filler. Well-paced paragraph structure.

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

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

For a two-parameter tool with an output schema, the description comprehensively covers the workflow, prerequisites, security model, and cost. The notable gaps are failure behavior (what happens when the signature does not match the npub) and the schema's required:0 being inconsistent with the description's clear implication that both parameters are needed.

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

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

Schema coverage is 100%, so both parameters are already documented in the input schema. The description adds some relational context — the wwheel checks that the signed_event signature matches the npub parameter — but it doesn't add format, encoding, or call-construction details beyond the schema.

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

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

The opening sentence states a specific verb (publish) + resource (client-signed kind-0 profile) + destination (relays for an npub), and the CLIENT-SIGNED qualifier sets it apart from the sibling get_nostr_profile, wich is read-only. An agent can tell immediately what this tool does and why it differs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 lays out the exact precondition or using this tool: the frontend must have already signed a kind-0 event with a session key or NIP-07 extension and passes the signed JSON here. Wile it clearly implies when the tool is appropriate, 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 provided, the description carries the full behavioral disclosure burden. It transparently states that the tool creates a Lightning invoice, requires proof of npub ownership for correct credit allocation, and is free to call. It also clarifies the expected payment flow, giving the agent a realistic picture of side effects and prerequisites.

Agents need to know what a tool does to the 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 short, front-loaded with the core purpose, and every sentence adds value. It covers what happens, what the user must do next, and a key prerequisite, without extraneous detail.

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

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

Given the output schema exists and the parameter schema is fully documented, the description is complete enough for an agent to invoke the tool correctly. It captures the operational flow, prerequisite authentication requirement, and pricing/cost model, which are the details not present in the structured 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 100%, so the schema already documents npub, dpop_token, and amount_sats in detail. The description adds minimal parameter-specific meaning beyond mentioning proof of ownership and the free-cost property, which aligns with the baseline score for fully covered schemas.

Input schemas describe structure but not intent. Descriptions should explain 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 a specific verb and resource ('Buy credits via Bitcoin Lightning') and explains the mechanism (creates a Lightning invoice). It is clearly distinguishable from sibling tools like check_balance or restore_credits, and it even names check_payment as the follow-up confirmation step.

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

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

The description provides a clear usage workflow: create the invoice, pay it with any Lightning wallet, then call check_payment. It does not explicitly discuss when not to use this tool versus alternatives, but the context is strong enough for an agent to understand the primary use case.

Agents often have multiple tools that could apply. Explicit usage 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 behavioral burden and succeeds. It discloses destructive side effects (wrong-phrase DMs are deleted and senders NACK'd), the acceptance/stop condition, the queue-drain failure mode (courier_not_found), and the internal reinitialization of the payment processor client. This is unusually transparent for a tool involving credential delivery.

Agents need to know what a tool does to the 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 detailed but every sentence earns its place, covering the flow, the critical precondition, the one-shot/destructive behavior, and the alternate credential_card path. The core instruction is front-loaded, with supporting semantics arranged logically. No filler 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—two retrieval paths, destructive relay draining, and a credential-card bypass—the description covers all necessary decision points and outcomes. The existence of an output schema means return-value details do not need to be repeated. An agent has enough context to know when and how to call it safely.

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

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

Schema coverage is 100%, so the schema already documents individual parameters. The description adds meaning beyond the schema by explaining how the three parameters (sender_npub, service, dpop_token) jointly identify the desired response. It also clarifies the credential_card parameter's effect: it bypasses relay access and makes dpop_token unnecessary.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Pick up credentials from the Secure Courier.' It clearly identifies the tool as completing the CREDENTIAL-DELIVERY flow and even names its ownership-proof counterpart (receive_npub_proof), which distinguishes it from the large sibling set. The scope is unambiguous.

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

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

The description gives explicit when-to-call guidance: 'Call this only after the user confirms they have replied.' It then states deterministic, one-shot retrieval and the imperative 'Do NOT poll, loop, or retry,' which is a direct usage boundary. It also explains when the credential_card path should be used instead of the relay-drain path.

Agents often have multiple tools that could apply. Explicit usage 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 behavioral burden, and it does so thoroughly. It discloses one-shot deterministic retrieval, relay draining, deletion and NACK of mismatched DMs, early-call consequences, the fact that the signed DM proves ownership, token handling requirements, vault storage hashing, and that the operation is free.

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

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

The description is long but information-dense, with critical urgency and usage guidance front-loaded in bold. Some repetition exists around the `dpop_token` being 'the same token' and 'value returned by request_npub_proof,' but each paragraph serves a distinct purpose: flow context, invocation rules, and postconditions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 complex two-parameter flow-completion tool with no annotations, the description is remarkably complete. It covers prerequisites, behavior, failure conditions, return semantics, follow-up obligations for the caller, and security-relevant storage details. The existence of an output schema means return-value structure does not need to be described in prose.

Complex tools with many parameters or behaviors need more documentation. 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 meaningful context beyond the schema by explaining that `dpop_token` is the exact value returned by `request_npub_proof`, must be remembered by the calling application, and will be returned unchanged on success. It also frames `patron_npub` as what identifies the response to retrieve.

Input schemas describe structure but not intent. Descriptions should explain 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 a specific verb and resource: 'Receive npub ownership confirmation from a patron.' It clearly situates the tool within the npub-OWNERSHIP-PROOF flow and explicitly names its counterpart `receive_credentials`, so an agent can distinguish it from related tools without opening schemas.

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

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

The description gives explicit when-to-call guidance: 'Call this only after the user confirms they have replied.' It also provides strong exclusion guidance with 'Do NOT poll, loop, or retry' and names the related flow via `request_npub_proof` and `receive_credentials`, making the selection criteria clear.

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

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

With no annotations, the description carries the full burden, and it does well: it discloses that the call is deterministic, one-shot, drains ONLY the pinned rendezvous relay, stops at the matching DM, and is free. The word 'drains' also usefully signals potential consumption of the message. It could clarify what happens when no match is found, but this is substantial disclosure.

Agents need to know what a tool does to the 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 every clause earning its place: main action, mechanism, parameter usage, the 'do not poll' warning, and the cost disclosure. The backtick notation adds a little visual noise but no bloat. It is tightly written.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 retrieval tool with an output schema, the description covers mode selection, parameter roles, and behavioral constraints. The main gaps are whether sender_npub and dpop_token are both mandatory for the first path, whether credential_card alone suffices for the second, and the not-found outcome. Still, the essential calling information is present.

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

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

Schema coverage is 0%, so the description is the only explanation for the parameters. It explains that sender_npub and dpop_token together name the response, and that credential_card is an alternative path where dpop_token is not required. This maps clearly to all three properties, though it doesn't specify exact formats for sender_npub or dpop_token.

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

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

The description opens with a concrete verb and resource: 'Pick up patron credentials from the Secure Courier.' It then specifies the deterministic, one-shot retrieval mechanism and names the two supported paths (sender_npub+dpop_token or credential_card). This clearly distinguishes it from sibling tools like roastify_receive_credentials and roastify_get_patron_credential_fields.

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

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

Provides explicit operational guidance: name the response with (sender_npub, dpop_token) or provide a credential_card to redeem directly, and explicitly warns 'Do NOT poll or retry.' While it doesn't name alternative sibling tools or state when to prefer this over roastify_receive_credentials, the two paths and the no-poll/retry directive give strong context for when 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 behavioral burden and does so thoroughly: validation of window and cap, recording of redemption rows, idempotency, lack of credit cost, npub proof requirement, and future discount side effects. This is strong disclosure for a state-changing redemption 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 front-loaded with the core purpose, then proceeds through process, side effects, pricing, prerequisite, and idempotency without wasted words. 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?

Coverage is strong: purpose, validation behavior, idempotency, pricing, prerequisite, and subsequent effects are all described, and an output schema exists so return values need not be restated. It remains slightly incomplete around 'dpop_token' and the exact mechanism for satisfying the npub proof requirement.

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

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

The description adds meaning for 'code' as the operator-shared coupon code and connects 'npub' to the proof requirement. However, with 0% schema description coverage, the optional 'dpop_token' parameter is left unexplained, leaving a real 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?

States a specific verb ('Claim') and resource ('coupon'), and clarifies that the code is the operator-shared coupon code. This cleanly distinguishes it from sibling coupon tools like mint, update, delete, and list.

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

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

Provides clear usage context: free to call, requires proof of npub, and affects subsequent paid tool calls via auto-applied discount. It does not explicitly mention when not to use it or name alternative tools, so routing is left somewhat to inference.

Agents often have multiple tools that could apply. Explicit usage 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 and does well: it discloses that the npub is the author of record, the issue is public, a fee is charged, nothing is verified locally, and the report goes to maintainers' normal triage. It also explains the not-configured case where the user is not charged. This is rich behavioral disclosure beyond what the schema or annotations provide.

Agents need to know what a tool does to the 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-organized: an opening action statement, a motivational context sentence, behavioral consequences, and a return/error summary. Every sentence adds necessary operational or behavioral detail, and the important constraints are front-loaded. Despite length, it earns its length with high-value 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?

The description covers purpose, prerequisites, costs, privacy/publicity, attribution, expected behavior, return values, and the error case. The schema and output schema provide the remaining parameter and output structural details. An agent has everything needed 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 baseline is 3; the schema already documents all parameters in detail. The description adds contextual meaning around npub and the cost/failure behavior, but it does not meaningfully elaborate the individual parameter semantics beyond the schema. It adequately complements rather than replaces 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 and resource: 'File a field report about this service as a GitHub issue on the operator's repo.' It clearly explains the purpose and provides concrete context ('Found a tool's metadata or response wrong or confusing?'), making it easy to distinguish from the many sibling tools. No sibling has a similar reporting function, so no further differentiation is needed.

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

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

The description gives clear conditions for use: report a tool when its metadata or response is wrong or confusing. It also states what happens if the operator has not enabled field reports, which helps the agent anticipate failure. It does not explicitly mention alternatives or when not to use it, but no sibling alternative exists for this action.

Agents often have multiple tools that could apply. Explicit usage 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 behavioral burden. It discloses that the call mints an ownership proof with the operator's nsec, resolves the Authority endpoint from the registry, delivers the request MCP-to-MCP, records it as pending, and only flips to ready after the Authority provisions it. This is strong transparency for a state-changing async request.

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

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

Four front-loaded, information-dense sentences with no filler. Each sentence contributes a distinct fact: purpose, restriction, mechanics, and asynchronous follow-up. The 'deferred courtship' phrasing is slightly colorful but immediately contextualized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 multi-step, async, restricted-caller tool, the description covers preconditions, the delivery mechanism, the pending/approval lifecycle, and the polling path. With 100% parameter schema coverage and an output schema present, an agent has enough to invoke it correctly; failure modes would be nice but are not essential.

Complex tools with many parameters or behaviors need more documentation. 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 some context around ownership proof and the MCP-to-MCP flow, but it mostly reinforces what the parameter descriptions already state rather than adding meaningfully new detail.

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

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

The description opens with a specific verb and object: 'Ask a chosen Authority to adopt this operator.' It clearly identifies the deferred/adoption nature and distinguishes itself from status-related siblings by directing the caller to poll adoption_status for progress.

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

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

The description explicitly restricts usage to the operator and requires proof of npub ownership, telling the caller who may invoke it. It also points to adoption_status for progress checking, an effective alternative, though it does not enumerate other when-not-to-use scenarios.

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