roastify-mcp

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

With no annotations, the description carries the behavioral burden and discloses important facts: the call is free (no credits consumed) and requires proof of npub ownership to prevent scraping. It does not mention failure modes or side effects, but the read-oriented 'Returns...' wording plus the auth disclosure cover the main risks.

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

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

Four short sentences with no filler; purpose and return contents are front-loaded, and the scope distinction, cost, and auth requirement are stated in separate compact sentences. 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 is largely complete for selection and invocation: it names what is returned, clarifies account scope, states cost, and flags the auth prerequisite, with output schema covering return structure. It would be more complete if it pointed to the infographic sibling or any pertinent exclusions, but an agent can act on this definition.

Complex tools with many parameters or behaviors need more documentation. 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 value by explaining why dpop_token is required (proof of ownership to prevent scrapes) and by clarifying that 'days' maps to recent daily usage logs. The schema already handles technical token construction details.

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

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

Clearly identifies the resource (patron's account statement) and the returned content (purchase history, credit tranches, usage breakdown, daily logs). It also distinguishes this from the operator's Authority tax balance, but it does not explicitly differentiate the near-namesake sibling roastify_account_statement_infographic.

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

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

The description gives clear context for when to use this tool: when a patron's spending-account statement is needed, and explicitly says it is not the Authority tax balance. It does not name alternative sibling tools or state when to prefer a different statement format, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage 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 disclosure burden and does so well: it reveals the dark-themed SVG output structure, the 1 api_sat cost per call, and that proof is verified by debit_or_deny before any cost is incurred. These are meaningful behavioral details 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?

Three sentences, each earning its place: the first states the core purpose, the second details the output and sibling relationship, the third covers cost and verification ordering. 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 3-parameter tool with an output schema, the description covers what the tool produces, how it relates to the sibling, and the cost/verification side effects. Nothing essential for selecting or invoking the tool 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?

Schema description coverage is 100%, so npub, dpop_token, and days are already fully documented. The description adds no additional parameter-level meaning beyond the schema, 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?

States a specific verb and resource: generate a visual SVG infographic of an account statement. It also distinguishes itself from the sibling account_statement tool by explicitly saying it returns the same data rendered as a graphic.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 positions this tool as the visual variant of account_statement, implying when to choose it over the non-graphic sibling. It does not explicitly state 'use account_statement when you need raw data,' but the context is direct and easy for an agent to follow.

Agents often have multiple tools that could apply. Explicit usage 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 disclosure burden, and it does well: it explains git-tracked version commits, server-side refusal on invalid placement, overlap collision behavior, typography inheritance, and the no-new-upload rule for images. The phrase 'Typography is inherited for text, so a new text element matches the template' is slightly ambiguous because style_from is described as required for text in the schema.

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

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

The description is dense but well organized: purpose first, then versioning, then placement rules, then text/image-specific behavior. Every sentence adds useful operational detail, and the length is justified for a complex 16-parameter mutation tool with no annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 this complex and with no annotations, the description covers the essential invocation context: versioning, related tools, placement constraints, panel/sheet behavior, and asset reuse rules. An output schema exists so return-value details are covered, but the ambiguity around style_from vs 'template' keeps it from being fully complete.

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

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

Schema coverage is high at 94%, so the baseline is 3, and the description adds meaningful operational context beyond the schema: same design_id commitment, kind-specific src/src_from reuse, server-side placement validation, and no-upload enforcement. It does not add much about dpop_token, but that is a minor gap given the schema's high 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 opens with a specific verb and resource: 'Add a new element (text or image) to a design and commit a new version of it.' It clearly identifies the operation, the target design, and the versioning side effect, and it is easy to distinguish from siblings like update_design_text and move_elements.

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

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

The description gives practical sequencing guidance by naming update_design_text and move_elements as the follow-up tools after the new element is created. It also explains when sheet-based placement applies vs panel-based placement, though it does not explicitly state 'use this when adding, not when editing' as a direct exclusion.

Agents often have multiple tools that could apply. Explicit usage 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 adds useful traits: the call is 'Free', it 'Polls the Authority MCP-to-MCP', and it reports pending/approved/rejected/provisioned statuses. However, it does not state whether the operation is read-only, what authentication the dpop_token relates to, or any side effects.

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

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

The description is three short sentences with no filler. The main purpose is front-loaded, and each subsequent sentence adds distinct information about cost, polling behavior, and returned statuses.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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-value documentation is not necessary, and the core status-check purpose is covered. However, with no annotations and 0% parameter schema coverage, leaving dpop_token unexplained and not referencing the related request tool makes the definition slightly incomplete for an agent.

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

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

Schema description coverage is 0%, so the description must explain both parameters. It only maps 'chosen Authority' to authority_npub and completely ignores dpop_token, leaving the optional authentication token's purpose and format unexplained.

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

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

The description opens with a specific verb and resource: 'Check this operator's adoption-request status at a chosen Authority.' It also lists the possible statuses, making the tool's purpose concrete and clearly distinct from action-oriented siblings like roastify_request_adoption.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 this is the status-check counterpart to adoption requests and mentions polling via the Authority MCP-to-MCP, but it never explicitly says when to use this tool versus roastify_request_adoption or roastify_get_operator_onboarding_status. Usage context is present but left 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 the behavioral disclosure burden. It adds useful safety context ('polling never costs anything') and explains the two terminal states of a job ('artwork_url' vs. 'error'). It does not detail rate limits or integration requirements, but the core behavior is transparent.

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

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

The description is extremely compact and front-loaded: the core action is stated first, followed only by two high-value clarifications (free polling and outcome fields). 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 simple status-check tool with an output schema, the description provides enough operational context: it is a safe pollable read, and the key success/failure fields are named. It does not explicitly describe the full workflow or explain dpop_token, but those gaps are minor given the schema and 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 67%, and job_id and npub already have meaningful schema descriptions. The tool description itself adds no parameter-level meaning, and dpop_token remains undocumented. The npub 'Required' wording conflicts slightly with the schema's required list, which the description does not clarify.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Check a Roastify artwork job') and clarifies it is a status/polling operation. The mention of finished vs. failed outcomes further distinguishes it from generation or other roasting 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 clearly implies this is for checking the status of an artwork generation job and explicitly says polling is free, so it can be safely repeated. It does not explicitly name sibling alternatives or state 'use after roastify_generate_artwork', but the schema's job_id description fills that gap.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses that plan-gated items are returned with tier markings rather than hidden, that certain catalog attributes (origin, altitude, processing, varietal) are absent, and that roast level and decaf status come from the blend. This is valuable 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 main purpose is in the first sentence, followed by two short, relevant behavioral notes. Every sentence earns its place with 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 description covers what the tool returns, behavioral visibility of plan-gated items, and an important data-limitation caveat. An output schema exists, so return structure does not need to be spelled out. It could be more complete with explicit guidance about when to prefer this over roastify_get_catalog_product or roastify_get_blend, but it is otherwise sufficient.

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

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

Schema description coverage is only 50%: npub is documented but dpop_token has no explanation. The tool description adds nothing about either parameter, so it does not compensate for the undocumented token or clarify how the billing-related npub is used.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Browse the Roastify catalog' and clarifies it returns 'products and coffee blends together.' This clearly distinguishes it from narrow sibling tools like roastify_get_catalog_product or roastify_get_blend, stating both the resource and the 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 establishes a clear usage context: this is the tool for browsing the full catalog, and the phrase 'products and coffee blends together' signals it is not for fetching a single product or blend. It does not explicitly name alternatives or exclusion criteria, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage 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 clarifies that the balance is operator-owned funding rather than a patron balance, explains the consequence of a zero balance, and directs the operator to purchase_credits as the remedy. The read-only nature is implied by 'Check,' and the output schema covers return details.

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

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

The description is tight and front-loaded with the core action, then adds meaningful context in short sentences. Every sentence earns its place: what the balance is, how it is used, what happens at zero, and a clarifying exclusion from patron balance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 parameterless read-only tool with an output schema, the description is complete. It covers the purpose, the meaning of the returned value, the zero-balance failure mode, the required remediation, and the distinction from patron balances. No critical operational information 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 tool has zero parameters and schema coverage is 100%, so there is no parameter documentation burden. The baseline of 4 applies; the description adds useful conceptual context even though no parameters exist to explain.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Check') and a specific resource ('this operator's tax balance at the Authority'), then defines the balance's purpose: sats available for certifying patron credit purchases. It also distinguishes itself from the sibling check_balance by emphasizing that this is the operator's own funding, not a patron balance.

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

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

The description gives clear context for when this tool matters: checking funds available for certifying patron top-ups, and notes that when the balance reaches zero, the operator must call purchase_credits. It does not explicitly enumerate sibling alternatives, but the context makes the appropriate use 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 burden and discloses non-obvious traits: the call is free, requires proof of npub ownership, and protects against balance enumeration. It doesn't detail failure behavior, but the key operational and security-relevant behaviors are 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?

Three short paragraphs with no filler: the core verb+object in the first sentence, differentiation in the second, and cost/security context in the third. Every sentence earns its place and the most decision-relevant 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 two-parameter tool with an output schema, the description covers what the balance is, when to use a different tool, that it is free, and why authentication is required. Nothing an agent needs to decide whether to call it or to interpret its purpose 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?

Schema coverage is 100% and the dpop_token description is thorough, so the schema carries parameter meaning. The description adds only the contextual statement that npub ownership proof is required, which reinforces but does not extend the schema's parameter documentation.

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

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

Opens with a specific verb+resource+scope: 'Check a patron's credit balance at this operator.' It then contrasts patron spending balance with the operator's Authority balance, and the sibling list includes roastify_check_authority_balance, so the tool is clearly distinguishable.

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

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

Explicitly routes the operator-balance use case to 'authority_check_balance instead' and notes this tool is free. Minor deduction because the named alternative does not exactly match the sibling roastify_check_authority_balance, but the intent 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?

No annotations are provided, so the description carries the transparency burden. It discloses that the call is free, that proof of npub ownership is required, and explains why it is required (preventing credit-grant front-running). This meaningfully informs the agent 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 with the core purpose. Every sentence adds value: the what, the when, the cost, and the authentication requirement. 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?

Given the rich input schema, output schema presence, and clear usage context, the description covers all essential operational knowledge: what the tool does, when to call it, its cost, and the required proof. Return values are already covered by the output schema, so no further detail 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?

Schema description coverage is 100% and each parameter already has detailed documentation, including the non-base64 dpop_token framing. The description adds minor context by linking invoice_id to purchase_credits and explaining the security rationale, but it does not need to compensate for schema gaps.

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

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

The description opens with a clear, specific verb-resource pair: 'Check the payment status of a Lightning invoice.' It further distinguishes itself from sibling check tools by tying the invoice to purchase_credits, making the tool's unique role immediately identifiable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 states the free cost and the npub ownership prerequisite. It does not explicitly describe when not to use it or name alternatives, but the sequencing and conditions are clear.

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

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

With no annotations provided, the description carries the burden of behavior disclosure and does a solid job: it says the call is a preview, free, and shows constraint effects such as discounts and surge pricing. It does not mention authentication needs or side-effect absence explicitly, but 'Preview' strongly implies a non-mutating read-like operation, and the free disclosure is valuable.

Agents need to know what a tool does to the 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, the second sentence explains what the output covers, and the third gives a key cost fact. Every sentence adds useful information with no repetition or filler.

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

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

The description is adequate for a simple cost-preview operation, especially with an output schema available, and it conveys the most important non-obvious context ('Free — no credits required'). However, it lacks guidance about when to use this tool versus many similar 'check' siblings, and partial parameter coverage leaves some ambiguity for an agent planning a 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 description provides no parameter-level guidance, and schema description coverage is only 50%: npub and dpop_token are undocumented in both the schema and description. The description's mention of constraint effects loosely relates to tool_kwargs for ad valorem/categorical pricing, but it does not compensate for the undocumented parameters.

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

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

The description clearly states a specific action ('Preview the effective cost of a tool call') and identifies the resource ('a tool call'), with examples of what it shows (base cost, discounts, surge pricing). It is distinguishable from most siblings by focusing on cost preview rather than balances, payments, or stock, though it does not explicitly name or contrast any sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'Preview the effective cost of a tool call' implies the tool is used before making a call to assess cost, and 'Free — no credits required' gives a useful usage condition. However, there is no explicit guidance on when to prefer this over related tools like check_balance, check_payment, or get_pricing_model, nor any exclusions mentioned.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the operation is 'Free, no side effects,' explicitly says it 'does not evict the cache or touch relays,' and frames the tool as a safe pre-flight check. This is strong, concrete behavioral 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 compact and well-structured: purpose first, usage context second, and behavioral safety third. Every sentence earns its place, and there is no redundant restatement of the title 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?

Given the simple two-parameter schema, full parameter descriptions, and the presence of an output schema, the description is complete. It explains what the tool checks, when to call it, and what side effects it avoids. The reference to check_oauth_status is a useful conceptual anchor, even though that exact tool is not listed among siblings.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already documents both dpop_token and patron_npub with meaningful descriptions. The tool description adds useful context about the token being 'previously-cached' and tied to the paid-call flow, but it does not need to add much parameter-level detail because the schema is already complete.

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

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

The description opens with a specific verb and resource: 'Check whether a previously-cached dpop_token is still valid.' It also clarifies the tool's role in the npub-proof flow and says it answers whether a next paid call will accept the token, making its purpose unmistakable and distinguishable from other roastify tools.

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

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

The description explicitly says when to use this tool: 'before burning credits on a guaranteed failure.' It also names the alternative flow it mirrors, 'check_oauth_status,' and gives the condition for this variant: 'for the npub-proof flow.' This gives the agent clear 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, the description carries the full burden. It implies a read-only operation via 'Check', but it does not disclose that the npub parameter is for credit billing (and thus the call likely consumes credits), nor that a DPoP token is involved. No mention of side effects, rate limits, or response behavior is made.

Agents need to know what a tool does to the 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 with no fluff. It conveys the essential operation and the two primary call variants efficiently.

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

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

The description is too sparse for a tool with no annotations. It lacks the critical detail that npub is required for billing, and the schema itself contradicts this by marking no parameters as required. The dpop_token field is left unexplained, and with many sibling check/list tools, more context about stock semantics and invocation prerequisites would be needed for reliable agent use.

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

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

The description adds meaning to the sku parameter by tying it to 'one SKU' versus 'whole stock list', which complements the schema's 'Omit to get the full stock list'. However, the dpop_token parameter has no schema description and no description-level explanation, and the npub billing context only appears in the schema, not the tool description. With 67% schema coverage, the description partially compensates but leaves a gap.

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

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

The description names a specific verb ('Check'), a specific resource ('Roastify stock'), and the two operation modes ('one SKU, or the whole stock list'). This clearly distinguishes the tool from sibling check tools like check_price or check_balance, though it doesn't elaborate on what 'stock' means exactly.

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

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

No guidance is given on when to prefer this tool over alternatives such as roastify_browse_catalog, roastify_get_catalog_product, or roastify_check_price. The description only distinguishes two modes (single SKU vs. full list), not the contextual scenarios that would select this tool.

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

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

With no annotations, the description fully discloses critical behavioral traits: cascading deletion to patron redemptions, no-op behavior for chain steps referencing deleted coupon_id, neutral constraint handling, and Studio warnings for orphan references. This is substantial, concrete behavioral context beyond the tool's 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?

The description is compact and every sentence earns its place: the action, the cascade effect, the no-op semantics, and the access restriction. It is front-loaded with the core purpose and contains 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 presence of an output schema covers return-value expectations. The description addresses key operational concerns: who may call it, what happens to redemptions, how chain steps behave, and how the Studio surfaces issues. The only noticeable gaps are the meaning of 'proof' and the role of dpop_token, which are relevant to successful 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 0%, so the description is expected to compensate. It adds context about coupon_id's role in cascade and orphan references, but it never explains the dpop_token parameter at all. The semantics of both parameters are largely left to inference from names, which is insufficient at 0% 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 opens with a specific verb and resource: 'Delete a coupon.' It is unambiguous and the cascading detail further clarifies the scope of deletion, distinguishing it from sibling tools like roastify_delete_design or 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?

The description clearly states that the tool is 'RESTRICTED to operator' and 'requires proof,' giving the agent clear context about when use is permitted. However, it does not explicitly mention alternative tools or when-not-to-use conditions, so it misses the full 'when vs alternatives' 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 full burden of behavioral disclosure. It only says 'Delete' and does not mention irreversibility, effects on related data, billing/Nostr authentication requirements, or any confirmation step. For a destructive operation, this is a notable gap.

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

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

The description is a single clear sentence with no filler. It is front-loaded with the action and resource, which is appropriately concise for a straightforward delete operation.

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

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

Given that this is a destructive tool with no annotations, the description is incomplete. It should state that deletion is permanent, how to obtain a design_id, and any credential/billing requirements. The output schema covers return values, but the operational context is still under-specified.

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

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

Schema description coverage is 67%, and the tool description adds no parameter-specific meaning. The schema itself provides useful context, especially design_id referencing roastify_list_designs, but the dpop_token parameter remains undocumented and the description does not compensate.

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

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

The description states a specific verb ('Delete') and resource ('one of your stored designs'), clearly distinguishing this from sibling delete tools that target coupons or credentials. The phrase 'your stored designs' also clarifies the scope of the operation.

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

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

No guidance is given for when to use this tool versus alternatives such as roastify_list_designs, roastify_stash_design, or the other delete tools. The tool description does not mention prerequisites, exclusions, or the recommended workflow of listing designs first to obtain a design_id.

Agents often have multiple tools that could apply. Explicit usage 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 does so thoroughly. It reveals idempotency (already-absent fields report removed: false without rewriting the vault), the vault-keyed behavior for untemplated fields, and authentication requirements (nsec-signed kind-27235 or cached dpop_token). It also flags destructiveness explicitly, which is critical for a delete 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 longer than average but every sentence contributes unique operational or selection information. The core action is front-loaded in the first sentence, followed by usage context, edge-case behavior, and security constraints. There is no filler 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 destructive, restricted mutation with no annotations and an output schema present, the description is unusually complete. It covers what is deleted, what is preserved, idempotent behavior, authentication requirements, access restrictions, and how it differs from the closest sibling. The agent has everything needed to call the tool safely and 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 schema coverage is 100%, the description adds meaningful semantics beyond the property descriptions. It explains that 'field' may be templated or untemplated and that deletion is keyed on what is vaulted, not the current template. For 'dpop_token', it clarifies the accepted proof forms and that patron proofs are rejected, which is essential for correct invocation.

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

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

The description opens with a precise verb and resource, 'Remove a single operator secret field,' and immediately clarifies scope: it deletes one key from the operator's encrypted credential blob without touching others. It explicitly positions itself as the field-level counterpart to forget_credentials, which wipes the whole row, making it easily distinguishable from sibling tools.

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

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

The description gives concrete when-to-use guidance, such as retiring a leftover after an SDK cutover or removing a stored-but-untemplated orphan, and contrasts it with the alternative forget_credentials for wiping the whole row. It also states restrictions: it is RESTRICTED to the operator, patron proofs are rejected, and it is destructive like a write, which helps an agent decide whether to invoke 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 transparency burden and does well: it discloses that this is a destructive write to a sensitive credential vault, requires proof of npub ownership, is free, and does not affect other fields. It does not explicitly state irreversibility, but 'delete' plus the sensitive-vault warning 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 primary action appears in the first sentence, and each subsequent sentence adds a distinct fact (scope, cost, auth requirement). 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 credential operation with no annotations, the description covers purpose, scope, cost, ownership proof, and risk. An output schema exists, so return-value details are not needed; the only minor omission is explicit guidance about alternatives or irreversibility, both reasonably 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 schema already documents all three parameters thoroughly. The description's 'proof of npub ownership' maps to dpop_token but adds no parameter-level meaning beyond the schema's detailed event-format 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 description states a specific action and resource: 'Remove a single patron credential field' and clarifies scope with 'Deletes one field from stored credentials without affecting other fields.' This clearly distinguishes the tool from sibling operations like roastify_update_patron_credential or roastify_delete_operator_credential.

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

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

The description provides clear context for use: when the goal is to remove one credential field while preserving others. It does not explicitly name alternatives or exclusions, but the 'patron credential' wording and single-field scope give an agent enough context to select it over related credential 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?

There are no annotations, so the description carries the disclosure burden. It does reveal an important behavior ('images re-inlined') and implies a read-only fetch, but it does not mention authentication requirements, credit billing, or any side effects, which is relevant given the npub/credit-billing 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 a single, front-loaded sentence with no filler. It names the verb, the resource, and the key behavioral detail in a compact structure that is easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 the description does not need to explain return values, and the parameter schema covers most inputs. The main missing context is explicit usage guidance and side-effect disclosure, but for a straightforward fetch operation the description is otherwise adequate.

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

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

The schema already provides descriptions for design_id, ref, and npub, covering roughly 75% of parameters. The tool description does not add parameter-level meaning and does not clarify the undocumented dpop_token, but it also does not need to duplicate what the schema already conveys.

Input schemas describe structure but not intent. Descriptions should explain 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') with a clear resource ('one of your stored designs') and adds the meaningful qualifier 'in full, with its images re-inlined.' This distinguishes it from listing tools like roastify_list_designs and from partial-retrieval tools like roastify_get_design_text, so an agent can identify the correct operation 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?

No explicit alternatives or when-not-to-use conditions are given, but the wording implies this is the tool for retrieving a complete stored design rather than a list or text-only view. The guidance is mostly implicit and could be stronger by naming relevant siblings such as roastify_list_designs or roastify_list_design_versions.

Agents often have multiple tools that could apply. Explicit usage 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 this excellently by stating the operation is cosmetic, non-destructive at the operator level, re-redeemable by the patron, free, and requiring proof of npub. This is materially richer than the bare schema and gives the agent a clear model of side effects.

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

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

Three short sentences deliver the core action, the critical caveat, and the cost/auth condition. There is no wasted phrasing, and the most decision-relevant fact ('Cosmetic only') appears immediately after the action. Ideal front-loading for an agent deciding whether to call this 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 small mutation tool with an output schema, the description is nearly complete: it explains purpose, behavioral caveats, pricing, and an auth requirement. The remaining gap is lack of explicit routing relative to delete_coupon and no guidance on dpop_token, but these are minor given the tool's simplicity and available 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 0%, so the description must compensate. It does clarify the role of npub ('this patron') and coupon_id ('a coupon'), but it does not explain dpop_token at all and gives no format or derivation hints. The compensation is partial: core parameters are inferable, but the optional parameter remains opaque.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Remove a coupon from this patron's redemption list.' It clearly distinguishes this from a permanent deletion by stating 'Cosmetic only — the coupon itself still exists at the operator.' This makes the tool's unique role immediately understandable, especially against the sibling 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 context for when to use this tool: when you only want to remove a coupon from a patron's visible list without destroying it. It implies the alternative of a real delete by saying the coupon still exists and can be re-redeemed, but it does not explicitly name delete_coupon or state 'when not to use.'

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

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

With no annotations at all, the description carries the full burden and it does add valuable behavioral context: 'Always requires proof of npub ownership — a deletion is as destructive as a write.' This signals authentication requirements and destructive potential, which is not inferable from the schema alone. It stops short of detailing reversibility or return behavior, but it is a strong disclosure for a delete 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 only three sentences and front-loads the core action. Every sentence earns its place: action, parameter disambiguation, and the destructive/auth warning. It does not repeat the verbose dpop_token schema text.

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

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

For the credential-deletion operation itself, the description covers the action, the key parameters, and a warning. However, it does not situate the tool among the overlapping sibling delete_operator_credential/delete_patron_credential, leaving a material contextual gap for a destructive operation. The existence of an output schema mitigates the need to describe return values, but not the routing ambiguity.

Complex tools with many parameters or behaviors need more documentation. 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 meaning beyond the schema by clarifying that npub should be the operator's own for operator credentials and the patron's for patron credentials, and by emphasizing that dpop_token must prove ownership of that npub. This extra guidance justifies a 4.

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

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

The description opens with a specific action and object: 'Delete vaulted credentials for a specific service and npub.' It clearly states what the tool does. However, it does not distinguish itself from sibling tools like roastify_delete_operator_credential and roastify_delete_patron_credential, which appear to cover the same operation, so it misses the top score.

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

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

The description provides context about which npub to pass for operator vs patron credentials, but it never explains when to choose this tool over the sibling 'delete_*' tools. There is no explicit when/when-not or alternative guidance, so an agent cannot route correctly among the overlapping credential-deletion 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 present, the description carries the behavioral disclosure burden and does so well: it reveals asynchronous rendering, immediate job-id return, non-attachment to products, no storefront-sync surface, and the need to carry the artwork URL onward. It stops short of explicitly stating whether the saved design itself is mutated or that generation consumes credits, but the schema's npub field hints at billing and the overall transparency 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?

The description is organized into three short, purposeful paragraphs: core action, limitations, and async flow. Every sentence adds information, and the key constraints are front-loaded. It is slightly verbose in phrasing but not wasteful given the behavioral nuances it must convey.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 non-schema context: async job handling, status polling, non-product attachment, and the requirement of an existing saved design. An output schema exists, so return-value details are not needed here. The main omissions are whether the source design remains unchanged and the explicit billing/credit consequence, but these are partially inferable from schema fields and the 'free' status-tool contrast.

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

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

Schema description coverage is 80%, so the schema already documents product_id, fields, client_req_id, and npub. The description paraphrases the fields placeholder mechanism and saved-design requirement but adds little parameter-level meaning beyond the schema. The dpop_token parameter remains undocumented in both schema and description, so no extra semantic value is contributed there.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Generate packaging artwork from one of your saved Design Studio designs.' It further clarifies the mechanism (rewrites named text and image placeholders) and explicitly contrasts itself with from-scratch authoring and product attachment, making its purpose unmistakable among the many roastify 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 gives clear context: use this when you have a saved design you authored and want personalized packaging artwork. It also states when not to use it (cannot author from scratch, artwork is not attached to a product) and explicitly directs the agent to roastify_artwork_status for checking the job. However, it does not name an alternative tool for from-scratch authoring or product creation, leaving some routing 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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It reveals the read-like nature ('Get') and the returned fields, but omits that this operation uses an npub for credit billing and likely consumes credits; authentication and side-effect details are absent. This is a meaningful gap for a potentially paid operation.

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

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

A single tight sentence that front-loads the verb and object and then lists the key attributes. No fluff, no 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 simple single-record get, the description plus the output schema and parameter descriptions cover the basics. However, it lacks explicit guidance on prerequisite steps (browse_catalog) beyond a hint in the blend_id field, and it does not flag the credit-billing side effect. Given the large sibling set, a bit more context would be safer.

Complex tools with many parameters or behaviors need more documentation. 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 schema already documents blend_id and npub. The tool description adds little about parameters, and it does not explain the dpop_token field or any parameter syntax. This is adequate at the baseline level because the schema mostly handles 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 uses a specific verb ('Get') and resource ('one coffee blend'), and lists the returned attributes (roast level, decaf status, variants). It clearly indicates a detail lookup rather than a list operation, though it does not explicitly differentiate from siblings like roastify_get_catalog_product or browse_catalog.

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

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

There is no explicit statement of when to use this tool versus alternatives. The only guidance is implied via the blend_id parameter description, which says the id comes from browse_catalog, suggesting a prior browse step. No when-not or alternative tool is mentioned.

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

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

With no annotations provided, the description carries the full burden. It discloses what the tool returns (variants, sizes, prices, dieline) and 'Get' signals a read-only operation, which is adequate for a simple read tool. It does not add context on error behavior or billing implications beyond what the schema's npub note already states.

Agents need to know what a tool does to the 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 12-word sentence front-loads verb, resource, and scope, then enumerates the return contents. Every word earns its place, with no filler or repetition of the tool title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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-item read tool with an output schema present, the definition covers what is fetched, what it includes, and where the product_id comes from. The only gap is explicit differentiation from roastify_get_my_product and roastify_browse_catalog, which an agent must infer from the word 'catalog.'

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

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

Schema description coverage is 67%: npub and product_id have meaningful descriptions (billing purpose; source from browse_catalog), leaving only dpop_token undocumented. The description itself adds no parameter-level meaning, but the schema already handles most of the burden, so no compensation is 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 states a specific verb ('Get'), a single resource ('one catalog product'), and the included data ('variants, sizes, prices, and dieline'). The qualifiers 'one' and 'catalog' implicitly distinguish it from list/browse and 'my product' siblings, though it doesn't name them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 main description gives no when-to-use or alternative routing guidance. However, the product_id parameter description ('The catalog product id from browse_catalog') implies a prerequisite workflow — browse first, then fetch a specific product by ID — which is real but implicit usage guidance.

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

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

With no annotations, this description carries the full burden of behavioral disclosure, and it delivers: it explains that text layers may not print due to missing visibility flags, that stash labels state intent not content, and that width is a fixed wrap while height re-measures with text growth. It also defines z-order semantics and warns about the ±10% chars constraint. This is far beyond a generic 'get' description.

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

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

The description is front-loaded with the core purpose and is well-structured into paragraphs and bullet-like lists, but it is quite long and contains some redundancy (e.g., width/height semantics stated in two places, repeated references to roastify_move_elements). It is wordy but each section carries useful domain nuance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool with no annotations, this description is comprehensive: it explains the full return shape (text layers, sheet/panels/face, elements, fonts, description), geometry semantics, caveats about missing visibility flags, and how to pair with sibling tools for edits. An agent has everything needed to invoke and interpret 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?

The description provides no additional meaning for the three input parameters; it focuses entirely on the return payload. The schema already covers npub and design_id (67% coverage), but dpop_token remains undocumented in both schema and description. Since coverage is not high and the description adds zero param-level guidance, this dimension is 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?

The opening sentence states a specific verb ('List') and resource ('editable text layers of a stored design'), and immediately scopes what is returned ('NOT the design's images'). It is clearly distinct from siblings like roastify_update_design_text (saves changes) and roastify_move_elements (changes geometry/font).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 routing: use roastify_move_elements to change fontSize/wrap frame/align/fontFamily or z, roastify_update_design_text to save text changes, and roastify_set_product_description for store-page prose. It also tells the agent to read these layers before judging a design and warns about images being excluded, though it never names the sibling that returns images. This is clear context with minor exclusion gaps.

Agents often have multiple tools that could apply. Explicit usage 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 delivers substantive context: it reveals that blend identity is not a named field but is encoded in the variant SKU, and warns that 'a product's title can say one thing while its SKU is really a different blend' — a genuine data-model trap. It also discloses the return scope ('in full, with all its variants'). It does not cover error behavior or auth requirements, but for a read operation there is little hidden destructiveness to disclose.

Agents need to know what a tool does to the 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 purpose is front-loaded in a single sentence, and the second paragraph, while detailed, earns its length because the SKU example ('COF-WHB-12O-HGL-BOX' → 'HGL' → High Lakes) and the title/SKU mismatch warning are load-bearing for correct downstream use. There is no filler and no restatement of schema fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 one required parameter and an output schema present to cover return-value details, the description covers everything an agent must know to use the result correctly: purpose, full-return scope, and the critical SKU-decoding trap that could cause wrong origin/roast copy. The only shortfall is the opaque dpop_token parameter, which neither the schema nor the description explains.

Complex tools with many parameters or behaviors need more documentation. 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 of 3 applies: the schema already documents npub for credit billing and product_id as coming from list_my_products, and the description adds no parameter-level detail on top. The SKU guidance concerns the returned data rather than the inputs, and dpop_token remains unexplained in both the schema and the description, leaving a small uncompensated 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 first sentence states a specific verb and resource: 'Get one of your saved product designs in full, with all its variants.' The phrase 'your saved product designs' distinguishes it from siblings like roastify_get_catalog_product and roastify_get_blend, and 'one of' contrasts with roastify_list_my_products, so an agent can disambiguate 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 'saved product designs... in full, with all its variants' framing gives clear context for when this tool applies versus catalog/blend/list siblings, and the input schema reinforces that product_id comes from list_my_products. The SKU-decoding paragraph is a concrete post-call guideline ('Decode the SKU before writing origin/roast copy'). It stops short of explicitly naming alternatives or when-not-to-use conditions, so it misses a 5.

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

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

With no annotations, the description carries the full burden. It discloses that the operation is a read, that it returns the latest metadata fields with a specific list, and that an empty profile is returned when none is published. It also states the data is publicly available, implying no side effects. It doesn't mention rate limits or relay details, but is otherwise 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, front-loading the core purpose and then adding context and return details. Every clause contributes 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 one-parameter read-only tool with an output schema, the description covers the input semantics, behavioral guarantees, return values, and edge case (empty profile). It is complete enough for an agent to invoke correctly without additional information.

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

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

The schema provides no description for the npub parameter (0% coverage), and the description compensates by indicating the npub is the identifier whose profile is read. However, it does not explain npub format, validation, or the meaning of the default empty string, leaving some ambiguity for an agent unfamiliar with Nostr.

Input schemas describe structure but not intent. Descriptions should explain 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 the verb 'Read' and the specific resource 'an npub's public Nostr profile', and specifies NIP-01 kind-0 metadata, making the operation unambiguous. It inherently distinguishes itself from the sibling write tool publish_nostr_profile by being a read operation.

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

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

It states 'Free, no proof — the data is already public on relays,' which tells the agent when this tool is appropriate (any time a public profile is needed) and that no authentication is required. It does not explicitly name alternatives or exclusion conditions, but the context is clear.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the operation as generating a proof, which suggests a non-mutating computational action, but it does not explicitly state that it is read-only, what prerequisites are required, or what happens if the notarization ID or npub is invalid. It adds useful technical context about the proof being Merkle-based and Bitcoin-notarized, but leaves some behavioral gaps.

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

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

The description is a single, well-constructed sentence with no filler. It front-loads the key purpose and includes enough technical specificity to be useful without being verbose.

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

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

The tool is relatively simple with two fully documented parameters and an output schema, so the description does not need to explain return values. The description covers what the tool does and the domain context. It is mostly complete, though explicit usage guidance or read-only clarification would make it fully self-sufficient.

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

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

Schema description coverage is 100%, so the input schema already fully documents both parameters (npub and notarization_id). The description adds no additional parameter-level meaning, which is acceptable because the schema does the heavy lifting. 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 ('Generate') and names a precise resource ('Merkle inclusion proof') plus the context ('patron's balance included in a Bitcoin-notarized snapshot'). It clearly distinguishes this tool from generic get/list tools and tells the agent exactly what the 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 usage when a Merkle proof for a specific notarized snapshot is needed, but it does not explicitly say when to use this tool versus related tools like roastify_list_notarizations, roastify_notarize_ledger, or roastify_receive_npub_proof. No alternatives or exclusions are mentioned, so the guidance 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 provided, the description carries the full burden. 'Report' and 'Shows' clearly imply a read-only inspection with no mutating side effects, and 'Free' discloses that no cost is incurred. It could be even more explicit about not modifying operator configuration, but the wording strongly signals a non-destructive status read.

Agents need to know what a tool does to the 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 in the first sentence. The follow-up sentences add concrete output detail and sibling routing without wasted words. 'Free' is a small but useful extra behavioral note.

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

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

This is a simple zero-parameter status tool with an output schema available, so the description doesn't need to explain return values. It covers what the tool does, what it reports, and how it differs from the related patron-level tool. Nothing important is missing 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?

The input schema has zero parameters, so there is no parameter semantics burden on the description. The description still adds context by scoping the operation to 'this operator,' which helps the agent understand what the tool applies to despite having no explicit 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 names a specific verb ('Report') and resource ('this operator's configuration readiness'), then clarifies exactly what is shown: configured settings, missing settings, and how to deliver each missing value. It also differentiates itself from the patron-level sibling by naming get_patron_onboarding_status explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: it is for operator-level onboarding status, not patron-level credential status. It explicitly tells the agent to use get_patron_onboarding_status instead when patron credentials are the subject, which is strong 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, the description carries the full behavioral burden and does so well. It reveals that values are never exposed, that delivered_at may be null for vaulted secrets, that the field list itself is sensitive and requires proof of ownership, and that the operation is free. This gives the agent a strong model of access, privacy, and 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 well organized and front-loaded, leading with the core action and then adding return semantics, privacy guarantees, cost, and auth in a logical order. Every sentence earns its place with no redundant 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 is complete for a read-only list tool: it explains what is returned, when fields are null, that values are never exposed, the sensitivity and auth requirement, and the cost model. An output schema exists so return-structure details are covered elsewhere.

Complex tools with many parameters or behaviors need more documentation. 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 both npub and dpop_token thoroughly, including the exact framing requirements for dpop_token. The tool description adds the contextual point that proof of npub ownership is required, but it does not need to repeat parameter syntax. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and object: 'List stored patron credential field names (not values).' It immediately distinguishes this from value-returning or mutating credential tools by stating values are never exposed and framing the purpose as verification of configured fields and their ages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 use case: 'use this to verify which fields are configured and how old each one is.' It also notes the prerequisite of npub ownership proof. However, it does not explicitly mention sibling tools as alternatives or state when not to use this tool, so it stops short of full usage guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool is free, requires proof of npub ownership, and explains that this is because credential presence is sensitive information. The 'Report' framing implies a read operation, and the description clarifies that it indicates which secrets are configured rather than exposing secret values.

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

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

The description is compact and front-loaded with the core purpose. Each sentence adds distinct value: purpose, behavior by service type, cost, and the auth requirement. There is no redundancy or filler.

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

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

For a two-parameter tool with 100% schema description coverage and an output schema, the description is sufficiently complete. It covers purpose, service variations, cost, and authentication requirements. It does not detail error cases or output parsing, but the presence of an output schema partially offsets that need.

Complex tools with many parameters or behaviors need more documentation. 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 contextual meaning beyond the schema by explaining why both patron_npub and dpop_token are required ('Proof of npub ownership is required because credential presence is sensitive information'), linking the parameters to the purpose of the tool.

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

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

The description states a specific verb and resource: 'Report a patron's credential readiness for this operator.' It further clarifies the two service categories (set-once vs dynamic/OAuth2) and what the tool shows for each, making it clearly distinguishable from the sibling 'get_operator_onboarding_status'.

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

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

The description gives clear context on when the tool applies by explaining how it behaves for set-once services (eXcalibur, TheBrain) and dynamic services (Schwab). It does not explicitly name alternatives or provide exclusion conditions, but the usage scenario is unambiguous enough to guide selection among the large sibling list.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the call is free, that it can self-initialize a scaffold as a side effect, and that it does not derive economic data from code. This is meaningful behavioral context beyond a simple 'get' 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 sentences each add distinct value: the core purpose, the cost, and the edge-case initialization behavior. 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?

With no parameters and an output schema present, an agent has sufficient information to invoke the tool and interpret results. The description additionally covers cost, missing-model behavior, and a meaningful data-source constraint.

Complex tools with many parameters or behaviors need more documentation. 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 schema coverage is 100%, so the baseline of 4 applies. No parameter documentation is needed 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 clearly identifies the action ('Get'), the resource ('active pricing model'), and the scope ('for this operator'). It is immediately distinguishable from related siblings like roastify_set_pricing_model and roastify_reset_pricing_model.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the active pricing model, and the 'If no model exists' clause gives some conditional context. However, it does not explicitly name alternatives or state when to use this getter instead of related pricing 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 full behavioral burden and does so thoroughly. It explicitly states 'Free, no side effects,' explains the registered:false/unregistered output behavior, describes the live wire-surface diff, and clarifies that tool_id remains stable across renames. This is unusually 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 front-loaded with the core purpose and well-paragraphed, but it repeats the deploy-drift/unregistered-reporting rationale in two places (#174 and #175) and spends a full paragraph on rename philosophy. It could be tightened without losing essential information.

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

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

For a zero-parameter tool with an output schema, the description is highly complete: it explains why the identity mapping matters, what the unregistered array means, how drift is surfaced, and that there are no side effects. Nothing an agent needs to call or interpret this tool 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 tool has zero parameters and an empty input schema, so there is no parameter-level semantic gap. The baseline of 4 applies because the description correctly focuses on output and behavior instead of pretending parameters need 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 description opens with a specific verb and resource: 'Return canonical (tool_id, mcp_name, …) for every tool the wheel exposes.' It also clearly positions itself as the authoritative identity source, distinguishing it from all other list_* siblings by focusing on canonical UUID mapping rather than domain objects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 for when to use the tool: any client that needs to know how the MCP identifies its tools, and specifically Reconcile for UUID-joining against the pricing model. It does not name explicit alternatives or exclusions, but no sibling tool addresses canonical identity mapping, so the guidance is sufficient.

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

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

With no annotations provided, the description carries the burden. It discloses the operation (list), the return payload structure, and the cost behavior ('Free — no credits required'). It does not explicitly assert read-only or side-effect-free status, but 'List' strongly implies it, and the free note adds useful 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?

Two tight sentences: the first fronts the action and resource, the second gives return details and cost. Every sentence earns its place, with 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 zero-parameter listing tool with an output schema, the description covers what is returned and the free cost behavior, and orients it within the pricing pipeline domain. It does not mention pagination or when exactly to call it, but those are minor given the tool's simplicity.

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

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

The tool has zero parameters, so schema coverage is trivially 100%, and the baseline for 0 params is 4. The description adds no parameter-specific semantics (none are needed), but it does clarify that the output includes 'parameter schemas' for each constraint type, which is relevant context.

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

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

The description states a specific verb ('List') and resource ('constraint types'), and explicitly enumerates the return fields (type, category, description, parameter specs). It is clearly distinct from sibling list tools, which target other resources like coupons or 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 implies use when working with pricing pipelines and highlights that it is free, but it does not explicitly state when to prefer this tool over alternatives or provide exclusions. Usage context is present but mostly implied by the purpose.

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

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

With no annotations, the description carries the burden and does well: it discloses ordering ('newest first'), the row-level times_redeemed counter, how the Studio consumes it against total_uses, and the access restriction. It does not describe pagination or the exact proof mechanism, but the core behavior is 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 short, purposeful sentences: purpose, data semantics, and restriction. No filler, and the most important scope information is front-loaded in the first sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, return values are covered, and the description adds ordering and row semantics. The main gaps are the unaddressed dpop_token/proof mapping and the lack of a clear distinction from the sibling list_my_coupons, leaving the tool slightly incomplete for autonomous 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 has one parameter (dpop_token) with 0% description coverage, and the description never mentions dpop_token or explains how to provide the required proof. 'Requires proof' hints at authentication but does not map that to the parameter, so an agent must guess how to 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 opens with a specific verb and resource: 'List every coupon this operator has minted (newest first).' This clearly states the operation and scope, and the 'minted' qualifier helps distinguish it from adjacent coupon tools. It does not explicitly contrast it with roastify_list_my_coupons, so it falls just short of full 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?

'RESTRICTED to operator — requires proof' is an explicit precondition and exclusion: non-operators should not call it, and proof must be supplied. This gives clear context for when it is appropriate. However, it does not name an alternative tool or state when to prefer list_my_coupons, so it is not a full 5.

Agents often have multiple tools that could apply. Explicit usage 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. It usefully discloses that the response is metadata-only and sorted newest-first, but it omits details about authentication, potential credit billing implications, or pagination. For a list action this is acceptable, though incomplete.

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

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

A single, front-loaded sentence that communicates the action, object, response scope, and ordering. Every word earns its place 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?

The core action is clear and the output schema covers return shape, but the description leaves dpop_token unexplained, gives no routing guidance against fetch_design/list_design_versions, and does not address the schema inconsistency where npub is described as Required while the schema marks it optional.

Complex tools with many parameters or behaviors need more documentation. 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 explanation for npub or dpop_token. Schema covers npub with a purpose note, but dpop_token is completely undocumented and the description does not clarify it. The word 'your' only weakly associates the listing with the npub parameter.

Input schemas describe structure but not intent. Descriptions should explain 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 action ('List') and resource ('your stored designs'), with additional scope 'metadata only' and ordering 'newest first'. This distinguishes it from fetch-style and version-list 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?

'Metadata only' implies that full design content is handled elsewhere, but the description does not explicitly name alternatives like fetch_design or list_design_versions, nor state when to prefer this tool. Usage context is present but left 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 the behavioral burden. It discloses that only committed versions are returned, ordering is newest-first, and each version exposes sha, short_sha, date, message, tag, and commit_url. It does not address failure modes or auth effects, but for a read-style listing tool this is a modest gap.

Agents need to know what a tool does to the 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 verb and result, then uses a compact second sentence to enumerate version fields and the downstream fetch_design relationship. Every sentence earns its place, and the formatting of code identifiers improves scanability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 ties the full workflow together: design_id from roastify_list_designs, version listing here, and sha/tag refs into roastify_fetch_design. An output schema exists, so return values are otherwise covered. It omits pagination and failure behavior, but for a simple list-versions tool the essential context 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 little direct meaning about this tool's own parameters: npub, design_id, and dpop_token are not named. The schema already documents design_id and npub, covering 67%, and the description's useful sha/tag-to-ref guidance is cross-tool rather than input-semantic. It is adequate but not compensatory for the undocumented 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 specific action and resource: 'List a stored design's committed versions, newest first — the git history.' This clearly distinguishes it from list_designs and fetch_design, and the explicit sha/tag-to-ref handoff to roastify_fetch_design reinforces its role in the workflow.

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

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

The description gives practical workflow context: design_id comes from roastify_list_designs, and a returned sha/tag is used as the ref for roastify_fetch_design. This implies when to use the tool, though it stops short of explicitly stating exclusions such as 'use fetch_design when you already have the ref.'

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

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

Even without annotations, the description discloses important behavior: it returns both active and exhausted redemptions, explains the per-row status values, notes that it is free, and states that proof of npub is required. It does not describe every detail such as dpop_token usage, but it is refreshingly transparent for a no-annotation tool.

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

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

The description is compact and front-loaded with the core action, followed by useful behavioral details and status values. Every sentence earns its place, and there is no redundant filler.

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

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

With an output schema present and low parameter complexity, the description covers the main purpose, statuses, and cost/auth requirement. The main missing piece is dpop_token semantics and a clearer statement of when to choose this over the sibling list_coupons tool, so it is adequate but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It adds some meaning to npub by associating it with patron proof, but it never explains the dpop_token parameter at all, including its relationship to proof of npub or why it has a default empty string. This is a significant gap for a two-parameter tool.

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

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

States a specific verb and resource: listing the coupons a patron has redeemed on an operator. The scope is explicitly narrowed with 'this patron' and 'this operator,' and the return statuses are enumerated, making it distinguishable from siblings like roastify_list_coupons.

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

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

Provides clear context for when the tool is appropriate: to list a patron's redeemed coupons on the current operator. It does not explicitly name alternatives or exclusion conditions, but the 'my coupons' scope is clear enough to guide 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 burden of explaining behavior. It does this well by disclosing that the tool returns one page at a time and that has_next_page and end_cursor are used to distinguish a page from a complete list. This is genuinely useful 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?

Two sentences, front-loaded with the core purpose, followed by a concise pagination warning. Every sentence adds value and there is 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 simple paginated list operation with an output schema present, the description covers the essential invocation context. It lacks an explicit pointer to sibling tools, but the resource scope and pagination behavior are clear enough for an agent to call 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 high (75%), so the description does not need to redefine each parameter. It does reinforce the cursor pagination semantics by mentioning end_cursor, which aligns with the cursor parameter. However, it does not address the schema oddity where npub is described as required but has a default and is not in a required list.

Input schemas describe structure but not intent. Descriptions should explain 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 and resource: listing the user's own saved Roastify product designs, with pagination. It clearly signals "your own" to separate it from catalog browsing, though it does not explicitly name or distinguish itself from sibling tools 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 implies when to use it—when you need your own saved product designs—and provides pagination context. However, it does not explicitly state when not to use it or point to an alternative such as browse_catalog or get_my_product.

Agents often have multiple tools that could apply. Explicit usage 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 'list recent,' leaving undefined how 'recent' is determined, whether pagination exists, or whether any implicit filters apply beyond the optional status parameter.

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

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

The description is a single concise sentence with no filler or repetition. It is easy to scan, though it is terse enough that it could have added a bit more contextual value without harming clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 optional-parameter list with an output schema, the description plus schema is minimally sufficient to invoke the tool. However, the lack of usage guidance and the ambiguous 'recent' semantics leave gaps that make it less than 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 describes both parameters (limit and status) with their defaults and meanings, so the description does not need to add parameter detail. The description adds no semantics beyond the schema, but none is required here.

Input schemas describe structure but not intent. Descriptions should explain 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 identifies the action ('list') and the resource ('recent Bitcoin notarization records'). It implicitly differentiates from siblings like get_notarization_proof and notarize_ledger, though it does not explicitly call out the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 on when this tool should be used versus alternatives. It does not mention that this is for browsing recent records while get_notarization_proof is for a specific record, or that notarize_ledger creates notarizations.

Agents often have multiple tools that could apply. Explicit usage 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 a create/mutation action but omits prerequisites (operator credential implied by the undocumented dpop_token parameter), operator-scoped uniqueness behavior on 'name', and conflict/error behavior on duplicates — all material for a write operation.

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

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

A single seven-word sentence with zero filler, front-loaded with the verb and resource. Every word earns its place; 'operator-owned' carries real scoping weight rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 a silently undocumented dpop_token parameter, a one-sentence description is insufficient. The output schema covers return values, but the description omits the operator-authorization requirement and the implications of operator-scoped uniqueness, leaving an agent to guess at failure modes.

Complex tools with many parameters or behaviors need more documentation. 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% (six of seven parameters documented), so the baseline is 3 even though the description adds no parameter-level detail. The 'operator-owned' phrase loosely contextualizes operator scoping and the dpop_token parameter but does not document parameters itself.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Create') and a specific resource ('new operator-owned discount coupon'), and the 'operator-owned' qualifier distinguishes it from generic coupon operations. Sibling tools like update_coupon, delete_coupon, and redeem_coupon make its mint-vs-modify role unambiguous 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?

No explicit when-to-use/when-not-to-use guidance or named alternatives are present. The word 'new' and the create verb contrast implicitly with update_coupon, delete_coupon, and redeem_coupon siblings, so usage is implied rather than stated.

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

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

No annotations are present, so the description carries the behavioral burden. It does well by disclosing that edits commit back to the same design_id, that git tracks the diff, that coordinates are not validated against panel bounds, and that the heavy background image is only moved if explicitly named. It could add more about error conditions or irreversibility, but versioning implies some safety net.

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

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

The description is front-loaded with a clear one-sentence purpose, followed by a motivating use case and caveats. It is somewhat wordy and includes an opaque phrase ('Apply it onto the product with the browser courier'), but the structure is logical and most content 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 complex edit tool with no annotations and an output schema, the description covers the key contextual gaps: when to use it, what it does to versioning, what it does not validate, and the special behavior around the background image. Combined with the highly detailed input schema, an agent has enough to select and 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 86%, so the schema already documents parameters thoroughly. The description does add useful operating context ('the caller owns the coordinates', 'the heavy background image is never moved unless you name its id'), but it does not need to—and does not—expand on the individual parameter formats beyond what the schema provides. This is a solid baseline-3 case.

Input schemas describe structure but not intent. Descriptions should explain 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 precise operation: 'Move a group of elements together and/or resize elements; commit a new version.' It goes on to explain the exact problem it solves — moving a multi-layer block as one rigid object — and clearly distinguishes itself from add_design_element by noting it does not validate against panel bounds.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 scenario ('the Designer can move only one layer at a time... drifts out of alignment') and names an explicit alternative: 'Nothing is validated against panel bounds here (unlike add_design_element)'. It also warns about the background image not being moved unless named, helping the agent decide when and how to call the tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the task is asynchronous, operator-scoped, free, and that Bitcoin confirmation takes 1-6 hours. It does not detail side effects beyond submitting the root, but this is meaningful disclosure for a parameterless background task.

Agents need to know what a tool does to the 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 deliver the core action, the operational constraints, and the cost model with no filler. The description is front-loaded and 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 no-input background task with an output schema available, the description covers the essential context: what it does, who can run it, how long it takes, and whether it costs credits. Nothing critical 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 tool has zero parameters, and the schema already defines an empty object. The description does not need to add parameter-specific semantics, and the baseline for a no-parameter tool is 4.

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

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

The description names a specific operation ('Build a Merkle tree of all patron balances and submit the root to Bitcoin via OpenTimestamps') and a clear resource ('all patron balances'). This clearly distinguishes it from read-only siblings like get_notarization_proof and list_notarizations.

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

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

The description gives clear context: it is an operator-only background task, costs no credits, and has a 1-6 hour confirmation window. It does not explicitly name alternative tools for checking the resulting proof status, but the inclusion of access and timing guidance makes usage conditions 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 burden is on the description. It adds 'Free,' which is a useful behavioral signal about cost, and 'Describe' implies a read-only, non-mutating operation. However, it does not explicitly mention side effects, authentication needs, or whether an external call is made—though for a zero-parameter informational tool this gap is modest.

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

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

The description is extremely concise: two short sentences with no filler. The core action is front-loaded, and 'Free.' adds a distinct useful signal without bloating the text.

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

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

With zero parameters and an output schema present, the description does not need to explain return values. It communicates purpose and cost clearly. The only real gap is the lack of guidance on how it relates to sibling oracle tools, but for such a simple informational tool this is a minor omission.

Complex tools with many parameters or behaviors need more documentation. 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 accepts zero parameters and the input schema has no properties, so the description cannot add parameter-level meaning. Per the baseline for tools with no parameters, this 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 action ('Describe') and a specific resource ('DPYC ecosystem'), and 'via the Oracle' connects it to the oracle tool family. It is distinguishable from sibling oracle tools like roastify_oracle_get_tax_rate and roastify_oracle_lookup_member, though it does not explicitly name those alternatives.

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

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

Usage is implied: use this tool when you want a general description or overview of the DPYC ecosystem. However, there is no explicit when-to-use guidance, no contrast with the other oracle tools, and no stated exclusions, so the agent has to infer the intended placement from the name and phrasing.

Agents often have multiple tools that could apply. Explicit usage 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 adds useful behavioral context with 'current' and 'Free,' implying freshness and no monetary cost, but it does not mention side effects, authentication needs, rate limits, or caching behavior. Still, the read-only nature is reasonably clear from 'Get.'

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

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

The description is two short sentences with no filler. The core purpose is front-loaded, and the extra 'Free.' note earns its place by adding behavioral context.

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

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

For a zero-parameter read-only tool with an output schema present, this description is sufficiently complete. The agent knows what the tool returns, that it is current, and that it is free. No return-value documentation is needed because an output schema exists.

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

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

The tool has zero parameters and schema coverage is effectively 100%, so there is nothing for the description to add about arguments. It does clarify the meaning of the returned data by specifying it is the current DPYC certification tax rate, which is helpful.

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

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

The description states a specific verb and resource: 'Get the current DPYC certification tax rate.' It clearly identifies what the tool returns and distinguishes it from other oracle_* siblings like about, lookup_member, and network_advisory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 on when to use this tool versus alternatives, no prerequisites, and no exclusions. The word 'Free' adds cost context but does not explain the calling scenario or when a different oracle tool would be more appropriate.

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

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

With no annotations provided, the description carries the full burden. The phrase 'Get... from the Oracle' indicates a read-only retrieval, and 'Free' transparently discloses that no payment or credits are required. While it does not detail output format or potential edge cases, the operation is simple and the description communicates the key behavioral traits for a no-parameter info lookup.

Agents need to know what a tool does to the 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 totaling eight words: 'Get DPYC onboarding instructions from the Oracle. Free.' The primary action is front-loaded, and the second sentence adds a useful cost detail without redundancy. 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 zero-parameter tool with an output schema, the description is complete for invocation. It tells the agent exactly what will be returned (DPYC onboarding instructions) and the cost (free). The presence of an output schema means return-value details do not need to be in 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?

The input schema has zero parameters, so there is no parameter semantic burden on the description. According to the rubric, a zero-parameter tool receives a baseline score of 4. The description does not need to add parameter meaning because none exist.

Input schemas describe structure but not intent. Descriptions should explain 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 action and resource: 'Get DPYC onboarding instructions from the Oracle.' The verb 'Get' and the noun 'onboarding instructions' make the tool's purpose unambiguous. It does not explicitly distinguish itself from sibling tools like roastify_oracle_about or roastify_get_operator_onboarding_status, but the resource is specific enough that an agent can infer its function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 roastify_oracle_about or roastify_get_patron_onboarding_status. There is no mention of alternative tools, conditions for selection, or exclusions. The usage context is only implied by the title and sibling list, not stated.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Look up' communicates a read-only, non-mutating operation, and 'Free' explicitly discloses a cost-related behavior. It does not detail error handling or authentication needs, but for a single-parameter lookup this is reasonably transparent.

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

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

The description is extremely concise: 'Look up a DPYC community member by npub. Free.' The action and resource are front-loaded, and the additional sentence adds useful cost information without unnecessary detail.

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

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

For a tool with one required parameter and an output schema, the description is enough to invoke it, especially since return values are presumably covered by the output schema. However, it omits context about what DPYC is, when this tool is preferable to related sibling tools, and how missing members are handled.

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

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

The description names npub as the lookup key, which adds meaning to the single required parameter beyond the bare schema property name. However, it does not explain the npub format, where to obtain it, or any validation constraints, leaving the parameter semantics only minimally compensated.

Input schemas describe structure but not intent. Descriptions should explain 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: look up a DPYC community member by npub, using the specific verb 'Look up' and a concrete resource. It does not explicitly distinguish itself from sibling tools like get_nostr_profile, but the member-by-npub scope is specific enough to be understood.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 related lookup tools, nor does it mention prerequisites such as having a valid npub or what to do if the member is not found. 'Free' hints at a cost consideration, but no alternatives or exclusions are provided.

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

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

No annotations are provided, so the description carries the burden. 'Get' implies a read-only operation, and 'Free' adds a cost-related behavioral detail. However, it does not state whether the advisories are live/cached or describe any other operational behavior beyond the basic get.

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

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

The description is very brief and front-loaded with the operation. 'Free.' is a separate short clause that adds useful context without unnecessary verbosity.

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

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

For a parameterless read-only tool with an output schema, the description is mostly complete. It clearly identifies what is returned; the only notable gap is the absence of alternative-tool routing guidance.

Complex tools with many parameters or behaviors need more documentation. 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 schema coverage is complete, so there is nothing for the description to add about parameters. Baseline 4 is appropriate for a parameterless tool.

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

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

The description states a clear action and object: 'Get active network advisories from the Oracle.' This is specific and distinct from sibling Oracle-related tools, though it does not explicitly differentiate itself from them by 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?

There is no guidance on when to use this tool versus alternatives. Sibling tools like roastify_oracle_about or roastify_oracle_get_tax_rate exist, but the description provides no selection criteria 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 of behavioral disclosure. It meaningfully explains that the wheel never holds the patron nsec, verifies the signature against the npub, relays to public relays, and treats the signature as the sole authorization. It does not cover failure modes or retry behavior, but it gives substantial safety-relevant context.

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

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

The description is front-loaded with the essential purpose in the first sentence. The second paragraph adds valuable security and authorization context, though phrases like 'Free' and the slightly conversational tone could be trimmed without losing meaning.

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

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

For a two-parameter tool with an output schema, the description provides the key context an agent needs: what is published, who signs it, how authorization works, and that no key custody is involved. It does not explicitly state that both parameters are effectively required, but the described flow implies that, and the output schema covers return expectations.

Complex tools with many parameters or behaviors need more documentation. 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 describes npub and signed_event accurately. The tool description reinforces the 'client-signed' and 'JSON' nature of signed_event but adds little semantic detail beyond what the schema provides, so a baseline score 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: 'Publish a CLIENT-SIGNED kind-0 profile to relays for an npub.' This clearly distinguishes it from read-oriented siblings like roastify_get_nostr_profile and other publishing/credential tools. The wording leaves no doubt about the tool's core function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 by explaining that the frontend signs the kind-0 event and passes it here, and the wheel verifies and relays it. It does not explicitly name alternative tools or state when not to use this one, but the client-signed flow makes the intended invocation scenario 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 full behavioral burden. It discloses that this call only creates an invoice, that external payment is required, that confirmation happens via check_payment, and that proof of ownership is needed. It stops short of mentioning invoice expiry or ledger-side effects, but the essential behavioral traits are visible.

Agents need to know what a tool does to the 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, and every sentence earns its place: what the tool does, how the payment flow works, the ownership prerequisite, and the free-call caveat. It is easy to scan and contains 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 output schema and full parameter documentation, the description provides enough contextual guidance for correct invocation: it covers the purchase flow, the required proof of ownership, and the needed follow-up call. Minor details such as invoice expiry or amount limits are absent, but they are not essential for 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?

Schema coverage is 100%, and the schema already documents npub, dpop_token, and amount_sats thoroughly. The description adds useful context about why ownership proof matters, but it does not meaningfully expand parameter meaning beyond the structured schema, 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 opens with a specific verb and resource: 'Buy credits via Bitcoin Lightning.' It clearly explains the invoice workflow and names the follow-up tool check_payment, so an agent can distinguish this from the many sibling tools such as check_balance or restore_credits.

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

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

The description gives a clear usage flow: create the invoice, pay it with a Lightning wallet, then call check_payment to confirm. It also states a key prerequisite — proof of npub ownership — and that the call itself is free. It does not explicitly enumerate when not to use the tool or compare it to alternatives, but the workflow guidance is strong.

Agents often have multiple tools that could apply. Explicit usage 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 delivers: deterministic one-shot retrieval, draining only the pinned rendezvous relay, deletion/NACK of wrong DMs, stopping at the first matching DM, courier_not_found on no match, and payment processor client reinitialization on success. No annotation contradiction exists.

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

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

Although longer than average, each sentence earns its place: action, flow context, call precondition, drain semantics, alternative path, and side effect. It is well-structured and front-loaded with the core purpose before diving into protocol details.

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

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

Given the complexity of a deterministic one-shot credential retrieval and the absence of annotations, the description is complete. It covers call timing, relay draining behavior, failure semantics, the credential_card bypass, and the post-success reinitialization. Since an output schema exists, not detailing return shape is acceptable.

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

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

Schema coverage is 100% and each parameter already has a description, so the baseline is 3. The tool description adds relational meaning beyond the schema: service must match request_credential_channel, dpop_token is the session phrase for this exact channel, sender_npub identifies the credential sender, and credential_card bypasses relay access entirely.

Input schemas describe structure but not intent. Descriptions should explain 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 names the CREDENTIAL-DELIVERY flow and explicitly distinguishes its counterpart receive_npub_proof, making the tool's role clear relative to siblings such as receive_patron_credentials and 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 an explicit precondition: 'Call this only after the user confirms they have replied.' It also tells the agent what not to do: 'Do NOT poll, loop, or retry.' The credential_card alternative path is explained with the condition under which dpop_token is not needed.

Agents often have multiple tools that could apply. Explicit usage 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 exceeds it: it discloses destructive side effects (mismatched DMs deleted and NACK'd), one-shot retrieval semantics, the relay-draining behavior, the security model (signed DM proves ownership, raw token never stored), and post-success obligations. This is exemplary 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?

Front-loaded and information-dense: the first sentence states the core purpose, and the critical timing warning appears immediately after. Each sentence earns its place given the protocol complexity, though 'the same token' is a minor redundancy that prevents a 5.

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

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

For a high-complexity async protocol tool, the description covers preconditions, retrieval mechanics, side effects, success return, and post-success usage obligations. An output schema exists, so return-structure details are properly delegated, and nothing critical 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that dpop_token must be the exact value from request_npub_proof and that the calling application must remember it for subsequent paid calls, and by defining the lookup as the (patron_npub, dpop_token) pair. This exceeds the baseline without being redundant.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Receive npub ownership confirmation from a patron') and explicitly distinguishes itself from the credential-delivery counterpart receive_credentials. The flow context makes it unmistakably a one-shot proof retrieval, not a general receive tool.

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

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

Gives an explicit precondition ('Call this only after the user confirms they have replied'), explains the failure mode if called too early, names the sibling alternative (receive_credentials), and explicitly forbids polling, looping, or retrying. This is complete when-to-use guidance.

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

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

With no annotations, the description carries the full behavioral burden and largely succeeds: it discloses deterministic one-shot retrieval, that the tool drains only the pinned rendezvous relay, stops at the matching DM, and should not be polled or retried. Some jargon ('pinned rendezvous relay', 'Secure Courier') is unexplained, so it is informative but not fully transparent.

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

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

The description is compact, front-loaded with the core action, and each sentence serves a purpose. The awkward phrase 'name the response with' and the heavy relay-specific jargon cost some clarity, but there is minimal wasted text.

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

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

The output schema covers return values, and the description explains the one-shot mechanics and no-retry rule. However, it assumes background knowledge about the Secure Courier, pinned rendezvous relay, how the channel is established, and what to do if no matching DM exists; a prior request_patron_credentials step is implied but never stated.

Complex tools with many parameters or behaviors need more documentation. 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 is the only source of parameter meaning. It explains that sender_npub and dpop_token identify the retrieval and that credential_card is an alternate ncred1... path not requiring dpop_token. It does not detail all formats or constraints, but it compensates well for the empty schema.

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

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

The description states a clear action ('Pick up patron credentials from the Secure Courier') and distinguishes two retrieval modes: sender_npub/dpop_token or credential_card. It adds behavioral specifics like 'deterministic, one-shot retrieval' that separate it from generic receive tools, though it does not explicitly name sibling tools.

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

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

The description gives operational guardrails such as 'Do NOT poll or retry' and explains the credential_card alternative, which helps an agent know how to invoke it. However, it never states when to choose this tool over sibling tools like roastify_receive_credentials or roastify_request_patron_credentials, leaving some selection 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 provided, the description fully carries the behavioral disclosure burden. It reveals validation of the validity window and total cap, recording of a per-patron redemption row, automatic discount application until uses_per_patron is exhausted, the free cost model, the npub proof requirement, and idempotency. This is comprehensive and exceeds minimal 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 dense and well-structured: it opens with the core action, then layers side effects, cost, prerequisites, and idempotency in a natural order. Every sentence contributes meaningful 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 redemption tool with three parameters and an output schema, the description is remarkably complete. It covers purpose, preconditions, side effects, cost, and repeat-call behavior. The missing dpop_token detail falls under parameter semantics, and explicit alternative routing is not essential given the clarity of the purpose.

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

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

Schema description coverage is 0%, so the description must compensate. It usefully defines 'code' as the shared coupon name and explains the proof requirement for npub. However, the optional dpop_token parameter is never mentioned, leaving one of three parameters semantically undocumented.

Input schemas describe structure but not intent. Descriptions should explain 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 'Claim a coupon by its name (the code the operator shared)' clearly states the action, object, and input terminology. It distinguishes redemption from coupon lifecycle tools like mint, update, delete, and list coupons, leaving no ambiguity about the tool's purpose.

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

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

The description provides clear operational context: the tool is free, requires proof of npub, is idempotent, and produces side effects on future paid calls. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to select it appropriately.

Agents often have multiple tools that could apply. Explicit usage 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 safety/behavioral burden and does it thoroughly: it discloses cost, public visibility, attribution to the caller's npub, lack of verification, normal maintainer triage, and the not-configured failure mode. It also states return value shape, which is valuable for an agent deciding whether to call 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 front-loaded and well organized, with a one-line definition followed by purpose, consequences, and return behavior. A few phrases are slightly redundant ('Report it where the tool lives' restates the first sentence), but the length is justified by the fee/privacy/failure conditions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 5-parameter tool with a high-complexity auth token, the description plus schema covers purpose, prerequisites, side effects, costs, attribution, output, and failure behavior. The output schema is noted as present, and the description augments it with the concrete return fields (repo, number, url) and the not-charged condition.

Complex tools with many parameters or behaviors need more documentation. 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 applies. The description adds motivational context (why npub is required, why a fee exists) but does not add new syntactic or format details beyond the schema's already-detailed parameter documentation.

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

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

The opening sentence names a specific action (file a field report), a resource (GitHub issue on the operator's repo), and a subject (this service). The follow-up question 'Found a tool's metadata or response wrong or confusing?' pins the exact use case and clearly separates it from the many service-operation 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 clearly signals when to use this tool: when a tool's metadata or response appears wrong or confusing. It does not explicitly enumerate when-not-to-use cases or name an alternative, but given this tool is unique among the siblings, the context is sufficient.

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