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

No annotations are provided, so the description must carry the burden — and it discloses the side effect (reason persisted on the record), the refusal conditions for terminal states, and the full returned wire form. It omits permission/auth requirements and whether cancellation is reversible, which keeps it from 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?

Front-loads the action and precondition, then the exclusion list and return shape. Dense but every clause earns its place; the trailing status enumeration is long though it doubles as valid value documentation.

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

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

For a two-param mutation with no annotations and no output schema, it supplies the missing behavioral and return-value context. Missing only auth/permission details and reversibility.

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 both parameters carry their own descriptions with length bounds, so the schema already does the work. The description only adds that the reason is stored, which is marginal incremental value.

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?

Specific verb+resource ('Cancel an invoice') plus a crisp precondition ('that has not been paid yet') and an explicit exclusion list of final statuses, which distinguishes it cleanly from sibling get_invoice/create_invoice.

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

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

The description clearly states when the tool applies (unpaid invoices) and enumerates the terminal statuses where cancellation is refused, giving strong negative guidance. It does not name an alternative tool (e.g., refund flows) for already-paid invoices, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden and does meaningful work: it discloses idempotency-per-project semantics, the return payload shape, and the full status lifecycle enum. It omits auth/permission requirements, error behavior, and anything about expiry duration or rate limits.

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

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

Three sentences, front-loaded with purpose and outcome, then idempotency, then the return/status detail. The long status enum is dense but earns its place given there is no output schema to carry the state machine.

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, the description usefully enumerates the returned fields and status values, which an agent needs to interpret responses. It is still silent on auth requirements and failure modes for a mutation endpoint, leaving a modest 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?

Schema description coverage is 100%, so every one of the 8 parameters is already documented in the schema, including the external_order_id idempotency note. The description adds no syntax or meaning beyond what the schema provides, which is the baseline-3 case.

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

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

States a specific verb+resource ('Create a Paymos invoice') plus the concrete outcome ('get a hosted payment_url the customer opens'). This cleanly separates it from get_invoice, list_invoices, cancel_invoice, and simulate_invoice_payment without needing their schemas.

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

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

Gives real conditional guidance for the idempotency key: reuse the same external_order_id and the existing invoice is returned rather than a duplicate. It does not name alternatives or state exclusions (e.g. when to cancel vs recreate), so it stops short of a full when/when-not prescription.

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, so the description carries the burden. It discloses the full wire-form return shape and enumerates all nine status values, which is genuinely useful behavioral context (e.g. idempotent read, state machine values). It doesn't explicitly state read-only or error behavior, keeping it from 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?

Two tightly front-loaded sentences: the action and key come first, then the return shape and enum values. No wasted words; every clause adds information.

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

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

For a simple one-param read tool with no output schema, the description fully compensates by listing the returned fields and status enum. 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%, so the single invoice_id parameter is already documented with format (inv_…) and minLength. The description adds no syntax or format detail beyond the schema, so 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 and resource ('Fetch the current state of one Paymos invoice') and names the exact key ('by invoice_id'). Distinguishable from siblings create_invoice and list_invoices. Clear what it retrieves.

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 'fetch by id' framing, but there is no explicit when-to-use guidance or mention of alternatives. It does not say e.g. to use list_invoices to find an id first. Implied usage only, so a 3.

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

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

No annotations are provided, so the description carries the full burden — and it does disclose key behavior: cursor pagination, next_cursor absent on the last page, and the read-only nature implied by 'Read'. It omits auth/permission needs and rate limits, keeping it below 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 dense, front-loaded sentences with no filler; the pagination contract is stated immediately. Minor redundancy in re-listing filters already enumerated in the schema.

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

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

With no output schema, the description correctly supplies the return shape (items[] and next_cursor) plus the terminal-page condition. Combined with full schema coverage, an agent has everything needed to call and iterate 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%, so every parameter is already documented (status enum list, Unix seconds bounds, cursor origin). The description restates the filter set and Unix-seconds semantics without adding syntax the schema lacks — baseline 3.

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 with scope: 'Read one cursor-paginated page of invoices for a project.' An agent can distinguish this page-listing tool from the sibling get_invoice (single invoice) without opening the schema.

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

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

Gives clear operational guidance ('Poll with the returned cursor; do not guess offsets') and implies the filter-driven retrieval context. It does not name sibling alternatives or state when-not-to-use, so it stops short of 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses that no blockchain is touched, that the server derives all amounts and money must never be computed client-side, what each stage produces, and the resulting statuses. It still omits auth/permission requirements, idempotency behavior, and whether the simulation triggers downstream effects such as webhooks (relevant given the verify_webhook_signature sibling).

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 safety constraint and the 'server derives amounts' rule, then each stage in four short clauses, then the return shape. Information density is high and the final status enumeration is defensible because there is no output schema.

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

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

With no output schema, explaining the returned wire fields and the full status enum is exactly what the agent needs, and the mutation semantics are fully spelled out. The remaining gap is operational context: permission prerequisites, rate limits, and how this interacts with cancel_invoice and webhook verification.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: paid marks fully paid, overpaid pays more than expected, underpay leaves the invoice in underpaid awaiting a top-up, and cancel voids the invoice. It also explains that invoice_id must be a test invoice (is_test=true).

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

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

The description states a specific verb and resource ('drive a test invoice through a payment outcome') plus the critical scope constraint 'Sandbox only ... without touching a blockchain'. That distinguishes it immediately from create_invoice, get_invoice, and list_invoices, which are the read/create 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?

It gives a clear selection condition ('Sandbox only', 'test invoice'), which tells the agent when this applies versus real payment paths, and explains the semantics of each stage outcome. It never names an alternative, however, and notably fails to clarify the overlap between stage=cancel here and the sibling cancel_invoice tool.

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

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

With no annotations, the description carries the burden and delivers unusually rich detail: the header grammar t/v1, the HMAC construction over '{unix}.{payload}', the secret-rotation case where two v1 values exist and either may match, and the byte-exactness requirement. What it omits is the outcome representation — nothing says whether a mismatch throws, returns false, or what expiry produces.

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 tight sentences, front-loaded with what the tool does and back-loaded with the two pitfalls (dual v1 values, re-serialization). Every clause carries information the caller must act on; nothing is padding.

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

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

For a four-parameter, no-annotation, no-output-schema tool, the description covers the mechanics thoroughly. The remaining gap is return semantics — an agent cannot know from this text what a successful verification looks like versus an expired or mismatched one, which matters more here because no output schema fills that in.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that signature_header may legitimately carry two v1 values during rotation and pins down that payload must be the untouched raw bytes. Those constraints directly affect how the caller supplies the required parameters.

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

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

States a specific verb (verify) plus the exact resource (the X-Webhook-Signature header of a Paymos webhook) and the scope (against the raw body, locally). It is unmistakably distinct from the invoice siblings in create_invoice/list_invoices, so an agent can route to it without schema inspection.

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 supplies the operating conditions an agent needs: this is local, 'no API call', and the payload must be the raw body byte-for-byte rather than re-serialized JSON. There is no competing sibling that needs naming, but it also never states the failure/expiry conditions that would guide retry or error handling.

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