WavePay Payments

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the required auth header (x-wavepay-service-key with an mk_live_…/mk_test_… key), which is real context an agent needs, but it says nothing about read-only vs mutating behavior, pagination, rate limits, or response 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?

Two short sentences, scope front-loaded and the auth prerequisite second; every clause carries information and nothing is padded.

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

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

For a no-parameter read tool with no output schema, the description covers what the catalog contains and how to authenticate, which is enough to invoke it correctly. The absence of any statement about read-only nature or result volume is a minor gap.

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

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

The tool takes zero parameters, so the baseline of 4 applies and there is no parameter-level semantics to add beyond what the schema (an empty object) shows.

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 resource (the merchant's catalog) and enumerates its contents — sites, plans, prices, coupons — scoped to the caller's merchant key. It is clear what the tool returns, though it never explicitly distinguishes itself from the nearby wavepay_pricing sibling.

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

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

Usage is implied by 'the sites, plans, prices and coupons your merchant key can see,' which tells an agent this is the merchant-scoped read surface. However, there is no statement of when to prefer it over wavepay_pricing or wavepay_providers, and no exclusions are given.

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

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

With no annotations, the description carries the full burden, and it does add one genuinely useful behavioral fact: the tool returns a hosted checkoutUrl to hand to the buyer. However, it says nothing about whether calling it creates a persistent session/order, whether repeated calls are idempotent, what auth or account state is required, or how provider-specific flows differ.

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

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

A single sentence that front-loads the action and appends the return value efficiently; nothing is padded. The only cost is the undefined 'rail', which spends words without adding precision.

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

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

For a 5-parameter, 4-required mutation-style tool with no annotations, no output schema, and 0% schema coverage, the description covers purpose and return artifact but omits parameter meaning, required account/auth state, and side effects. An agent could not confidently populate the schema from this description alone.

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

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

Schema description coverage is 0% for five parameters, so the description must compensate, and it partially does: 'product/plan' maps to productId+planId, 'rail' loosely gestures at provider, and 'buyer' implies email/phone. It still leaves phone optionality, the provider enum values (paynow, paynow-mobile, paypal), and the required email semantics entirely to the schema's type declarations.

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

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

The description names a specific verb and resource ('Start a checkout for a product/plan on a rail') and states the artifact produced (hosted checkoutUrl). It is clearly distinct from siblings like wavepay_checkout_status, wavepay_catalog, and wavepay_pricing, though the term 'rail' is jargon that isn't defined and slightly muddies the resource being acted on.

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

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

There is no explicit guidance on when to use this tool versus wavepay_checkout_status or wavepay_pricing, nor any prerequisites (e.g., must the product already be in the catalog? must the buyer be registered via wavepay_register?). Usage is only inferable from the verb 'Start a checkout', which is minimal guidance rather than a stated condition.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the three terminal/non-terminal states (pending | collected | expired), which tells the agent when to stop polling, but omits whether the call is read-only, any rate limits on polling, and auth requirements.

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

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

A single front-loaded sentence with zero filler — action, input, and outcome all in one line. It is efficient, though arguably terse to the point of omitting necessary context.

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

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

No output schema exists, and the description at least enumerates the possible status values, which partly compensates. However, for a polling tool it should mention polling cadence/termination conditions and the reference's origin, leaving it adequate but not complete.

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

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

Schema description coverage is 0% for the single 'reference' parameter, and the description only restates 'by reference' without specifying its format, origin (e.g., returned by wavepay_checkout), or constraints. The listed states are return values, not parameter semantics, so they add nothing here.

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

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

States a specific verb ('Poll') and resource ('a payment by reference'), and the enumerated states make the intent unmistakable. It is reasonably distinguishable from siblings like wavepay_checkout (initiation) and wavepay_register, though it never names them explicitly.

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

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

'Poll' implies usage after a checkout, but there is no explicit when-to-use guidance, no mention of the sibling wavepay_checkout that creates the payment, and no statement of when it is unnecessary. Usage is inferable but not directed.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Live' hints at real-time, non-cached reads, but the description says nothing about permissions, latency, whether the call is side-effect free, or which rail values are valid.

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

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

One compact sentence with no filler, and the resource (plans and prices) is front-loaded. It is a noun fragment rather than a sentence, which slightly reduces readability but wastes nothing.

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

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

With no output schema or annotations, the description partially compensates by describing the returned content (plans, prices, rail breakdown, active promotion). It still leaves 'rail' undefined and does not say what happens when no promotion is active, which an agent needs to interpret results.

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

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

Schema description coverage is 0% and the single parameter productId is undocumented anywhere. The description refers to 'a product' but never explains the identifier's format or origin, so it adds no real meaning beyond the schema key name.

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

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

The description names a clear resource and payload — plans, prices, per rail, plus the active promotion for a given product — so an agent knows this returns pricing data rather than performing a transaction. It does not, however, explicitly differentiate itself from the nearest sibling, wavepay_catalog, which likely also exposes plan information.

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

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

There is no guidance on when to call this versus wavepay_catalog or wavepay_checkout, and no prerequisites or exclusions are stated. The agent must infer that this is the pricing lookup path and the others are not.

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

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

With no annotations, the description carries the full burden. It discloses useful scope ("this deployment") and effectively enumerates the payload contents, but never states that the call is read-only, whether it is cached, or requires auth. Adequate but missing the safety profile an agent would want.

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

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

A single front-loaded sentence with the verb, scope, and payload enumeration all in one pass. Every clause earns its place; nothing is padded or repeated.

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

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

For a zero-parameter lookup with no output schema, the description covers what the agent needs: it explains the scope and lists the rails that will be returned. It could go further by noting the read-only nature or that the list is deployment-dependent, but the essentials are present.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4 and there is nothing for the description to disambiguate. No parameter details are needed or missing.

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 ("List") and resource ("payment rails this deployment can take") and enumerates the concrete providers, so the agent knows exactly what comes back. It implicitly distinguishes itself from wavepay_catalog and wavepay_pricing by scoping to supported rails, though it never names those siblings explicitly.

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

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

Usage is only implied — an agent can infer this is the discovery call for supported payment methods, but the description never says when to prefer it over wavepay_catalog or wavepay_pricing, nor states any prerequisites. No exclusions or alternatives are given.

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

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

With no annotations, the description carries the full behavioral burden and does well: it warns that the merchant key is returned only once and that only its hash is persisted, plus discloses a free-tier quota of 25 payments per 30 days. It omits auth requirements and duplicate-registration behavior, keeping it short of a 5.

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

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

Three short sentences, front-loaded with the action and immediately followed by the most consequential facts (one-time key, quota). Every sentence earns its place with no filler.

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

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

There is no output schema, and the description compensates by explaining the critical return value (single-use merchant key) and the free-tier limit. It stops short of covering failure modes such as duplicate emails or validation errors, but is otherwise complete for a two-parameter registration tool.

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

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

Schema description coverage is 100%, so both parameters (name, ownerEmail) are already documented in the schema. The description adds no parameter-level detail, making the baseline 3 correct.

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 ('Register a WavePay merchant account') in the first sentence, which is unambiguous against siblings like wavepay_checkout, wavepay_catalog, and wavepay_pricing. An agent can tell this is the account-creation tool 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?

The purpose implies onboarding use, but there is no explicit when-to-use guidance, no prerequisites, and no mention of what to do if a merchant already exists. With no competing registration sibling, the implied usage is adequate but sparse.

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