Server Quality Checklist

Tool Scores

• create_payment_linkC
  2.8/5.0
  Behavior2/5

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

  The annotation readOnlyHint=false already signals a write operation, and the description repeats this with 'Write operation.' It adds that the result is a hosted checkout link and QR code, but does not disclose behavioral details like idempotency, expiration handling, required permissions, side effects, or what happens on failure.

  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 a single concise sentence that is front-loaded with the operation type. It has no filler or irrelevant details, though 'Write operation' is somewhat redundant with the annotation readOnlyHint=false.

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

  Completeness2/5

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

  For a tool with seven parameters, no output schema, and no usage guidance, the description is too sparse to support correct invocation. It states the intended artifact but omits required parameter semantics, return value expectations, and behavioral context, so an agent would still need substantial external knowledge.

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

  Parameters1/5

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

  Schema description coverage is 0%, and the description provides no parameter-level meaning. None of the seven parameters (amount, currency, merchantTransactionId, expiresAt, customIpnUrl, idempotencyKey, description) are explained, leaving the agent with only raw JSON schema constraints and no semantic context.

  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 uses a specific verb ('create') and a specific resource ('hosted ZEN checkout link and QR code for a customer to pay'). This clearly distinguishes the tool from read-oriented siblings like get_payment_link and list_payment_links, and from other create operations like create_payout and create_customer.

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

  Usage Guidelines2/5

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

  The description gives no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusion criteria. The agent is left to infer that this is the creation tool for payment links based solely on the name and sibling list.

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

• create_customerC
  2.9/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=false, and the description reinforces this with 'Write operation'. It adds meaningful context by noting that the tool 'stores personal data', signaling persistence and privacy implications. There is no contradiction with annotations, but other side effects are not disclosed.

  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 a single, tight sentence with the operation type and resource front-loaded. There is no filler or redundancy. However, the brevity comes at the cost of omitting parameter and behavioral details.

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

  Completeness2/5

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

  With five parameters, no parameter descriptions, no output schema, and minimal annotations, the description is not sufficient for an agent to invoke the tool correctly. It leaves out return value, duplicate handling, idempotency behavior, and what happens after a successful creation.

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

  Parameters1/5

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

  Schema description coverage is 0%, and the description names none of the five parameters. It does not explain the required email, the purpose of idempotencyKey, or how phone and name fields relate to the stored personal data. The description fails to compensate for the schema's complete lack of parameter documentation.

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

  Purpose4/5

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

  The description uses a specific verb and resource: 'create a customer record in ZEN', and states its purpose, 'for future payment flows'. This clearly identifies the tool's domain and helps distinguish it from siblings like create_payment_link, which create a different resource.

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

  Usage Guidelines3/5

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

  The phrase 'for future payment flows' implies this is a setup step before payment operations, providing some usage context. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites such as whether a customer email must be unique.

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

• download_reportB
  3.1/5.0
  Behavior3/5

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

  The 'Read-only' prefix aligns with the readOnlyHint annotation, and 'request ... download' hints at an async request-style behavior, which adds modest context. However, it does not disclose what the request returns, whether a file/link is produced asynchronously, or any auth or rate-limit considerations beyond the annotation.

  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 a single front-loaded sentence with no filler, and the read-only qualifier is placed first. It is concise, though the brevity comes at the cost of leaving out needed parameter and return-behavior context.

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

  Completeness2/5

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

  For a tool with four undocumented parameters and no output schema, the description is too thin: it does not clarify date formats, reportType values, whether parameters are conditionally required, or what the response to the download request looks like. It communicates basic intent but not enough to invoke correctly in varied situations.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description carries the burden for explaining the four parameters. It only constrains reportType indirectly via 'transaction or settlement report' and says nothing about format, startDate, or endDate semantics, leaving the agent to rely on parameter names and loose inference.

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

  Purpose4/5

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

  The description states a specific action ('request a report download') and a specific resource ('transaction or settlement report') from ZEN. The report domain separates it from sibling tools like get_transaction, though it does not explicitly name any alternative.

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

  Usage Guidelines3/5

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

  The description implies the tool should be used when a transaction or settlement report download is needed, but it gives no explicit guidance on when it should be preferred over siblings or what conditions make it inappropriate. There are no when-not-to-use statements or alternative tool references.

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

• cancel_transactionB
  3.3/5.0
  Behavior4/5

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

  The description explicitly labels the operation as a destructive write, consistent with annotations, and adds real consequences: it may prevent or reverse payment processing and requires confirmation. This is useful behavioral 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.

  Conciseness5/5

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

  Two compact sentences front-load the destructive nature and clearly state the core action, consequence, and caution with no wasted words.

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

  Completeness3/5

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

  For a simple two-parameter destructive tool, the description covers the essential semantics and risk, but leaves gaps: no state prerequisites, no explanation of idempotencyKey, and no indication of what the response contains given there is no output schema.

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

  Parameters2/5

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

  The description adds no parameter-level meaning; with 0% schema description coverage, id and idempotencyKey rely on their names alone. The id is loosely implied as the transaction to cancel, but idempotencyKey's purpose is entirely unexplained.

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

  Purpose4/5

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

  The description states a specific action ('cancel a ZEN transaction') and identifies the resource, so an agent knows what the tool does. It does not differentiate cancellation from the sibling refund_transaction or capture_transaction, which keeps it from a 5.

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

  Usage Guidelines2/5

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

  The only usage guidance is a caution to 'confirm before use,' which does not say when cancellation is appropriate versus alternatives like refund_transaction. There is no mention of transaction state or conditions that select this tool.

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

• list_payment_linksB
  3.3/5.0
  Behavior3/5

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

  The description echoes the readOnlyHint annotation and adds 'hosted ZEN' as a scoping detail. It does not disclose pagination, filtering, rate limits, or response behavior, but annotations already cover the read-only safety profile, so this is acceptable but not rich.

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

  Conciseness5/5

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

  One short, front-loaded sentence with no filler. It communicates the operation and read-only nature efficiently.

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

  Completeness3/5

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

  For a simple list operation with all optional parameters, an agent can safely call it with no arguments. However, the description does not explain filtering or pagination semantics, and there is no output schema to clarify return shape, leaving noticeable gaps.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description does not explain page, limit, or status. The parameter names hint at pagination and filtering, but status values and pagination behavior are left entirely to inference.

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

  Purpose4/5

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

  The description uses a specific verb and resource: 'list hosted ZEN payment links.' It is clear enough to distinguish from get_payment_link (single link) and list_payment_methods (different resource), though it does not explicitly draw those contrasts.

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

  Usage Guidelines3/5

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

  The intended use is implied by the name and description, but there is no explicit guidance about when to choose this over get_payment_link or create_payment_link. The read-only label helps with safety, not with tool selection.

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

• capture_transactionA
  3.5/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'Destructive write' partially restates that. However, it adds meaningful context by specifying the destructive consequence: funds are actually collected, making the operation financially irreversible. The 'Confirm before use' warning reinforces the destructive nature beyond the annotation flags.

  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?

  A single, front-loaded sentence that immediately signals destructive behavior, states the operation, and provides a clear warning. Every word earns its place, and the structure is highly scannable.

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

  Completeness2/5

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

  With no output schema and no parameter descriptions, the tool definition is spartan. The agent knows the tool is destructive and collects funds, but it lacks crucial details about optional partial captures, idempotency, expected responses, or failure conditions. For a financial write operation, this is too incomplete for confident invocation.

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

  Parameters1/5

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

  Schema description coverage is 0%, so the description must compensate for unexplained parameters. It does not mention the 'id' field, the optional 'amount' (which likely indicates partial capture), or 'idempotencyKey'. An agent receives no help understanding what each parameter means or how they interact, making this a significant gap.

  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 a specific verb ('capture'), a specific resource ('an authorized transaction'), and the concrete effect ('causing funds to be collected'). This clearly differentiates it from siblings like refund_transaction or cancel_transaction by describing the actual money movement that occurs.

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

  Usage Guidelines3/5

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

  The phrase 'capture an authorized transaction' implies the tool is for transactions that have been previously authorized and are ready for fund collection. However, there is no explicit guidance on when to use this over refund_transaction or cancel_transaction, and no mention of preconditions beyond authorization. The warning 'Confirm before use' is a caution, not a usage rule.

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

• create_payoutA
  3.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=false and destructiveHint=true; the description reinforces this and adds useful context: 'Highest-risk destructive write' and 'send money outward' clarify the real-world consequence. It also warns to verify key parameters, which is valuable behavioral guidance beyond the boolean 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?

  The description is a single, dense sentence that front-loads the most critical warning and immediately states the action. Every word contributes to the message, with zero filler or redundancy.

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

  Completeness2/5

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

  For a high-risk mutation tool with 9 parameters, no output schema, and no enum/schema guidance, a one-sentence warning is not enough. The agent is left without crucial usage context such as idempotency behavior, required field semantics, return values, or failure modes. This is a significant gap for a tool with destructive consequences.

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

  Parameters2/5

  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 names recipient, channel, currency, and amount—which loosely map to customerEmail/customerPhone, paymentChannel, currency, and amount—but leaves idempotencyKey, merchantTransactionId, and customer name fields unexplained. This is insufficient for an agent to correctly populate all 9 parameters.

  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 the specific action: 'send money outward through ZEN,' which clearly identifies creating a payout. This also differentiates it from sibling tools like refund_transaction, capture_transaction, and create_payment_link, none of which move money outward as a payout. The verb and resource are unambiguous.

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

  Usage Guidelines3/5

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

  The description gives cautionary context ('Highest-risk destructive write') and a pre-use verification checklist (recipient, channel, currency, amount), which helps the agent proceed safely. However, it does not explicitly specify when to choose this tool over alternatives or mention any condition when it should not be used.

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

• refund_transactionA
  3.7/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint=true, and the description reinforces this by leading with 'Destructive write.' It adds a valuable safety instruction to confirm the transaction and amount, and clarifies that partial refunds are possible. However, it does not discuss idempotency or return behavior.

  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 two sentences with no filler. The destructive-write warning is front-loaded, and the caution is immediately actionable.

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

  Completeness2/5

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

  With four parameters, zero schema descriptions, no output schema, and a financial operation requiring care, the description is not complete. It omits the roles of zenId and idempotencyKey, does not explain refund status effects, and gives no indication of the response. The safety caution helps but is insufficient.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must carry the burden of explaining parameters. It references 'transaction' and 'amount' but leaves zenId and idempotencyKey completely unexplained. Even for the mentioned parameters, it adds little beyond what the schema already indicates.

  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 a specific action—'return all or part of a payment to the customer'—with a clear verb and resource. It distinguishes itself from siblings like capture_transaction and cancel_transaction by focusing on refunding funds back to the customer.

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

  Usage Guidelines3/5

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

  The description implies the tool is used to refund a payment, but it does not explicitly say when not to use it or compare it with alternatives such as cancel_transaction for pending payments. The caution 'Confirm the transaction and amount before use' provides a precondition but not usage context.

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

• get_payoutA
  3.8/5.0
  Behavior3/5

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

  The description repeats the readOnlyHint annotation with 'Read-only' but does not add meaningful behavioral detail beyond that. It does not mention error behavior, response shape, or any side-effect-related caveats, though the annotations already cover the safety profile.

  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 a single sentence with no filler. It front-loads the read-only nature and immediately states the action and target resource.

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

  Completeness4/5

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

  For a simple read-only lookup with one parameter, the description is nearly complete. It identifies the resource, the identifier, and the safe read-only nature, which is sufficient 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.

  Parameters3/5

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

  The input schema only provides 'zenId' as a string with minLength 1, so the description's 'by its ZEN ID' adds useful semantic meaning by tying the parameter to the ZEN payout identifier. It does not, however, explain the ID format or origin.

  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 uses a specific verb ('retrieve'), identifies the resource ('a ZEN payout'), and specifies the lookup key ('by its ZEN ID'). This clearly distinguishes it from sibling tools like get_transaction or create_payout.

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

  Usage Guidelines3/5

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

  The phrase 'by its ZEN ID' implies the tool should be used when the agent already has a ZEN payout ID and needs the corresponding payout details. However, it does not explicitly state when to prefer this over get_transaction or mention any exclusions.

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

• list_payment_methodsA
  3.8/5.0
  Behavior3/5

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

  The 'Read-only' label reinforces the annotation but adds little beyond it. The description does add the scope 'configured ZEN terminal,' which implies dependence on terminal settings, but provides no further behavioral details like output shape or ordering. Annotations already cover the safety profile.

  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?

  A single front-loaded sentence contains all necessary information. There is no redundant wording or unnecessary detail.

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

  Completeness4/5

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

  For a zero-parameter read-only list operation, the description is sufficient to know what the tool does and when to call it. The absence of an output schema is notable but not critical given the simplicity of the operation.

  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 input schema has zero properties and schema description coverage is 100%, so there is nothing for the description to add about parameters. Baseline 4 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 a clear verb ('list') and resource ('payment methods available to the configured ZEN terminal'). It is specific enough to distinguish from sibling tools like list_payment_links and list_supported_currencies, even without naming them.

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

  Usage Guidelines2/5

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

  No guidance on when to choose this tool over alternatives is provided. The description simply states what it does, leaving the agent to infer appropriate usage from context.

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

• verify_webhook_signatureA
  3.8/5.0
  Behavior3/5

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

  The readOnlyHint annotation already establishes the safety profile, and the description reinforces it with 'Read-only'. The description adds context about the configured IPN secret, but it does not disclose the output format, whether verification failures are errors or just false results, or any other behavioral details.

  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 a single, tightly written sentence that front-loads the most important trait ('Read-only') and conveys the tool's exact purpose without filler. Every word adds value.

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

  Completeness3/5

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

  For a simple two-parameter verification tool with readOnlyHint and openWorldHint annotations, the description covers the core use case. However, with no output schema, the lack of any statement about the return value or how to interpret verification results leaves an agent guessing about the outcome of the call.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It mentions 'signature' and the IPN secret, but it does not explain that 'payload' is the webhook body, how the signature should be formatted, or how the two relate in the verification process.

  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 uses a specific verb ('verify'), a clear resource ('ZEN IPN webhook signature'), and explicitly marks the operation as read-only. This clearly distinguishes it from all sibling tools, which are payment, transaction, and reporting operations.

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

  Usage Guidelines4/5

  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: when a ZEN IPN webhook signature needs to be verified. It does not explicitly name alternatives or exclusions, but no sibling tool appears to perform a similar function, so the routing is unambiguous.

  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/5.0
  Behavior3/5

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

  The description repeats the read-only nature already declared by readOnlyHint=true, which is consistent, and adds that the payment link is 'hosted ZEN'. However, it does not add much behavioral context beyond what annotations already provide, such as not-found behavior, response shape, or open-world fields.

  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?

  A single, front-loaded sentence with no filler. 'Read-only' is placed first for safety awareness, and the verb, resource, and access pattern are all conveyed efficiently.

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

  Completeness4/5

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

  For a simple, single-parameter read-only getter, the description is nearly complete. It could mention expected response content or explicit routing to list_payment_links, but the combination of annotations and clear ID-based retrieval makes the tool actionable.

  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 0%, so the description must compensate. It does identify the parameter as the payment link ID, but the schema already names the parameter 'id' and the tool name already implies the resource, so the added semantic value is modest.

  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 a specific verb ('retrieve'), a specific resource ('hosted ZEN payment link'), and the key discriminator ('by ID'). This distinguishes it from sibling tools like list_payment_links and create_payment_link without needing to inspect schemas.

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

  Usage Guidelines4/5

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

  The description gives clear context: this is for fetching a single payment link by its ID, and it is read-only. It does not explicitly name alternatives or state when not to use it, but the emphasis on 'by ID' makes the intended use obvious relative to listing or creating payment links.

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

• list_supported_currenciesA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, and the description reinforces the read-only nature while adding context that the list is confirmed against public documentation. This makes the data source and scope clear, which is meaningful 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.

  Conciseness5/5

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

  A single, front-loaded sentence that immediately communicates read-only safety and the resource being listed. Every word earns its place, with no filler or repetition of the tool name.

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

  Completeness4/5

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

  For a zero-parameter read-only list tool, the description is adequate: it specifies the resource and the source of truth. The lack of an output schema is mitigated by the intuitive nature of listing supported currencies, though slightly more detail about the return format could make it fully 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?

  The tool has zero parameters, so the description cannot meaningfully add parameter semantics. The baseline of 4 for a parameterless tool is appropriate here because no parameter documentation 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?

  States a specific verb ('list') and resource ('currencies confirmed in the public ZEN documentation'), which clearly distinguishes it from sibling tools like list_payment_methods. The scope is also precise, indicating the source of the data.

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

  Usage Guidelines2/5

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

  The description gives no explicit guidance on when to use this tool versus alternatives, and does not mention any when-not-to-use conditions. The purpose is obvious from the name, but the tool description itself provides only implied usage context.

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

• get_transactionA
  4.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only safety profile is covered. The description adds the 'exactly one identifier' constraint, which is useful, but it does not disclose behavior on errors, missing identifiers, or both identifiers being supplied. This is acceptable given the annotation coverage but not rich.

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

  Conciseness5/5

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

  A single sentence front-loads the read-only safety cue and packs in the essential identifier constraint with no filler. Every word earns its place.

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

  Completeness5/5

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

  For a simple read-only retrieval tool with two parameters and no output schema, the description is complete enough for an agent to call it correctly. It states the operation, the resource, and the exact identifier requirement, covering the main ambiguity created by the schema's missing required fields.

  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 description coverage is 0%, so the description must compensate. It does by clarifying that zenId and merchantTransactionId are alternative identifiers and that exactly one must be provided. This is high-value semantic information missing from the schema, though it stops short of explaining the format or provenance of each ID in detail.

  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 uses a specific verb ('retrieve') and resource ('transaction'), and further narrows scope by requiring exactly one ZEN ID or merchant transaction ID. This clearly distinguishes it from sibling tools like get_payment_link and get_payout, which target different resources.

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

  Usage Guidelines4/5

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

  The description gives clear usage context: use this when you need a transaction and have one of the two accepted identifiers. It also communicates a key constraint ('exactly one'), though it does not explicitly name alternatives or state when not to use this tool.

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