Supplier Payment Decision Agent (Ireland)

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

With no annotations, the description carries the full burden and does so: it defines PASSED only for NORMAL status, states dissolved/liquidated/unknown FAIL, and that source uncertainty returns UNAVAILABLE rather than a pass. It also discloses quota and cost behavior — 1 free attempt per UTC day per IP shared across REST/MCP with failures counted, then 0.01 USDC with explicit approval.

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

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

Front-loaded with the core action and the PASS/FAIL rule, then alternatives, then pricing. Every sentence carries information, though the pricing/quota sentence and the alternative list make it denser than ideal for a single-parameter lookup.

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

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

Complete for a simple lookup: it covers the input requirement, the three possible outcome states, the returned value (registered name), failure semantics, and cost/quota. No output schema exists, but the description already explains what comes back, so nothing material is missing.

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

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

Schema coverage is 100% and the single parameter is already well documented in the schema, so the baseline is met. The description adds selection-level meaning by warning that this is a CRO number, not a company name or VAT number, reinforcing the schema's negative guidance without adding new format rules.

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

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

Names a specific verb and resource: looks up an Irish company by CRO number in the Companies Registration Office open data, and states the outcome (registered name). It also implicitly distinguishes itself from name/VAT lookups, so an agent can tell it apart from check_vat and the supplier-payment siblings.

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

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

Explicitly says to supply a CRO number rather than a company name or VAT number, and routes the agent to named alternatives with their conditions: check_vat for VIES, verify_supplier_payment for identity reconciliation, decide_supplier_payment for a full invoice decision. It also states the boundary 'No invoice is approved here.'

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

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

With no annotations, the description carries the full burden and does so: it discloses the return format, the Irish-IBAN default-pass quirk, that no bank transfer occurs, and the exact cost/rate-limit model (1 free attempt per UTC day per IP, shared REST/MCP, failures count, then 0.005 USDC with explicit approval). These are precisely the side-effect and billing facts an agent needs before calling.

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

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

Front-loaded with the key differentiator ("Cheapest call") and the core action, then packs return format, exclusions, alternatives, side effects, and pricing into compact sentences. Every sentence supplies information the agent would otherwise lack, with no filler.

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

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

Given no annotations and no output schema, the description supplies everything needed: what is validated, what is returned, what is explicitly out of scope, which sibling to use instead, and the cost/rate-limit behavior. No material gap remains for a single-parameter validation tool.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents normalization of spaces/lowercase and the checksum-only scope. The description reinforces the same scope but adds no new syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Validates an IBAN") plus the exact checks performed (ISO 13616 mod-97 checksum, length, country) and the return shape (PASSED/FAILED with reason code). It also names what it is not (ownership, Confirmation of Payee, supplier identity), so an agent can separate it from every sibling without opening a schema.

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

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

Explicitly gives the when-to-use ("before you pay it"), the when-not-to-use ("not account ownership, bank Confirmation of Payee or supplier identity"), and routes each adjacent need to the right alternative: check_vat, check_company, decide_supplier_payment. Nothing is left to inference.

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

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

With no annotations, the description carries the full burden and delivers: statelessness, that it operates on caller-supplied documents rather than ERP records, the return contract (PASSED/FAILED plus reason code), and explicit exclusions (no CRO/VIES lookup, no signature validation, no bank transfer). This is exactly the behavioral context an agent needs before invoking.

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

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

Front-loaded with the core comparison, then layered with scope exclusions and routing guidance; every sentence adds distinct value and none is redundant. It is dense but not padded, stopping just short of the tightest possible phrasing.

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

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

Despite no output schema, the description states the return shape (PASSED/FAILED plus reason code) and clearly bounds scope (no CRO/VIES, no signature validation, no transfer) and preconditions (approved fee). Enough for an agent to invoke correctly without further clarification.

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

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

Schema description coverage is 100% and the single nested request parameter is fully documented in the schema, including per-field descriptions for supplier_cro_number, invoice, PO and goods receipt. The description adds only the general framing that the caller attaches the documents and that the CRO number is not looked up, so the baseline 3 is appropriate.

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

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

States a specific verb (checks) and resource (PO, goods receipt, invoice) and enumerates exactly what is compared: supplier, currency, amount, line items, unit prices, quantities received. It also names the sibling decide_supplier_payment, so the agent can distinguish it without opening any schema.

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

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

Explicitly routes to decide_supplier_payment 'when document matching must be combined with supplier identity, VAT, payee and signature checks,' giving a concrete selection condition. It also states the operational precondition that an explicitly approved service fee is required.

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

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

No annotations are supplied, so the description carries the full load and does so: it discloses the three possible outcomes (PASSED/FAILED/UNAVAILABLE), the accompanying reason code and evidence, the paid/free cost model with a per-IP daily quota shared across REST and MCP, that failed attempts consume quota, and that payment requires explicit approval. It also states the correct interpretation of an outage, which prevents a costly false negative.

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

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

Front-loaded with the core action and return values before routing, outage interpretation, and cost. Despite its length, each sentence carries distinct operational information (outcomes, alternatives, retry prohibition, quota, pricing) with no restatement of the tool name.

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

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

There is no output schema, yet the description enumerates the return statuses, the reason code, and the evidence fields, so an agent knows what comes back. Combined with quota, pricing, and failure-interpretation notes, nothing needed to call or interpret this tool is missing.

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

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

Schema description coverage is 100% and the single vat_number parameter is already documented with the IE-prefix, whitespace and lowercase normalization rules. The description adds nothing about the parameter beyond the schema, so this sits at the baseline for fully documented schemas.

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

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

States a specific verb chain (validates format and check letter, then confirms registration live with EU VIES) and the exact resource, which is more than the bare name conveys. It also distinguishes itself from check_company, verify_supplier_payment and decide_supplier_payment by naming what each of those does instead.

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

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

Explicit scope boundary for use ('for one VAT number, not company-name matching or invoice approval') plus an explicit routing table to the three sibling alternatives. It also gives situational guidance for the outage case ('an outage is uncertainty, not invalid registration; do not auto-pay to retry'), which is exactly the kind of when-not guidance that prevents agent mistakes.

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

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

No annotations exist, so the description carries the full burden and does so: it states it decides only and never moves money, that retries require a stable transaction_id and must not trigger repayment, that it returns per-check results with reason codes and a confidence score, and that independent payment approval must be retained. It also proactively disambiguates two misleading result labels (CONFIRMATION_OF_PAYEE and ERP_THREE_WAY_MATCH) that an agent would otherwise misinterpret.

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

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

The purpose and outcome set are front-loaded, and nearly every sentence contributes a distinct constraint (gates, outcome enum, label caveats, key prerequisite, sibling routing, retry discipline). It is dense rather than padded, though the run-on sequence of caveats makes it a wall of text that could be split into clearer blocks.

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

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

There is no output schema, so the description correctly compensates by describing the return shape (one of three verdicts, per-check results, reason codes, confidence score). Combined with the prerequisite, retry, and escalation guidance, an agent has everything needed to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100% with a single top-level parameter, so the baseline is 3. The description still adds real semantics the schema does not: transaction_id must be stable across retries and changed content under the same ID conflicts, and the signature requires a key registered beforehand. It stops short of detailing the nested supplier/invoice fields, which the schema already covers.

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

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

The description states a specific verb+resource (an independent third-party payment decision on an Irish supplier invoice) and enumerates the five gates it runs and the exact three outcomes it can return. It explicitly distinguishes itself from verify_supplier_payment and get_verification, so an agent can route between them without opening a schema.

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

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

It names the conditions for use (complete signed invoice/PO/GRN workflow), the prerequisite (register a signing key first via /v1/agent-keys), the alternatives to avoid (verify_supplier_payment's identity/VAT contract, get_verification retrieval), and the escalation rule (provider uncertainty requires review, not execution). Both when-to-use and when-not-to-use are explicit.

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

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

With no annotations, the description carries the full burden and does so richly: it explains that results are stored and registry checks are not rerun, states the auth model (original paying wallet for x402, or bearer token with verification.read scope), discloses not-found behavior for missing/other-tenant IDs, flags a retrieval service fee requiring spending approval, and warns against automatic payment retries.

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

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

Front-loads the action and the required identifier type, then layers constraints and cautions. Every sentence is informative, though the cautionary tail (fee, retry, authorization inference) makes the paragraph dense enough that trimming some redundancy with the schema would help.

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

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

No output schema and no annotations, so the description must cover behavior and returns; it does both by enumerating the stored result states (RELEASE/REVIEW/BLOCK/INSUFFICIENT_EVIDENCE) and the ownership/auth requirements. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, and the schema already documents the verification_id UUID and the IDs not to supply. The description largely restates this (tenant/wallet ownership, wrong-ID types), adding reinforcement rather than new syntax or format detail, so baseline 3 applies.

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

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

States a specific verb+resource (read an existing identity/VAT verification) and anchors it to its producer (verify_supplier_payment / POST /v1/verifications). It explicitly carves itself out from siblings, noting it neither reruns registry checks, retrieves decide_supplier_payment decisions, nor creates a verification.

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

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

Gives explicit when-to-use conditions and exclusions: supply the returned verification_id UUID, not request_id, transaction_id, invoice number, or A2A task ID, and the ID must belong to the same tenant. It names the alternative actions (decide_supplier_payment, verify_supplier_payment) it is not a substitute for.

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

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

With no annotations, the description carries the full burden and mostly delivers: immutability per tenant, rotation via new key_id, conflict on duplicate key_id, private key must stay local, and the fee-approval prerequisite. It omits auth/permission scope and any rate or latency expectations, so it falls just short of exhaustive.

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

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

Front-loaded with purpose, then constraints, then prerequisites; every sentence conveys actionable info. Dense but not padded, though the trailing fee-approval sentence reads as an afterthought.

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

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

No output schema exists, but the description compensates by naming the return values (key_id, registered=true) and covering mutability, rotation, conflicts, and call prerequisites. Adequate for a 2-param registration tool, though it lacks authorization/permission context.

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

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

Schema description coverage is 100%, so the schema already documents key_id uniqueness/rotation and PEM/key-size rules; the description largely echoes those rather than adding new parameter-level detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Registers an RSA public key ... used to sign payment-decision requests') with concrete constraints (2048-bit+, PEM). It explicitly distinguishes itself from siblings like check_* tools and payment authorization, so an agent can route correctly.

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

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

Gives explicit sequencing ('Use before decide_supplier_payment'), a consistency requirement ('same tenant/paying wallet for registration and decision'), negative boundaries ('not a supplier check, API-key creation or payment authorization'), and a prerequisite (approve the registration fee first).

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

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

With no annotations, the description carries the full burden and does so richly: it discloses that it creates a verification, may call external sources, never executes or authorises a bank payment, requires x402 service-fee approval or an authorized bearer token, and must not be auto-retried because it is paid. It also describes the advisory decision values and per-check return shape.

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

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

Four dense sentences, front-loaded with the primary use case and routing guidance, and each clause earns its place by covering side effects, auth, and retry policy. It is appropriately sized for a complex paid tool, though the run-on construction is slightly heavy.

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

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

For a complex, paid, no-annotation tool with no output schema, the description covers the return decision set, side effects, auth, and sibling routing well. The remaining gap is the purpose of the optional transaction/evidence/payment-destination parameters, which the low schema coverage does not fill.

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

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

Schema description coverage is only 36%, so the description should compensate, and it partly does by naming the three supplier identity fields being reconciled. However, the majority of the 11 parameters (transaction, evidence, customer_assertions, payment_destination, callback, metadata) are not explained in the description, leaving a meaningful gap.

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

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

States a specific verb (reconciles), the exact resources (claimed legal name, company registration number, VAT number), and the authoritative sources (Irish CRO and EU VIES). It immediately distinguishes itself from the signed invoice decision, so an agent can tell it apart from decide_supplier_payment without opening a schema.

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

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

Explicitly says when to use it ('supplier identity and VAT reconciliation') and when not ('not the full signed five-gate invoice decision'), then names the alternatives: decide_supplier_payment for the signed workflow, the individual check tools for a single check, and get_verification only for retrieval. Nothing is left to inference.

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