Server Quality Checklist

Tool Scores

• invalidate_payment_link_if_pendingA
  4.6/5.0
  Behavior5/5

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

  Even though annotations already flag this as destructive, the description adds crucial behavioral nuances: success does not imply cancellation (the tool no-ops on non-pending links), cancellation is irreversible, and it never moves money. It also advises confirming with `get_payment_link`, which is high-value context beyond the annotations.

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

  Conciseness4/5

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

  The description is somewhat verbose (four paragraphs) but every sentence carries meaningful information: purpose, use cases, a critical caveat about success responses, and irreversible consequences. It is front-loaded with the main purpose and structured logically. Slightly dense but earns its length.

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

  Completeness5/5

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

  The description covers purpose, conditional behavior, alternatives, side effects, and verification steps. With an output schema present, it doesn't need to detail return values. This is a complete and self-contained guide for a destructive, conditional operation.

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

  Parameters3/5

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

  The schema has 100% coverage for the single parameter `reference_id` with a clear description. The tool description doesn't add much parameter-specific detail beyond what the schema already says, but it does reference 'fresh reference ID' when mentioning issuing new links, which is indirect. Baseline 3 is appropriate given full schema coverage.

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

  Purpose5/5

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

  The description opens with a precise, conditional statement: 'Cancel a payment link only if it is still pending; otherwise do nothing.' This clearly identifies the verb (cancel/invalidate), resource (payment link), and the unique condition (pending). It also distinguishes itself from the sibling tool `invalidate_payment_link` by calling itself the 'safe version' that checks status first.

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

  Usage Guidelines5/5

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

  The description gives explicit use cases: retiring abandoned checkouts or withdrawing incorrectly priced links. It also contrasts with `invalidate_payment_link` (the non-conditional version) and directs users to `create_refund` for returning money, making when-to-use and alternatives very clear.

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

• check_order_paidA
  4.7/5.0
  Behavior5/5

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

  Beyond the read-only and idempotent annotations, the description explains the exact semantics of `paid` (only Complete or Delivered statuses), the crucial distinction between `paid` and `safeToFulfil`, the test-mode behavior where `safeToFulfil` stays false, and the string type of `total`. This adds substantive context not available from annotations alone.

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

  Conciseness5/5

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

  While the description is long, every sentence earns its place by explaining status mappings, the safeToFulfil distinction, usage guidance, and return field types. It is well-structured, front-loaded with the core answer, and contains no redundant fluff.

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

  Completeness5/5

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

  The description fully accounts for the tool's complexity by explaining the return fields (`paid`, `safeToFulfil`, `total`), the test-mode edge case, and the correct usage context. Even with an output schema present, it adds necessary business logic not inferable from the schema alone.

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

  Parameters3/5

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

  The schema description for `reference_id` already provides 100% coverage, explaining it is the user's own order ID and not Wayl's internal link ID or checkout code. The description adds no new parameter syntax or format, so it does not significantly enhance the schema's semantics.

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

  Purpose5/5

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

  The description clearly states the tool 'Answer whether an order is paid and safe to fulfil, from your reference ID,' which is specific and distinguishes it from related tools like `parse_webhook` and `get_payment_link` by referencing alternatives.

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

  Usage Guidelines5/5

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

  It explicitly instructs when to use the tool ('Check this before sending a download link or shipping a copy') and provides alternative tools for other scenarios ('When a webhook delivery arrives use `parse_webhook` instead; for the full link record use `get_payment_link`; to reconcile many orders use `get_payment_links_batch`').

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

• create_refundA
  4.7/5.0
  Behavior5/5

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

  Beyond the annotation `destructiveHint: true`, the description discloses critical behavioral traits: the refund is irreversible once 'Refunded', there is no idempotency key so duplicate calls create duplicate refunds, and the returned `id` must be saved for `get_refund`/`cancel_refund`. It also notes the POST is never retried. This is rich, non-obvious context that annotations alone do not provide.

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

  Conciseness5/5

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

  The description is compact yet information-dense. Every sentence serves a purpose: what it does, prerequisites, approval flow, cancellation option, irreversibility warning, idempotency caveat, and ID recovery advice. The structure is logical, moving from action to lifecycle to cautions, with no redundant words.

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

  Completeness5/5

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

  Given the tool's destructive nature and the existence of an output schema, the description covers all essential context: prerequisite conditions, workflow states, error-prone amount ceiling, no-undo warning, duplicate-risk, retry policy, and how to recover the ID. It fully equips an agent to invoke the tool correctly and handle follow-ups.

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

  Parameters3/5

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

  The input schema already provides 100% coverage with clear descriptions for `reference_id`, `reason`, and `amount`. The description reinforces the amount constraint ('may not exceed what the buyer actually paid') and the reason length requirement, but adds no new per-parameter semantics beyond what the schema states. This meets the baseline for fully documented schemas.

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

  Purpose5/5

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

  The description opens with a specific verb+resource: 'Request a refund against a paid order.' It clarifies the real-world effect ('sends real money back') and distinguishes from sibling tools like `list_refunds`, `get_refund`, and `cancel_refund` by focusing on the creation action. No ambiguity about what the tool does.

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

  Usage Guidelines5/5

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

  The description gives explicit when-to-use and when-not-to-use guidance. It instructs calling `check_order_paid` first if unsure, notes that Wayl reviews the request so it starts as 'Requested', and explains that `cancel_refund` can withdraw it while pending. This clearly orients the agent relative to alternatives and prerequisites.

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

• get_payment_linkA
  4.7/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds valuable behavioral specifics: 'Read-only, no side effects,' plus the caveats that checkout `code` is only returned at creation, `lineItem` and `webhookSecret` are never echoed, `total` arrives as a string needing parsing, and `env` is never reported. These are non-obvious traits that help the agent avoid misinterpretation.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose, then adds compact usage guidance and caveats in four sentences. Every sentence adds relevant information (alternatives, side effects, field behaviors, type gotcha), with no redundancy or fluff.

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

  Completeness5/5

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

  The tool has one parameter and an output schema, but the description still covers return fields (status, total, timestamps, checkout url) and details which fields are absent. It also covers when to use it vs. siblings, making it complete for an agent to invoke correctly.

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

  Parameters3/5

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

  The input schema already fully describes `reference_id` (100% coverage) including that it is the user's reference ID and not Wayl's internal link `id`. The description adds little beyond what the schema provides, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description states 'Fetch one payment link by your reference ID, including its current status,' which is a specific verb+resource. It clearly distinguishes the tool from siblings like check_order_paid, get_payment_links_batch, and list_payment_links by explaining what unique role this tool serves.

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

  Usage Guidelines5/5

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

  Explicit usage guidance is provided: 'Use this to inspect a single order...' and then directly states when to use alternatives: 'To answer "can I deliver yet?", call check_order_paid instead... For many orders use get_payment_links_batch; to browse without knowing IDs use list_payment_links.' This fully clarifies when to use this tool vs. alternatives.

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

• get_payment_links_batchA
  4.7/5.0
  Behavior5/5

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

  Annotations declare read-only and idempotent hints, but the description adds crucial behavior: unrecognized reference IDs are silently skipped, `totalFound` may be below `totalRequested` with missing IDs listed in `missingReferenceIds`, returns the raw envelope rather than enriched records, lacks a paid verdict, `total` is a string, and no retry on transient failures. These details far exceed the annotations.

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

  Conciseness5/5

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

  Each paragraph covers a distinct aspect: purpose/usage, missing-ID behavior, response envelope, status interpretation, and HTTP/no-retry semantics. The description is front-loaded with the primary purpose and is efficient given the rich behavioral nuances that need disclosure.

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

  Completeness5/5

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

  For a batch lookup tool, the description covers batch limits, silent skip behavior, response shape (`data`, `totalRequested`, `totalFound`, `missingReferenceIds`), status settlement rules (Complete/Delivered), `total` as a string, and retry semantics. This is complete guidance for safe invocation.

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

  Parameters3/5

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

  The input schema already fully describes `reference_ids`, including its meaning (your own IDs, not Wayl's internal `id`) and constraints (1-100 per call). The description adds context about behavior with unrecognized IDs, but the parameter itself is fully covered by the schema, so the baseline for 100% coverage applies.

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

  Purpose5/5

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

  The description opens with a concrete action: 'Look up many payment links at once by your own reference IDs (1-100 per call).' It explicitly contrasts with `get_payment_link` for single orders and `check_order_paid` for delivery decisions, distinguishing this batch tool from siblings.

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

  Usage Guidelines5/5

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

  The description states 'Use this when reconciling a batch of orders — far cheaper than calling get_payment_link in a loop' and directs to `get_payment_link` or `check_order_paid` when appropriate. This explicit when-to-use guidance covers both recommended contexts and alternatives.

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

• get_refundA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description reinforces the read-only nature and adds non-obvious behavioral details: the server re-attaches the refund ID as `refundId` when omitted, and the amount is a number in whole IQD (unlike link's string `total`). No contradictions with annotations.

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

  Conciseness5/5

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

  The description is moderately long but every sentence earns its place: purpose, return fields, usage guidance, alternative tools, and two subtle response quirks. It opens with a clear, specific summary and avoids fluff.

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

  Completeness5/5

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

  With only one required parameter and an output schema present, the description is more than sufficient. It covers the tool's role, its relationship to sibling tools, and key data type nuances, making the tool fully comprehensible in context.

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

  Parameters4/5

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

  The schema already documents `refund_id` with 100% coverage, but the description enriches it by clarifying that this ID is what `create_refund` returns and is not the order reference ID. This helps prevent misuse without repeating schema text.

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

  Purpose5/5

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

  The description clearly states it fetches one refund request by its Wayl refund ID and enumerates the returned fields (reason, linkId, referenceId, amount, initiatedBy, status). It distinguishes itself from siblings by explicitly contrasting with `list_refunds` and `cancel_refund`.

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

  Usage Guidelines5/5

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

  It provides explicit when-to-use guidance: poll a refund you raised with `create_refund`, and if you have only the order's reference ID, use `list_refunds` instead. It also tells users to call `cancel_refund` to withdraw a pending refund, covering both when and when-not to use this tool.

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

• list_productsA
  4.7/5.0
  Behavior5/5

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

  Although annotations already declare readOnlyHint, openWorldHint, and idempotentHint, the description adds critical context: listing changes nothing and charges nobody, returns no total count, requires paging via nextSkip/hasMore, returns price as a string, and provides richer records than get_product. This goes far beyond annotations.

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

  Conciseness5/5

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

  The description is well-structured, front-loaded with the core purpose, and every sentence provides useful information—no fluff. It covers scope, exclusions, returned record details, paging, price format, side effects, and alternatives without being redundant.

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

  Completeness5/5

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

  With an output schema present and comprehensive annotations, the description fills remaining gaps: it explains the richer record content, paging limitations, price representation, and product type filters. This is complete for a list tool of this complexity.

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

  Parameters3/5

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

  Schema description coverage is 100% for both skip and take, each with clear descriptions. The description does not elaborate on parameter usage beyond what schema provides, though it does mention paging behavior (nextSkip/hasMore) that relates to skip. Baseline 3 is appropriate given high schema coverage.

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

  Purpose5/5

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

  The description opens with a clear specific action: 'List the products in your Wayl catalogue, newest first.' It identifies the resource (products) and the ordering, and later distinguishes from siblings like get_product and sell_book by clarifying what this endpoint does and does not return.

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

  Usage Guidelines5/5

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

  The description explicitly states scope (Digital, Physical, Service) and exclusions (Subscription products are not returned), when to use it for stock inspection ('To inspect one product's stock, page this endpoint'), and names alternatives for selling (sell_book or create_payment_link). It also warns about paging semantics.

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

• list_payment_linksA
  4.8/5.0
  Behavior5/5

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

  Annotations already declare readOnly, openWorld, and idempotent, but the description adds substantial behavioral context beyond that: no total count returned, `hasMore` is a heuristic, `total` is a string, only status Complete/Delivered means paid, and the environment is not reported. The warning to confirm with `check_order_paid` before delivery is extra value not present in annotations.

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

  Conciseness4/5

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

  Every sentence carries unique operational guidance, and the description is front-loaded with the core purpose. While it is longer than minimal, there is no filler or repetition; it earns its length with dense, useful detail.

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

  Completeness5/5

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

  Given the tool's complexity, the description covers all critical operational aspects: pagination behavior, status semantics, raw record format, environment ambiguity, and cross-tool confirmation via `check_order_paid`. The output schema exists, so no need to describe return values, making this complete.

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

  Parameters4/5

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

  Schema descriptions cover all three parameters, so the baseline is 3. However, the description adds meaningful usage semantics for `statuses` (recommended combinations and omission for all states) and explains the `skip`/`nextSkip` pagination pattern, going beyond what the schema provides.

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

  Purpose5/5

  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 your payment links, newest first, optionally filtered by status.' It clearly states the sort order and filtering capability. It also distinguishes itself from siblings by explicitly naming `get_payment_link` and `get_payment_links_batch` as alternatives when you already know reference IDs.

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

  Usage Guidelines5/5

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

  The description provides direct when-to-use guidance: `statuses=['Complete', 'Delivered']` for paid orders, `statuses=['Pending']` for abandoned checkouts, and omit `statuses` for all states. It also explicitly names alternatives (`get_payment_link`, `get_payment_links_batch`) and warns against treating row count as order count, making the usage context unmistakable.

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

• cancel_refundA
  4.9/5.0
  Behavior5/5

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

  Annotations mark the tool as destructive, but the description adds meaningful context: it only affects the refund request, not the payment link or buyer's payment, requires user confirmation, and the undo involves filing a fresh refund with a new reason and re-review. This goes well beyond the annotation hints.

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

  Conciseness5/5

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

  Every sentence carries necessary information—state constraints, ID disambiguation, side effects, alternatives, and caution. The structure flows logically from action to limitations to confirmation, with no filler or redundancy.

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

  Completeness5/5

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

  For a destructive, state-dependent tool, the description covers prerequisites, scope of impact, user confirmation, and consequences. An output schema exists, so return-value documentation is not needed here. The description is fully self-sufficient for correct invocation.

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

  Parameters4/5

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

  The schema already thoroughly describes refund_id with 100% coverage. The description reinforces this and adds how to find the ID when only the order reference is available (list_refunds with reference_id). This exceeds the schema baseline.

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

  Purpose5/5

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

  The description opens with a specific action: 'Withdraw a refund request before Wayl acts on it, so no money is returned.' It clearly identifies the resource (refund request) and the effect, and differentiates from sibling tools like invalidate_payment_link_if_pending.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use and when-not-to-use guidance: only for 'Requested' status, not for 'Refunded' or 'Rejected', suggests checking get_refund first, and names the alternative invalidate_payment_link_if_pending for stopping payment. Also gives direction to list_refunds when only the order reference is known.

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

• create_payment_linkA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description reveals crucial behaviors: 'Nothing is charged until the buyer completes payment there,' env='test' charges nobody, uniqueness requirements for reference_id, refusal of unsigned webhooks, and the fact that `code` and `webhook_secret` are not retrievable later. It also notes the call is never retried and has no idempotency key, providing comprehensive operational transparency.

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

  Conciseness5/5

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

  The description is concise yet information-dense, with each sentence serving a distinct purpose: purpose, alternative, charge behavior, reference_id uniqueness, webhook constraint, data irrecoverability, and idempotency warning. It is front-loaded with the primary action and avoids redundant phrasing.

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

  Completeness5/5

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

  Given the tool's complexity (9 parameters, output schema, annotations), the description covers all critical operational aspects: return value semantics, environmental differences, webhook security pairing, uniqueness constraints, data persistence caveats, and retry behavior. It leaves no major gaps that would cause an agent to misuse the tool.

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

  Parameters4/5

  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 significant value by explaining parameter interdependencies (e.g., 'Passing `webhook_url` without `webhook_secret` is refused'), uniqueness requirements, and the ambiguity in line_items reconciliation. It also clarifies the meaning of env values and the irrecoverability of `code` and `webhook_secret`, enriching the schema's bare definitions.

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

  Purpose5/5

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

  The description opens with 'Create a Wayl payment link and return the checkout URL to send the buyer,' a specific verb+resource statement that clearly distinguishes this from siblings like `sell_book` and `get_payment_link`. It further clarifies that this is the 'general-purpose builder,' reinforcing its role.

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

  Usage Guidelines5/5

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

  Explicitly contrasts with the sibling tool: 'For selling a book, `sell_book` is usually less work — it derives the line items and reference ID for you.' It also explains when to poll `check_order_paid` and warns about the env distinction, giving clear context for when to use this tool vs alternatives.

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

• get_productA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnly and idempotent hints, but the description adds significant behavioral context: 'nothing in the catalogue changes and nobody is charged,' 'A blank product_id is rejected before any request is made,' and the format warning that '`price` is a string of whole IQD; parse it before doing arithmetic.' This goes well beyond the structured hints and helps the agent anticipate edge cases.

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

  Conciseness5/5

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

  The description is well-structured: it leads with the purpose, then usage, exclusions (what's NOT returned), a critical data-format caveat, read-only reassurance, and a cross-tool clarification. Every sentence carries distinct, useful information; there is no filler or repetition of schema/annotations.

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

  Completeness5/5

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

  Given the tool's complexity is low (one parameter), the description is nevertheless thorough. It covers the full field set returned (and what is omitted), the alternative for richer data, the ID source, and a payment-link disambiguation. An output schema exists, so return format is already defined, but the description adds the 'NOT returned' list, which is very helpful. No meaningful context is missing.

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

  Parameters4/5

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

  Schema coverage is 100% and the param description already explains the ID is Wayl's own ID, not name/slug/URL. The tool description adds value by tying the ID source to `list_products` or a product URL, and by confirming no lookup by name is possible. This reinforces and slightly extends the schema without redundancy, though the core meaning is already present in the schema.

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

  Purpose5/5

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

  The description opens with a precise verb+resource: 'Fetch one product's basic details by ID.' It clearly distinguishes from sibling tools like `list_products` and `get_payment_link` by stating it's for a single product and only basic details. No ambiguity 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.

  Usage Guidelines5/5

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

  Explicitly states when to use: 'Use it when you already have the ID from `list_products` or a product URL — there is no lookup by name or slug.' It also names an alternative for extended fields: 'for those, page `list_products` and filter by id.' Plus it clarifies the tool is unrelated to payment links, guiding against misuse.

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

• invalidate_payment_linkA
  4.9/5.0
  Behavior5/5

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

  Annotations already mark the operation as destructive, but the description adds crucial context: irreversibility, reference ID uniqueness and non-reusability, lack of status checking, undefined outcome for paid links, non-retry on transient failures, and the raw envelope return. This far exceeds the annotation baseline and fully discloses behavioral nuances.

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

  Conciseness5/5

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

  The description is front-loaded with the core action, then delivers necessary warnings and alternatives without redundant language. Every sentence provides distinct value, and the structure (purpose, consequences, caveats, alternatives, return behavior) is logical and easy to parse.

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

  Completeness5/5

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

  For a destructive, irreversible operation, the description covers all key aspects: irreversible consequences, unique ID constraints, undefined behavior on paid links, alternative tools, and retry behavior. The output schema exists, so return values need no explanation, and the description still manages to mention it returns the raw envelope.

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

  Parameters4/5

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

  The schema covers the parameter with 100% description, and the tool description reinforces it by explaining that reference IDs are unique and cannot be reused, and that the parameter is the user-set reference ID, not Wayl's internal ID. This adds meaningful semantic context beyond the schema, though the schema already carries the primary definition.

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

  Purpose5/5

  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: 'Cancel a payment link unconditionally so it can no longer be used.' It clearly distinguishes from the sibling `invalidate_payment_link_if_pending` by emphasizing 'unconditionally' and from `create_refund` by noting it cancels the checkout, not the money.

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

  Usage Guidelines5/5

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

  Explicit guidance is provided: 'Prefer `invalidate_payment_link_if_pending`, or confirm with `check_order_paid` first.' It also directs users to `create_refund` if the buyer already paid, and warns that invalidating a paid link yields undefined behavior. This is comprehensive when-to-use and when-not-to-use advice.

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

• list_refundsA
  4.9/5.0
  Behavior5/5

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

  Goes well beyond annotations by explaining status meanings ('Requested' is cancellable), amount format (whole IQD numbers vs. string), and paging semantics (no total count, use nextSkip/hasMore). No contradiction with readOnlyHint.

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

  Conciseness5/5

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

  The description is well-structured and front-loaded with the core purpose. Each paragraph covers a distinct aspect (usage, statuses, paging) with no redundant or filler sentences.

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

  Completeness5/5

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

  Given the output schema exists, the description doesn't need return details. It covers purpose, alternatives, filtering, statuses, amount types, and paging instructions, making it comprehensive for this list tool.

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

  Parameters4/5

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

  Schema already covers all parameters, but description adds valuable semantics for statuses and reference_id. The paging reference to 'nextSkip' is slightly ambiguous against the 'skip' parameter, but overall it enriches parameter understanding.

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

  Purpose5/5

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

  The description clearly states the tool lists refund requests with ordering and optional filters. It explicitly distinguishes from get_refund by emphasizing when to use this list vs. fetching a single refund by ID.

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

  Usage Guidelines5/5

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

  Provides explicit use cases: recovering a refund ID when only order reference is known, and instructing to use get_refund instead when the ID is already held. Also clarifies the reference_id filter behavior.

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

• parse_webhookA
  4.9/5.0
  Behavior5/5

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

  The description goes far beyond the annotations by revealing critical behaviors: it operates 'all locally with no network call,' handles the different paymentStatus vocabulary, simulates payment in test mode via safeToFulfil, and warns about replay attacks due to missing timestamps. This is valuable context not present in readOnlyHint or idempotentHint.

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

  Conciseness5/5

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

  Although long, every sentence earns its place for a security-sensitive webhook tool. It opens with the core purpose, moves to usage alternatives, then covers essential caveats. The structure is logical, front-loaded, and densely informative without redundancy.

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

  Completeness5/5

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

  The description covers the full operational context: authentication, payload parsing, safety fields, idempotency, replay risks, and error behavior. Given the tool's complexity and the presence of an output schema for return values, this is comprehensive and leaves no critical gaps.

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

  Parameters4/5

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

  Schema coverage is 100%, so parameter meaning is already documented. The description adds extra semantic guidance, such as reading raw_body byte-for-byte because Wayl sends text/plain, and that headers/signature are found automatically. This supplements the schema with practical context, though it does not systematically walk through each parameter.

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

  Purpose5/5

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

  The first sentence immediately states the specific verb and resource: 'Verify a Wayl webhook and summarise what it says about the order.' It distinguishes itself from siblings by explicitly naming the alternatives and their different use cases, making its purpose unmistakable.

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

  Usage Guidelines5/5

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

  The description provides clear guidance on when to use this tool: 'Use this for any incoming delivery.' It also explicitly contrasts with alternatives: 'Use verify_webhook when a bare valid/invalid boolean is enough, and check_order_paid when polling by reference ID.' It adds operational warnings like deduplicating on eventId and never acting on unverified payloads.

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

• verify_auth_keyA
  4.9/5.0
  Behavior5/5

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

  Adds significant behavioral context beyond the annotations: makes one network call, explains the 401-vs-404 routing behavior, and clarifies that success does not indicate test vs. live because Wayl uses a single key for both. This is genuinely useful nuance not derivable from readOnlyHint/openWorldHint/idempotentHint.

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

  Conciseness5/5

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

  The description is dense but each sentence earns its place: purpose, usage context, alternative, and caveats are all covered in a compact format. Front-loaded with the core purpose, then expands with relevant details without redundancy.

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

  Completeness5/5

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

  For a zero-parameter diagnostic tool with a rich output schema, the description covers all necessary context: when to use, what it returns, key behavioral caveats, and the alternative. Nothing important seems missing, and the output schema handles return-form specifics.

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

  Parameters4/5

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

  The tool has zero parameters, and the schema confirms this with 100% coverage. The description adds value by explaining what the return communicates (key validity, base URL, default environment), which is more than expected for a no-parameter tool. Baseline 4 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's function: verifying that the configured Wayl API key is accepted. It uses a specific verb ('check') and resource ('API key'), and distinguishes itself from siblings by positioning it as the first diagnostic step when payment tools fail, in contrast to wayl_status for configuration inspection.

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

  Usage Guidelines5/5

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

  Provides explicit guidance: call this first when payment tools start failing to distinguish bad key from request issues. It also names the alternative wayl_status for offline configuration inspection, giving a clear when-to-use vs. when-not-to-use distinction.

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

• verify_webhookA
  4.9/5.0
  Behavior5/5

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

  Beyond the readOnly/idempotent hints, the description discloses key behaviors: errors on missing signature/secret or out-of-range secret, no timestamp/nonce (so valid:true does not imply freshness), and instructs to treat invalid as an attack. It adds security-critical context without contradicting annotations.

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

  Conciseness5/5

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

  The description is organized into tight paragraphs, front-loading the core purpose and then layering context. Every sentence adds value, covering usage, failure modes, and security caveats without redundant fluff.

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

  Completeness5/5

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

  The tool is security-sensitive and the description covers all essential context: what it verifies, when to use it, what invalid means, how to pass the body, error conditions, and idempotency/deduplication guidance. The output schema exists, so return values need no extra explanation.

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

  Parameters4/5

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

  Schema coverage is 100% and parameter descriptions already explain each field. The tool description complements by reinforcing raw_body must be byte-for-byte, headers can be passed whole because signature is auto-found, and secrets are per link. This adds practical nuance beyond the schema.

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

  Purpose5/5

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

  The description opens with 'Check a webhook's HMAC-SHA256 signature and return only a valid/invalid answer', using a specific verb and resource, and explicitly names the sibling 'parse_webhook' as an alternative that does more. This fully distinguishes the tool from its siblings.

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

  Usage Guidelines5/5

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

  The description gives explicit guidance: 'Prefer parse_webhook for an incoming delivery' and 'Reach for this tool only when the boolean alone is what you need.' It also notes the tool runs locally with no network call, providing clear contextual usage direction.

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

• wayl_statusA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint and idempotentHint, but the description enriches them with important behavioral details: it 'Makes no network call and changes no state,' never returns secrets (only booleans), and notes that config is read once at startup so env changes require restart. It also clarifies that `apiKeyConfigured` reports presence, not validity. These go beyond annotation-provided safety hints.

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

  Conciseness5/5

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

  Every sentence earns its place: main purpose, when to call, return fields (condensed), presence-vs-validity caveat, secret handling, startup read behavior, and side-effect note. The structure is logical and front-loaded with the most important information. Despite length, it is compact for the amount of nuanced content.

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

  Completeness5/5

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

  Given zero parameters and a likely simple output schema, the description still covers edge cases (misconfiguration detection, key validity, env var changes, secret masking) and explicitly states side effects. It gives the agent everything needed to decide and invoke correctly, and it complements annotations and output schema without redundancy.

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

  Parameters4/5

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

  The tool has zero parameters, so the baseline is 4. There are no parameter semantics to explain, and the description correctly avoids inventing any. The schema coverage is 100% (empty), so no compensation is needed.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: 'Report how this server is configured, without calling the Wayl API.' This clearly distinguishes it from sibling tools, which focus on links, products, refunds, webhooks, etc. The scope (configuration/status) is unambiguous.

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

  Usage Guidelines5/5

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

  Explicit guidance is given: 'Call this first when something looks misconfigured.' It also provides a direct alternative for a related need: 'Use `verify_auth_key` to confirm the key actually works.' This tells the agent exactly when to choose this tool versus a sibling.

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

• sell_bookA
  5/5.0
  Behavior5/5

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

  The description discloses side effects: creating the link 'charges nobody', env='test' 'never moves real money at all', and it stresses the safeToFulfil requirement. This goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by explaining the real-world impact and the distinction between paid and safeToFulfil.

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

  Conciseness5/5

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

  The description is long but tightly packed: every sentence adds a distinct piece of information (purpose, calculation, minimum, env behavior, fulfillment warning, alternative tool, persistence hint). It's structured with clear paragraphs and no filler.

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

  Completeness5/5

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

  With an output schema already present, the description still covers the key returned fields (`url`, `code`), the rejection condition (total below 1000 IQD), and the critical fulfillment check (`safeToFulfil`). Together with the rich annotations and schema, an agent has everything it needs to invoke this tool correctly.

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

  Parameters5/5

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

  The schema already documents all 8 parameters at 100%, but the description adds the exact formula (`price * quantity + delivery_fee - discount`), the 1000 IQD minimum, and title truncation/padding details. It also clarifies that discount applies to the whole order, not per copy.

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

  Purpose5/5

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

  The opening sentence names the exact action and output: 'Create a checkout link for a book order, with the price breakdown filled in.' It goes on to specify the mechanics (line items, total computation, reference ID) and explicitly contrasts with create_payment_link, so the purpose is unmistakable.

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

  Usage Guidelines5/5

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

  It tells the agent exactly when to prefer this tool: 'Use `create_payment_link` instead when you need a webhook, redirect or custom line items for one order.' It also gives the negative condition ('for anything beyond a single flat-priced copy') and warns about fulfillment timing, which is crucial usage context.

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