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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds genuinely new behavioral context: it only applies to unpaid invoices, and the agent must obtain user confirmation before invoking — an interaction protocol annotations cannot express. It stops short of saying what error or state results if the invoice is already paid.

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: the action and effect first, the confirmation requirement second. Every clause earns its place with no redundancy.

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 single-parameter destructive mutation with no output schema, the definition covers action, precondition, effect, and the confirmation requirement. It is only marginally short of complete: success/failure behavior for non-unpaid invoices and whether cancellation is reversible are left unstated.

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?

There is one parameter (`id`) with 0% schema description coverage, so the schema contributes nothing. The description never mentions the parameter, its format, or where the invoice id comes from; the name alone makes 'invoice id' inferable, but the description does not compensate for the coverage 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?

The description gives a specific verb (cancel) and resource (invoice) plus the effect ('so it can no longer be paid') and a precondition ('unpaid'). It does not name a sibling, but no sibling overlaps with cancellation, so an agent can still discriminate it from get_invoice, create_invoice, simulate_payment, etc.

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 clearly scopes usage to unpaid invoices and adds an explicit interaction rule: 'Ask the user to confirm first.' No alternatives are needed here since no sibling performs cancellation, so the absence of an explicit alternative is not a real gap; what is missing is guidance for the paid-invoice case.

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?

Adds real behavior beyond the annotations: it discloses what the call returns (a payment_url), that the exchange rate is locked at creation in USD mode, the 10 USD floor, and that reusing order_id returns the existing invoice rather than creating a duplicate. This usefully qualifies the flat idempotentHint=false annotation by explaining conditional idempotency; the slight tension is reconcilable rather than contradictory. Not disclosed: rate-limit/auth needs or invoice expiry default behavior beyond the schema's own note.

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: purpose/return first, then the mode selection rule, then the constraint and idempotency tip. No filler and every clause carries information an agent needs before calling.

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 9-parameter mutation with no output schema, the description covers the essentials: what is created, what comes back (payment_url), how the two pricing modes differ, the minimum amount, and idempotency via order_id. The remaining parameters are fully described in the schema, so nothing critical is missing, though a note on expiry semantics would close the last 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 coverage is 100% and the schema already documents each field, so baseline is 3. The description adds the mutually exclusive either/or relationship between price_usd and token+amount and the 10 USD minimum, which the schema does not state, but leaves tokens, success_url, metadata, and expires_in_minutes entirely to the schema.

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 payment request') and immediately names the concrete artifact produced ('hosted payment page (payment_url)'). This is clearly distinguishable from the read/cancel siblings (get_invoice, list_invoices, cancel_invoice) 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 between the two pricing modes: 'Either price_usd (customer picks TRX or USDT, rate locked) or token + amount (fixed coin amount)', and gives a business constraint (minimum 10 USD) plus the order_id idempotency/find-later pattern. It stops short of naming sibling alternatives (e.g. use get_invoice/find_invoice_by_order to retrieve instead of re-creating), so it is clear context without full exclusion guidance.

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?

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond 'look up': it does not say what happens when no invoice exists (error vs empty result), whether it returns the most recent invoice, or whether the caller's own orders are the only ones accessible — all of which matter for a lookup by an externally supplied id.

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 tight sentence with the resource and the key discriminator (order id) front-loaded. There is no filler, though it stops short of the length that would let it cover usage or behavior.

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 one-parameter read tool with an output schema absent and safety hints already present, the description is minimally viable. It is still missing the return shape (what fields a found invoice carries) and the not-found behavior, which are the main things an agent needs to call and interpret this 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 0% for the single order_id parameter, so the schema gives no semantics beyond type and length bounds. The description partially compensates by clarifying that the id is an order id belonging to the caller ('one of your order ids'), which is genuinely useful. However, it does not state format, whether invoice ids are accepted, or what an invalid id does.

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: 'Look up the invoice' scoped to 'one of your order ids'. That distinguishes it from get_invoice (which presumably looks up by invoice id) and list_invoices, though the sibling differentiation is implicit rather than stated outright.

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 phrase 'for one of your order ids' implies the use case, but there is no explicit when-to-use guidance. Nothing tells the agent when to prefer this tool over get_invoice or list_invoices, or what to do when multiple invoices might exist for an order. No exclusions or prerequisites are mentioned.

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?

Annotations cover safety (readOnlyHint=true) and openWorldHint, so the bar is lower, yet the description still adds meaningful content: it enumerates the possible invoice statuses and the data returned (amounts, payments, payment_url), which is valuable given there is no output schema. It omits error behavior for missing ids and any 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 compact sentence-fragment with the core content front-loaded and no filler. It is efficient but so terse that it reads as a field list rather than a full statement of behavior.

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 full schema coverage and no output schema, the description supplies the return-value summary (statuses, amounts, payments, payment_url), which is exactly the gap the missing output schema leaves. Missing only edge-case behavior such as not-found handling.

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 'id' is already documented as 'Invoice id', so the description adds no syntax or format detail beyond it. Baseline 3 applies when the schema does the heavy lifting for a one-parameter tool.

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 the resource precisely ('Status and details of one invoice') and scopes it to a single record, which distinguishes it from list_invoices and find_invoice_by_order. It never uses an explicit retrieval verb and never names a sibling, so differentiation is implicit rather than stated.

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 'one invoice' plus the required id, suggesting it is the lookup-by-id path. No explicit when-to-use, no mention of how it relates to find_invoice_by_order or list_invoices, and no preconditions such as needing an existing invoice id.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-data behavior are covered. The description adds that rates are 'current' and limited to USDT/TRX, but it does not disclose freshness, caching, or failure behavior for live rate retrieval.

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 compact sentence that front-loads the resource and scope. Every phrase adds information about the returned values and their invoice 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?

For a zero-parameter read-only tool with no output schema, the description is nearly complete: it states the asset coverage and pricing basis. It could mention return format or freshness, but those are minor gaps given the tool's simplicity and existing annotations.

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 has zero parameters, so the baseline is 4. The description correctly avoids implying any inputs and reinforces which assets are covered, which is useful but not strictly necessary for invocation.

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 ('current USD prices of the supported coins') and names the exact coins covered (USDT and TRX). It also distinguishes itself from the invoice-oriented siblings by clarifying the pricing context used for USD-priced invoices.

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 implies usage for USD pricing and invoice contexts, but it does not explicitly say when to call this versus the invoice-focused sibling tools or whether it should be used before creating/reading invoices. The context is helpful but leaves selection guidance mostly inferred.

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?

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful behavior — newest-first ordering and cursor-style pagination keyed on created_at — but omits the default page size, the 100 cap, and whether results are a live window or a full history.

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, no filler, with the ordering and scoping facts front-loaded before the paging instruction.

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 and no explanation of what an invoice record contains or what happens when no filters are supplied, the agent must guess the default result size and the response shape. The ordering and pagination story is solid, but the return-side and default behavior gaps keep it at adequate.

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 only 33% (only `before` is documented), so the description must compensate. It does: it clarifies that `before` is the created_at of the last item (cursor semantics, not a generic date bound) and that `status` is a filter, which is real added meaning. The `limit` parameter is left unexplained.

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 the resource (invoices) and the ordering (newest first), which distinguishes it from get_invoice (single) and find_invoice_by_order. However, 'Recent' is unscoped — it doesn't say whether this is an unbounded list or a windowed set — and no sibling is named 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?

The description implies usage by explaining the filter and paging mechanics, but never says when to pick this over find_invoice_by_order or get_invoice. An agent can infer it is the browse/list path, but the routing guidance is left implicit.

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?

Beyond the annotations, it discloses that the tool fires the same webhooks as real payments, which is an important side effect. It also clarifies the test-key restriction and the available simulated outcomes, adding meaningful behavioral context.

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 compact sentences, front-loaded with the key test-mode constraint and followed by the webhook behavior. There is no wasted text.

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?

It covers the test-mode scope, outcomes, and webhook side effect well, and annotations already communicate the safety profile. The main remaining gap is that the required 'id' parameter is never explained, which could matter for correct invocation.

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 description maps the outcome choices into natural language, such as 'paid part' and 'let the invoice expire', which helps interpret the enum. However, with only 33% schema description coverage, it does not clarify the required 'id' parameter, so the parameter semantics remain partially incomplete.

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 action, simulating payment outcomes, and clearly frames it as test-mode invoice payment behavior. It distinguishes itself from real payment and from the invoice-management siblings through 'Test keys only' and the simulated outcomes.

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?

'Test keys only' gives a clear usage constraint and effectively excludes live-mode use. It does not explicitly name alternatives or when-not scenarios, but for this test-only tool the context is sufficiently clear.

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