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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false. The description adds value on top: it discloses the return value (the generated `code`) and an operational guardrail (confirm with the user). It stops short of explaining coupon lifetime or side effects beyond creation.

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 tight sentences, front-loaded with the core action and followed by the caution. Every clause carries information; nothing is wasted.

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 notes the returned `code`, and rich annotations cover the mutation/safety profile. It is largely complete for a create tool, though it omits parameter-level detail.

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 contributes nothing about the seven parameters. Schema coverage is 71% (below the 80% threshold), leaving `name` and `max_uses` undocumented in both schema and description, so the description fails to compensate for the 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 (create) and resource (discount coupon), plus two key facts: the coupon is active and the response returns its `code`. This clearly separates it from the get_coupon/list_coupons siblings, 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?

Adds a real usage rule ("Creates real data: confirm with the user first") that tells the agent to gate the call behind user confirmation. However, it gives no guidance on when to create vs. when to reuse or fetch an existing coupon, so usage is only partially covered.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond them: the operation creates real data and requires user confirmation, plus the practical fact that the returned `code` feeds invoices. It omits failure behavior (duplicate email/phone) 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?

Two sentences, zero waste, and the highest-value constraints – what it does, the returned code, and the confirmation requirement – are front-loaded.

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 mutation tool whose annotations already carry the safety profile and which has no output schema, the description covers purpose, the return value, and the confirmation prerequisite. It is only slightly incomplete in not addressing the 50% undocumented parameter surface or error cases.

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?

With 8 parameters at only 50% schema description coverage, the description must compensate but adds no input-field meaning at all; it only mentions the returned code. Half the fields (email, last_name, first_name, business_name) have no schema description and the description does nothing to fill that 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 and resource ('Save a new customer in the PayPing account') and distinguishes itself from the get/list_customer siblings by adding the returned `code` needed for invoices. An agent can tell exactly what this does 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?

Provides a concrete pre-call condition: 'Creates real data: confirm the details with the user before calling.' This is a clear when-to-use caveat, but it never names alternatives (e.g., payping_get_customer to check for an existing customer first) or exclusions, so it falls 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?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, so the mutation profile is known. The description adds genuinely new behavior: the invoice is created but NOT sent, and it demands user confirmation of customer/items/prices before execution. It stops short of explaining reversibility or what happens on retry (non-idempotent), which would be valuable given destructiveHint=true.

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 purpose and return values, then the routing rule, then the safety caveat — a sensible ordering in roughly three short sentences. The line break mid-sentence ("Not sent:\ncall payping_send_invoice") is slightly awkward but the content carries 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?

For a 5-parameter creation tool with no output schema, the description compensates by naming the return fields (code, payCode, url), stating the prerequisite, the non-send behavior, and the confirmation requirement. The remaining gap is the non-idempotent/destructive semantics — retry behavior and reversibility are not addressed.

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 60%, so some documentation is already present. The description reinforces the semantic gist (customer, items, prices) and implies customer_code must reference an existing customer, but adds no detail on the undocumented fields (title, notes, quantity, has_tax) beyond what the schema says. 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 ("Create an invoice for a saved customer") and names the exact artifacts returned (`code`, `payCode`, `url`). It also distinguishes itself from payping_send_invoice and payping_create_payment_link by clarifying that the invoice is not dispatched, so an agent can pick 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?

Gives an explicit when-to-use-elsewhere rule: "Not sent: call payping_send_invoice or share the url." It also states a precondition ("saved customer") and a pre-call confirmation requirement ("confirm customer, items and prices with the user before calling"), leaving nothing 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?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description nonetheless adds genuinely new behavioral facts: the link is *permanent*, it is *public*, it creates real data, and user confirmation is required before invocation – context the annotations cannot express.

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 sentences, zero filler. The effect and the return value come first, and the mutation warning sits second – correctly ordered so the agent reads capability before caution.

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 destructive, non-idempotent creation tool with no output schema, the description covers the essentials an agent needs: it warns about permanence, public exposure and confirmation. But it omits the meaning of the required `product_code`, any auth/permission requirements, and whether a created link can be revised or revoked.

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 67%, and the one parameter with no schema description is `product_code`, the only required one – the description never explains what it is, where it comes from, or its format. It also says nothing about `ask_address` or `redirect_url` behavior, so it 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?

States a specific verb and resource ('make a permanent public payment page for a product') and even discloses the return artifact (`url`, https://ppng.ir/d/...). This is clearly distinguishable from siblings like payping_create_invoice or payping_create_product, which create different objects.

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 gives one concrete invocation guardrail – 'confirm with the user before calling' – which is real usage guidance, but it offers no when-to-use/when-not criteria and never names an alternative (e.g. when to use create_invoice instead). Usage context is implied rather than spelled out.

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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is partly covered. The description adds real value on top: it flags that this writes production data, mandates user confirmation, and discloses the returned `code` field, which no structured field provides.

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 with no filler; the mutation-and-confirm warning is front-loaded alongside the purpose rather than buried, and every clause carries 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?

No output schema exists, but the description names the returned identifier, and it covers the creation/confirmation flow for a 6-param write tool. Missing only secondary details such as currency handling for amount_toman versus amount_set_by_payer, which the schema partially covers.

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 67%, with most optional params (has_tax, quantity, amount_set_by_payer) already documented in the schema. The description only alludes to 'title and price', adding no syntax or constraint detail beyond what the schema supplies, 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+resource ('Create a product') plus a clarifying parenthetical ('financial item') and the return value ('return its `code`'). This cleanly separates it from the read-side siblings (payping_list_products, payping_get_product) and the follow-on payping_create_payment_link.

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 a clear workflow cue ('Then payping_create_payment_link makes a public payment page for it') and a hard precondition ('confirm title and price with the user before calling'). It stops short of naming when not to use it (e.g. versus create_invoice), but the routing for the common path is 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new context — the unit is Toman and the balance excludes already-withdrawn funds — but says nothing about auth requirements, freshness/caching, or multi-wallet behavior despite openWorldHint=true.

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 resource and immediately qualifies it. No filler, no redundancy with the title.

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 parameters, no output schema, and annotations covering the safety profile, very little is required from the description. The currency and balance definition are sufficient to call and interpret it, though an agent gets no hint about the response shape or what an empty/zero balance looks like.

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 is 4 and the description correctly avoids inventing any. The unit (Toman) is the only semantic detail relevant to interpreting the result, and it is supplied.

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 (PayPing wallet balance) and pins down its scope with the parenthetical 'money received and not yet withdrawn', which separates it from the sibling withdrawal tools. It does not, however, name or contrast with an actual sibling by name, so it stops short of a 5.

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 statement of when to call this versus payping_get_withdrawal or payping_list_transactions, and no prerequisites (e.g., authentication, token type) are mentioned. Usage is only implied by the resource name.

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, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds genuine value by disclosing the returned data (amount, expiry, max uses, buyer count and total spend), which no output schema provides. It stops short of error behavior (e.g. unknown code) or 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 dense sentence, front-loaded with the resource and lookup key, then the return fields. Every clause earns its place, though the field list is a touch listy rather than explanatory.

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 lookup with an output-free schema, the description covers what an agent needs: the resource, the lookup key, and the shape of the return. It omits only edge-case behavior such as missing/invalid codes, which is a minor gap for a read-only 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 coverage is 0% and there is no description on the 'code' property, so the description must carry the burden. 'One coupon by code' implicitly informs the agent that the sole parameter is a coupon code identifier, but it adds no format, case-sensitivity, or length guidance beyond that.

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 and scope: 'One coupon by code', which cleanly implies a single-item retrieval and implicitly contrasts with payping_list_coupons. It also enumerates the returned fields, so an agent knows exactly what it gets. The only gap is that it never names the sibling alternative, but the resource+cardinality is unambiguous.

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 gives no when-to-use guidance, no when-not-to-use, and does not point to payping_list_coupons or payping_create_coupon as alternatives. The 'by code' phrasing weakly implies the lookup key, but there is no explicit context for choosing this tool over its siblings.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description contributes the returned field set, which is genuinely useful, but says nothing about auth requirements, error behavior for unknown codes, 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?

A single short sentence, front-loaded with the scoping constraint and followed by the returned fields. Nothing is wasted; the only slight weakness is that the field enumeration is comma-heavy rather than structured.

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 reasonably compensates by listing the returned fields. Annotations carry the safety and world-access profile. For a one-parameter read tool this is close to complete, missing only auth/error 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?

Only one parameter exists and schema description coverage is 0%, so the schema gives no meaning for 'code'. The description's 'by code' clarifies that the input identifies a single customer, but adds no format, source, or example beyond that minimal hint.

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 and scope: 'One customer by code', immediately distinguishing it from payping_list_customers and payping_create_customer. It also enumerates the returned fields (name, contact details, address, national id, memo). The retrieval verb is implied rather than stated, so it falls just short of the top tier.

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?

'By code' implies this is the single-record lookup versus the sibling list tool, so the usage is inferable. However, there is no explicit when-to-use statement, no exclusion of alternatives, and no mention of prerequisites such as authentication or obtaining a valid code.

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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real value beyond that by disclosing the response contents (items, customer, status, payment code) and clarifying what `url` means, which matters since there is no output schema.

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 no waste: the core action leads and the returned fields follow. Every clause earns its place 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 read-only single-invoice getter with annotations covering safety and the description covering the returned fields, an agent has enough to call it correctly. The only minor gap is the absence of any hint at error behavior for a missing/invalid code.

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 single `code` parameter has 0% schema description coverage, but the description anchors it ('by code'), and the parameter is self-evident for a get-by-identifier tool. More detail on code format would help, but the semantics are adequately conveyed.

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?

'One invoice by code' is a specific verb+resource statement that clearly identifies a single-record fetch rather than a list. It sits opposite list_invoices and create/send_invoice, though it doesn't name those siblings explicitly, so differentiation is implied 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 only implied: 'by code' suggests you call this when you already hold an invoice code, but the description never states when to prefer it over list_invoices or what happens if the code is unknown. No exclusions or alternatives are named.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that refund state and status_text are exposed, but says nothing about error behavior for a missing/invalid code or any 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?

Two sentences, front-loaded with the retrieval scope before the use case, and no filler. The middle field enumeration is a long run-on list but each item is informative.

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's field inventory (amount, dates, payer, card, fees, refund state, status) is the agent's only view of the return shape, and it supplies that adequately for a simple read-by-id tool. Only the missing-error/not-found behavior keeps it from being fully 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?

The single 'code' parameter has 0% schema description coverage; the description compensates by naming it a 'payment code,' which usefully disambiguates it from invoice or customer codes in this product family. It still omits format expectations (prefix, checksum, typical length) that would let an agent construct the value confidently.

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 (retrieve) and resource (one payment) scoped by payment code, and enumerates the returned fields (amount, dates, payer, card, fees, refund state, paymentStatus, status_text). That distinguishes it from siblings like list_transactions and get_invoice, though it never uses an explicit verb like 'Fetch' and slightly reads like a field list.

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?

'Use it to check whether a payment really succeeded' gives one concrete use case, which is more than a bare restatement. However, it names no alternatives or exclusions – an agent is not told whether to prefer this over list_transactions or how to handle an unknown code.

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 establish the full safety profile (readOnly=true, idempotent=true, destructive=false, openWorld=true), so the description's burden is light. It usefully discloses the return contents, which matters because there is no output schema, but adds nothing on auth, error behavior, or lookup failures.

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 core action ('One product by code') and then the returned fields. No wasted words, though the fragment style lacks the structure that would make the field list scannable.

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 single-item read on an annotated, zero-config tool, the definition is nearly sufficient: safety is covered by annotations and return contents are enumerated in lieu of an output schema. Only the parameter format and error handling for an unknown code are unaddressed.

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%, so the description must carry the meaning of 'code' — and it does, implying the parameter is a product code that selects a single product. It stops short of stating the code format or source, so it only partially compensates for the annotation-free parameter.

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 ('One product by code') and enumerates the fields returned (title, price, stock, etc.), so the agent knows exactly what it retrieves. It does not explicitly name or contrast with the sibling payping_list_products, though 'by code' implicitly distinguishes a single-item fetch from a list.

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 when-to-use guidance and no named alternative. The phrase 'by code' hints that a product code is required, but the description never says to prefer this over payping_list_products when a code is known, nor does it state any prerequisites.

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/idempotentHint/non-destructive, so safety is covered externally. The description adds value beyond that by disclosing the auth mechanism (PAYPING_TOKEN) and the intended pre-flight/validation role, though it says nothing about failure behavior when the token is invalid.

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, front-loaded with the resource and field list, then the usage hint. No filler, no repetition of the title.

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 compensates by listing the account fields returned, and a zero-parameter read tool needs little more. Auth source and intended use are both stated, so nothing required for correct invocation 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?

The tool takes zero parameters, which is explicitly the baseline-4 case. There are no parameters whose meaning could be clarified further.

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 ('Show') and resource ('the PayPing account behind PAYPING_TOKEN') and enumerates the returned fields (username, name, email, phone, verification flags). This distinguishes it cleanly from siblings like payping_get_balance or payping_get_customer without needing to name them.

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?

'Use first to confirm the token works' gives a concrete, actionable context for invocation. It does not name alternatives or state when this tool is not appropriate, so it stops short of the explicit when/when-not needed for 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?

Annotations already declare readOnly, idempotent and non-destructive, so safety is covered. The description adds real behavioral value an agent cannot get from annotations: the returned metrics (totals, count, daily averages) and the default trailing-30-day window when no dates are supplied.

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 tight sentences, front-loaded with what the tool returns and followed by the default-window behavior. Every clause 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?

For a read-only, idempotent summary with a rich annotation set and full parameter documentation, the description covers purpose, return fields and default range. It could be slightly more explicit about how the daily averages are computed or the aggregation boundary, but 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 coverage is 100% and both date parameters are documented with format. The description still adds meaning beyond the schema by clarifying that omitting the dates means the last 30 days, resolving the null defaults the schema leaves 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?

The description gives a specific verb+resource ('Sales totals for a period') and enumerates what is returned (total amount in Toman, transaction count, daily averages), so the agent knows exactly what this summarizes. It does not explicitly differentiate against siblings like payping_list_transactions, but no sibling offers a summary, so ambiguity is low.

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?

'Defaults to the last 30 days' implies the intended context of a periodic summary, but it never states when to prefer this over list_transactions for detail or get_balance for point-in-time figures. Usage is implied rather than guided.

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 readOnly, idempotent and non-destructive, so safety is covered. Because there is no output schema, the description's disclosure of the returned fields (amount, request/payout dates, IBAN, bank tracking number) and the 'Toman' currency unit is genuinely useful additional 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.

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

A single, front-loaded sentence that names the operation first and the returned fields second, with no filler. Appropriate size for a one-parameter read tool, though the telegraphic fragment style leaves little room for anything else.

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 read-by-id tool with no output schema and one opaque parameter, the description covers the resource and the returned fields adequately and annotations cover behavior. The main omission is not telling the agent where the required 'code' comes from.

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 0%: the single 'code' parameter is an undescribed string. The description adds only 'by code', clarifying it identifies the settlement, but gives no format, length or provenance for the identifier, so it only partially compensates for the documentation 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+resource: 'Detail of one settlement by code', and the singular framing implicitly contrasts with the sibling payping_list_withdrawals. It is very clear what it returns, though it never names an alternative explicitly to help an agent choose between the two.

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?

'by code' implies the tool is used once a settlement code is already known (e.g. from list_withdrawals), so usage is inferable. There is no explicit when-to-use/when-not-to-use guidance and no named alternative, leaving the list-vs-detail choice 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered without the description. The description adds a useful data-model detail (coupon type encoding 0=percent, 1=Toman) but says nothing about pagination behaviour or whether archived coupons appear by default.

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 no filler; the resource and its key fields come first. It is appropriately sized, though the parenthetical field list is a slight run-on.

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's enumeration of returned fields is genuinely useful. However, for a paged, searchable list tool it omits how paging/search behave and omits any hint about result volume, leaving the agent to reconstruct that from the schema 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 100%, so limit, offset, search, and include_archived are already fully documented in the schema and the baseline is 3. The description's 'type' detail refers to a returned field, not any input parameter, so it adds no parameter meaning.

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 clear verb+resource ('List discount coupons') and even enumerates the returned fields, which helps an agent know what data it gets. It does not, however, distinguish itself from the sibling payping_get_coupon (single-coupon fetch), so an agent choosing between list and get gets no explicit signal.

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 statement of when to use this tool, no mention of the singular payping_get_coupon alternative, and no indication that the listing can be paged or filtered. Usage must be inferred entirely from the name and schema.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful return-content context (the fields and total count), which is valuable because there is no output schema, but it does not explain pagination behavior, search semantics, or what 'total count' represents. This is a modest addition beyond annotations, consistent with a 3.

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 that packs the essential purpose and return content without any wasted words. It is appropriately sized for a simple list operation.

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 list tool with three optional parameters and no output schema, the description partially covers returns by naming fields and the total count. However, it omits pagination behavior (limit/offset) and how search interacts with the result set, leaving gaps that matter when no output schema exists.

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 limit, offset, and search are fully documented in the schema itself. The description mentions returned fields, not parameters, and adds no syntax or behavioral meaning beyond what the schema already provides. Baseline 3 is correct 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 (List) and resource (saved customers), and enumerates the fields returned plus the total count. It is clear what the tool does, but it does not explicitly differentiate itself from sibling tools like payping_get_customer (single customer) or payping_list_transactions, so it falls short of the sibling-differentiation bar for a 5.

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 gives no guidance on when to use this tool versus alternatives such as payping_get_customer for a single record, nor any prerequisites or context. Usage is only implied by the word 'List', which is not enough for 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the returned field set, but says nothing about pagination behavior, result ordering, or rate limits for a list operation.

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 dense sentence that front-loads the verb and then the payload; every token carries information. The status legend is parenthetical and compact rather than sprawling.

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 field list is the right thing to include and it is present. However, for a 5-parameter filtered list tool it omits any statement of filterability and paging semantics, so an agent cannot infer how to narrow 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 60%; limit/offset/search are documented in the schema, while status and customer_code are not. The description supplies the semantics of the status values (draft/awaiting payment/paid/overdue/cancelled), which partially compensates, but never explains that status, search or customer_code are usable filters.

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 clear verb+resource ('List invoices') and enumerates the fields the listing returns, so the agent knows exactly what it gets back. It does not differentiate from the sibling payping_get_invoice or explain how this list relates to payping_list_customers/transactions, so it stops short of a 5.

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 when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as payping_get_invoice for a single invoice. The status legend hints that statuses exist but never says the tool can be filtered by them.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered externally. The description adds useful domain context (the items are called 'financial items', prices are denominated in Toman, and items carry a payment link), but says nothing about ordering, pagination total counts, 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?

A single tight sentence with the core action front-loaded before the field enumeration; no filler. It is slightly compressed, packing the return-field list and the terminology alias into one clause, but every element earns its place.

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 partly compensates by naming the returned fields (code, title, price, stock, active, payment link), which is the main information gap for this tool. Paging mechanics and default exclusion of archived items are left to the schema, but nothing critical for a simple list call 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% – limit, offset, search and include_archived are all self-documented, including ranges and defaults. The description adds no parameter-level detail (e.g. what search matches against, or that archived items are excluded by default), 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?

Specific verb (list) plus resource (products), and it disambiguates the domain-specific PayPing term 'financial items' so an agent doesn't confuse products with transaction line items. It also enumerates the returned fields. The sibling payping_get_product (singular retrieval) is only implicitly contrasted via the 'list' verb, so it falls just short of 5.

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 when-to-use guidance: nothing says to reach for this instead of payping_get_product for a single item, nor when to set include_archived or use the search parameter. The description only describes payload contents, leaving routing entirely 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: results are newest-first, amounts are denominated in Toman, and the response includes a total count for the same filter. It does not mention auth requirements, rate limits, or pagination behavior, but the added return-shape context is real value.

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 sentences, both earning their place: the first front-loads what is returned and its ordering, the second handles sibling routing. No filler or repetition of schema content.

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 carries the return-shape burden and does so by enumerating the fields and the total count, which is the key information for a list tool. It omits pagination semantics (limit/offset interaction, maximums) that an agent would want when iterating over large result sets, and mentions nothing about the newest-first ordering interacting with date filters.

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 explains kind (received/paid), limit range, offset paging, and the UTC YYYY-MM-DD date bounds. The description adds only the incidental "Toman" unit and "same filter" framing for the total count, 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 ("List payments") and immediately defines the returned shape: amount in Toman, payer, description, isPaid, payment code, plus total count. It also distinguishes itself from the sibling payping_get_payment, which is the closest lookalike in the toolset.

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 routing guidance: use this tool to enumerate payments, and switch to payping_get_payment with a code when full detail is needed. It does not state when-not to use it (e.g. versus payping_list_withdrawals or payping_get_sales_summary for aggregation), so it stops short of the full when/when-not/alternatives bar.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered without the description. The description does add useful domain context (amount is in Toman, includes a paid-out flag and total count), but says nothing about ordering, paging behavior, 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?

A single front-loaded sentence that identifies the resource and then enumerates the salient return fields. No filler, no redundancy with the title.

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 names the returned fields (date, amount, code, paid status, total count), which is exactly what the agent needs to judge relevance. Only the absence of paging/ordering guidance and sibling routing keeps it short of full completeness.

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 limit and offset are already documented in the schema including defaults and ranges. The description adds no further parameter meaning, which is the expected baseline when the schema does the work.

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 ('List') and resource ('settlements (withdrawals to your bank account)'), and even disambiguates the domain term settlement with the common-language equivalent. It does not explicitly contrast itself with the sibling payping_get_withdrawal, but the list-vs-get distinction is inferable from the names.

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 use this tool versus payping_get_withdrawal or payping_list_transactions, and no mention of paging workflow despite limit/offset parameters. The agent must infer usage from the name alone.

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 readOnly=false, destructive=true, openWorld=true and idempotent=false, so the safety profile is covered. The description adds genuinely new context: the effect leaves the system as an outbound SMS/email to a human recipient, which explains the open-world/destructive hints and justifies the confirmation requirement.

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 tight sentences with zero filler: the action and channel first, then the operational caution. Nothing is repeated from the schema or annotations and nothing could be cut without losing 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 single-parameter mutation with no output schema, the description covers what happens and the key behavioral risk, and annotations cover idempotency and world-openness. The remaining gap is the meaning of the required 'code' argument, which is never clarified.

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?

One parameter ('code') with 0% schema description coverage, so the schema explains nothing and the description must compensate. The description only implies the code identifies the invoice; it never states the format, where the code comes from, or how to obtain it, leaving the sole required input under-specified.

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 (send) and resource (invoice) plus the delivery channels (SMS/email) and the service (PayPing). It is clearly distinguishable from reads like payping_get_invoice, though it never explicitly contrasts itself with payping_create_invoice, the nearest write 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?

Gives an explicit caution — 'Messages a real person: confirm with the user before calling' — which tells the agent this is a user-visible, irreversible-feeling action rather than a safe retrieval. It does not name alternative tools or state what to do if the invoice was already sent, so it stops short of full when/when-not guidance.

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