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 still adds value by spelling out that this creates real data, requires user confirmation, and returns a generated code -- context not present in 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?

Two sentences, zero filler, and the action plus its caution are front-loaded. Nothing repeats structure already encoded elsewhere.

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?

An output schema exists, so the return value need not be re-explained, and the description still highlights the returned code. The remaining gap is behavioral detail (e.g. whether the coupon is immediately live or how it interacts with product_codes), minor given the annotation coverage.

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 71%, and the schema already explains kind, amount, expires_on, coupon_code and product_codes. The description contributes nothing about any of the seven parameters, 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 ("Create an active discount coupon") plus a notable side effect (returns its `code`), which is far more than a tautology. It is distinguishable from the get/list coupon siblings, though it never names 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?

Provides one real usage instruction -- confirm with the user first -- which is the right kind of guidance for a mutation. But it offers no when-not conditions, no prerequisites (e.g. do the referenced products need to exist?), and no routing to alternatives.

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, openWorldHint=true, so the safety profile is covered. The description supplements this with the practical consequence ('Creates real data') and a required user-confirmation step, plus the returned `code` and why it matters. It doesn't cover failure modes, but the added context is real value 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?

Two tight sentences, front-loaded with what the tool produces, then the caution. No filler. Slightly terse on the parameters side, but efficient.

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?

A mutation tool with safety covered by annotations and an output schema that carries the return shape, so those gaps are acceptable. However, with 8 parameters at only 50% schema coverage and no description of required fields or business/national_id semantics, the definition is not complete 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?

Schema description coverage is 50% across 8 parameters, and the description says nothing about any of them – no mention of required first_name/last_name, the is_business legal-person distinction, or national_id formats. The half of parameters lacking schema descriptions are left undocumented in both places, so the description fails to compensate.

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 ('Save a new customer in the PayPing account') and adds the return payload ('return it with its code'). This clearly separates it from the sibling read tools (get_customer, list_customers) and the other create_* tools. It does not name a sibling explicitly, which is why it's a 4 rather than 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?

Gives one procedural instruction ('confirm the details with the user before calling') but no when-to-use vs when-not guidance and no alternatives named. Usage is only implied from the create semantics.

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, openWorldHint=true, idempotentHint=false and readOnlyHint=false. The description adds genuinely additive context beyond them: 'Creates real data: confirm customer, items and prices with the user before calling', which flags real-world side effects and a verification step. It stops short of discussing reversibility or whether duplicates can be created, so not a 5.

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

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

Three tight sentences with the core behavior and return value front-loaded, followed by the routing hint and the safety caution. No redundancy; 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?

An output schema exists, yet the description still usefully names the returned code/payCode/url. For a destructive, non-idempotent mutation it supplies the needed caution, so an agent can call it correctly. Only minor gaps (e.g., currency/tax implications, error cases) remain.

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%, and the description only implies the customer is 'saved' (customer_code) and lists return fields; it adds no meaning for items, notes, title or due_date beyond what the schema already documents. With the schema doing most of the lifting, 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) plus its scope: for a saved customer, returns code/payCode/url. It also explicitly distinguishes itself from payping_send_invoice by noting the invoice 'is not sent', so an agent can differentiate it from the sibling without opening either 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 alternative and the condition that selects it: 'It is not sent; use payping_send_invoice or share the url.' It also states a precondition for calling ('confirm customer, items and prices with the user'). Routing and prerequisites are both 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 declare destructiveHint=true and openWorldHint=true, but the description adds the crucial interpretation: this produces a *permanent public* page anyone can pay, and it creates real data requiring user confirmation. That is meaningful context beyond the flags, though it omits permanence/irreversibility details and any auth or rate-limit notes.

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, zero waste. The identity/return value is front-loaded and the confirmation caveat follows immediately, with a concrete example URL that anchors the concept.

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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description covers the key behavioral caveat but leaves the required `product_code` and the optional parameters unexplained, a minor gap for a 3-parameter mutation 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 67%: `ask_address` and `redirect_url` are documented in the schema, while `product_code` is undocumented. The description only implies the product input ('for a product') and adds nothing about the optional flags, so it does not compensate for the uncovered parameter. 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 ('make a permanent public payment page for a product') and commits to a concrete return value (the `url`). No sibling tool creates payment links, so the agent can distinguish this from the create_* and list_*/get_* family without opening 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?

Provides a real usage constraint ('confirm with the user before calling') because it creates real data, which is genuine guidance. However, it never states when this is the right tool versus alternatives or what preconditions (e.g. a valid product_code) are required; usage is only implied.

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, openWorldHint=true and non-idempotent, so the safety burden is partially carried. The description adds value beyond that by stating 'Creates real data' and demanding user confirmation of title and price before the call, which is actionable behavioral guidance not present in 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?

Two short sentences, front-loaded with the core action and return value, then the downstream tool reference and the safety caution. 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?

An output schema exists, so return-value explanation isn't required, yet the description still names the returned `code` to enable chaining. Combined with the confirmation guidance, it is nearly complete; it stops short of noting duplicate/non-idempotent behavior for repeated calls.

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 description only alludes to 'title and price', mapping loosely to the title and amount_toman fields. It adds no detail for the remaining parameters (has_tax, quantity, amount_set_by_payer, description), leaving the schema to do most of 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?

States a specific verb and resource ('Create a product') and clarifies the return value ('return its `code`'), which distinguishes it from read-side siblings like payping_get_product and payping_list_products. An agent knows immediately this is the write entry point for the product lifecycle.

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 the agent to the next step ('Then payping_create_payment_link makes a public payment page for it') and prescribes a confirmation workflow before invocation. It gives clear positive context but no explicit when-not-to-use guidance (e.g. duplicate handling).

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, covering the safety profile. The description confirms it is a read of current balance but adds nothing beyond the parenthetical definition—no mention of rate limits, currency conversion caveats, or freshness. With annotations doing heavy lifting, a 3 is appropriate.

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?

Single sentence, front-loaded with the core purpose, no wasted words. The parenthetical is concise and earns its place by defining the balance scope.

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 tool with a rich output schema and comprehensive annotations, the description is adequate. It states what the balance is and its currency (Toman). The only minor gap is lack of any freshness or scope caveats, but these are not critical given the structured data.

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?

Zero parameters, so baseline is 4. The description adds no parameter info, which is correct since there are none.

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 (get) and resource (wallet balance), and clarifies scope with a parenthetical definition of what the balance represents ('money received and not yet withdrawn'). Clearly distinguishable from siblings like payping_get_withdrawal or payping_list_transactions.

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?

No guidance on when to use this tool versus alternatives. It implies a read operation but doesn't state prerequisites, context, or exclusions relative to sibling tools like payping_get_sales_summary or payping_get_withdrawal.

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 only a partial inventory of returned fields, which the output schema already carries, and says nothing about behavior on an unknown code 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 dense sentence with the resource and lookup key front-loaded and zero filler. It is telegraphic rather than a complete sentence, but nothing in it 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?

For a one-required-parameter read tool with an output schema and full annotations, the essential selection information is present. The only real gap is what happens when the code does not match a coupon, which is minor for this tool shape.

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% for the single 'code' parameter, so the description must compensate. 'By code' does establish that the parameter is the coupon's lookup identifier, but it adds no format, length, or case-sensitivity guidance beyond what the schema's string type implies.

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 resource and lookup key ('One coupon by code'), making it distinguishable from payping_list_coupons without opening either schema. It never uses an explicit verb like 'retrieve', but the intent 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?

There is no when-to-use guidance, no routing to the sibling payping_list_coupons, and no prerequisites (e.g., a valid/known code, case sensitivity). Only the weakest implication exists that this is for looking up a coupon you already have a code for.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds that a lookup is keyed on a code and enumerates returned fields, but says nothing about authentication, what happens on an unknown code, or error behavior.

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 fragment with no filler; the key constraint (lookup by code) comes first. Slightly under-specified rather than padded, which is the better failure mode here.

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?

An output schema exists, so the returned-field enumeration is redundant and the description need not explain returns. For a one-parameter read tool with full annotation coverage that is close to sufficient, but the absence of any routing to payping_list_customers leaves a real 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 0%, so the description carries the burden for the single 'code' parameter. 'By code' establishes that the parameter is the customer identifier rather than, say, a name or phone number, but adds no format, source, or length guidance beyond the schema's constraints.

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 resource (customer) and the retrieval key (code), and 'One customer by code' implicitly contrasts with the sibling payping_list_customers by signalling a single-record fetch. It does not name that sibling explicitly, so an agent must infer the single-vs-list distinction.

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?

No when-to-use statement, no prerequisites, and no mention of payping_list_customers as the alternative for enumerating customers. The phrase 'by code' is the only hint about when this tool applies, which is implied rather than stated.

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. The description adds only a content summary of the response and the meaning of `url` as the customer-facing payment page, which is modest added value for a read tool.

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 tail listing return fields is slightly redundant given the output schema exists, but the description remains tight and readable.

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 a full output schema and complete annotations, the description covers purpose and the notable `url` field adequately. The only real gap is routing guidance versus payping_list_invoices and the origin/format of the code value.

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 `code` parameter, so the description must compensate. It does state the lookup is 'by code', identifying the parameter as an invoice code, but adds no format, source, or example of where that code comes from.

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 'one invoice by code', and enumerates what the record contains (items, customer, status, payment code, url). The singular 'one invoice' implicitly separates it from payping_list_invoices, though 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?

There is no explicit when-to-use or when-not-to-use statement, and no alternative tool is named. The phrase 'by code' implies a single-record lookup, but the agent is left to infer that payping_list_invoices is the alternative for browsing.

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 and destructiveHint=false, so the safety and repeat-call profile is fully covered without description help. The description's additional detail (refund state, plain-English status_text) is essentially a preview of the return payload, which the output schema already supplies, and it says nothing about error behavior for an 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?

Two sentences, front-loaded with the resource and lookup key, no filler. The field enumeration is slightly long but each listed field tells the agent what to expect in a verification flow, so it largely 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 an output schema present, the description is not obligated to explain return values, and it still identifies the key, the scope (one payment vs. lists), and the primary purpose. For a single-parameter read tool with full annotation coverage, nothing essential 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?

There is a single parameter, 'code', with 0% schema description coverage, so the schema provides no meaning on its own. The description compensates partially by making clear it is the *payment* code (not an invoice or withdrawal code), which is a real disambiguation, but it adds no format, length, or example detail.

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

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

The description names a specific verb+resource (retrieve full detail of one payment) and enumerates the returned fields, so the agent knows exactly what it fetches. It implicitly separates itself from the list_* siblings by scoping to 'one payment by its payment code', but never names an alternative sibling such as payping_get_invoice or payping_list_transactions.

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 concrete when-to-use case: 'Use it to check whether a payment really succeeded.' That is clear context for selecting the tool, but there are no exclusions and no routing guidance versus closely related lookups like payping_get_invoice or payping_get_withdrawal.

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, non-destructive, open-world behavior, so the safety profile is covered. The description adds only that the result includes fields like price in Toman, stock and tax, which is mild extra context; it says nothing about auth needs, error behavior for a missing code, 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 clause with zero filler; the key scoping fact ('by code') comes first. It is terse to the point of missing context, but nothing in it 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?

An output schema exists, so the enumerated fields are redundant rather than necessary, and for a single-parameter read-only tool the description is adequate. It nonetheless leaves usage context and error/missing-product behavior 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?

Schema description coverage is 0% for the single 'code' parameter, so the description carries some burden. 'One product by code' establishes that code identifies the product, but adds no format, source, or constraints (schema only gives maxLength 100) 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?

The description states a specific resource (one product) and the lookup key (by code), and the listed fields make the intent unambiguous. It does not explicitly name payping_list_products as the alternative, but 'One product by code' implicitly contrasts with the list 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?

No explicit when-to-use guidance, prerequisites, or alternatives are given. The reader can infer it is for fetching a single known product, but nothing routes the agent between this and payping_list_products or payping_create_product.

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, openWorld and non-destructive, so safety is covered. The description adds real value beyond that: it identifies the exact fields exposed and positions the call as a token-validity probe, which is behavior the annotations don't convey. It omits any note on auth failure behavior or rate limits, keeping it short of a 5.

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

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

Two short sentences, zero filler. The scope (what is shown) comes first and the usage guidance ('Use first...') is a tight, front-loaded follow-up.

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?

A no-parameter read tool with an output schema, so return-value documentation is unnecessary. The description covers what is returned, why it matters, and when to call it — nothing an agent needs 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, so the baseline is 4. There are no arguments whose semantics the description could clarify, and it correctly introduces none.

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 ('Show') plus resource ('the PayPing account behind PAYPING_TOKEN') and an explicit enumeration of returned fields (username, name, email, phone, verification flags). This distinguishes it from siblings like get_balance or list_transactions without the agent needing to open 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?

'Use first to confirm the token works' gives clear, actionable context for when to call it — as a prerequisite/health-check step. It stops short of naming an alternative tool or stating when not to use it, but the primary usage condition is unambiguous.

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 genuinely useful behavior beyond that: the reporting currency (Toman) and the effective default window when dates are omitted, which the schema alone does not resolve (it only shows null defaults).

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: the returned metrics are front-loaded, the default period follows. Zero filler and nothing redundant with 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?

For a read-only aggregate with an output schema covering return values, the description is nearly sufficient: it names the metrics, currency, and default range. The only gap is routing guidance versus sibling tools, which keeps it from a 5.

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 baseline is 3, but the description adds the null-omission behavior ('defaults to the last 30 days') that the schema's null defaults leave ambiguous, clarifying how from_date/to_date behave when unset.

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 (sales summary) and enumerates the concrete outputs: total amount in Toman, transaction count, daily averages. This distinguishes it from list-oriented siblings like payping_list_transactions, but it never explicitly names an alternative, so it falls 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?

The default window ('last 30 days') implies a typical usage context, but there is no explicit when-to-use or when-not-to-use guidance, nor any pointer to sibling aggregation tools such as payping_get_balance or payping_list_transactions.

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 structurally. The description adds the currency unit (Toman) for the amount, which is genuinely useful context, but enumerates return fields that the output schema already 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?

A single dense sentence with the resource and identifier front-loaded, followed by the useful field list. Nothing is wasted, though the return-field enumeration partly duplicates the 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?

For a single-parameter read tool with an output schema and full annotation coverage, the description supplies enough to call it correctly and sets expectations about the payload. The only real gap is not explaining where the 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?

There is one required parameter ('code') at 0% schema description coverage, and the description only tells us the code identifies a settlement ('by code'). It does not clarify the code's format, source, or whether it is the same identifier used by payping_list_withdrawals, so the compensation for the coverage gap is thin.

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 ('Detail of one settlement by code'), which cleanly separates it from the sibling payping_list_withdrawals. It stops short of naming that sibling, so the differentiation is inferable rather than explicit.

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 'by code' implies you need a known settlement code, which is a usable precondition, but there is no explicit statement of when to use this versus payping_list_withdrawals or what to do if the code is unknown. 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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the type-code semantics (0 = percent, 1 = Toman), which is genuine value beyond the annotations, but says nothing about paging behavior or result ordering.

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 enumerates the meaningful fields with zero filler. Nothing could be removed 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?

With an output schema present, the field enumeration is somewhat redundant, and the annotations already carry the read-only profile. The definition is adequate for a simple list call but adds little beyond what structured fields already provide.

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

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

Schema description coverage is 100% with all four parameters (limit, offset, search, include_archived) fully documented in the schema, including the 1-50 cap. The description adds no parameter detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('List discount coupons') and enumerates the returned fields, so the agent knows exactly what this yields. It distinguishes itself from the singular payping_get_coupon and payping_create_coupon siblings implicitly via 'list', but 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?

No when-to-use guidance and no mention of alternatives such as payping_get_coupon for a single coupon or payping_create_coupon for writes. The agent must infer usage from the verb 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that a total count is returned, which is mild extra context, but says nothing about 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 names the resource, the returned fields and the count with zero filler. 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?

An output schema exists, so return values need no elaboration, and the description notes the fields and total count. Given the simple 3-param read-only nature, it is largely complete, missing only usage routing.

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 with ranges and defaults. The description adds no syntax or semantic detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb (List) and resource (saved customers) and even enumerates the fields returned plus the total count. It is clearly distinguishable from the singular sibling payping_get_customer, though it never names that sibling 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?

There is no guidance on when to use this list tool versus payping_get_customer, payping_search, or filtering via the search parameter. 'Saved customers' hints at scope but no when/when-not conditions or alternatives are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the returned field set and a status-code legend (0 draft ... 4 cancelled), which is useful context, but it never explains filtering behavior, paging semantics, or that the numeric status legend does not match the string enum in the 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 that leads with the verb and resource, with no filler or redundant preamble. The inline status legend is slightly verbose but readable and earns its place as field semantics.

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?

An output schema exists, so return values need not be spelled out — yet the description's entire content is a return-field list. For a five-parameter filtered list tool, the description omits how to filter, how to page, and when to prefer it over payping_get_invoice or payping_list_transactions, leaving real gaps.

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

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

Schema description coverage is only 60%, and the description contributes zero parameter information — it never mentions limit, offset, search, status, or customer_code. It spends its budget on return fields instead, leaving the filtering interface under-documented relative to 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 ('List') and resource ('invoices') and enumerates the fields returned, so the agent knows this is a paginated collection read rather than a single-record fetch. It does not explicitly distinguish itself from siblings like payping_get_invoice or payping_list_transactions, but the list/get distinction is inferable from the name.

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?

No when-to-use statement, no named alternatives, and no mention that the tool supports filtering by status, customer_code, or search despite those params existing. The agent must infer usage entirely from the 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=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered without the description. The description adds the useful detail that prices are in Toman and that items carry a payment link, but says nothing about pagination semantics, whether archived items are excluded by default, 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 sentence with zero filler, front-loading the verb and resource before the field enumeration and the alias clarification. Nothing needs to be trimmed and nothing important is buried.

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?

An output schema exists, so the description is not obliged to explain return values, and annotations cover the safety profile. For a simple paginated list endpoint this is close to sufficient; the only mild gap is that it never routes the agent to get_product/create_product or explains the archived-item default, though the latter is implied by include_archived.

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/include_archived are already documented with defaults and bounds in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline of 3 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 (products) and even resolves PayPing's domain alias ('financial items'), so an agent knows exactly what this returns. The enumerated fields (code, title, price, stock, active, payment link) pin down scope further. Plural 'List' versus the singular sibling payping_get_product is unambiguous from the name alone.

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 prerequisites, and never mentions alternatives such as payping_get_product for a single item or payping_create_product for writes. Usage is only inferable from the tool name, which is the definition of minimal 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?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuine value beyond them: newest-first ordering, currency (Toman), the presence of a total count, and the exact field set returned. It stops short of mentioning pagination behavior or limits, which is a modest gap.

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, with the result-shape information front-loaded and the alternative deferred to the end. Every clause 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 an output schema present and annotations covering safety, the description needn't explain return values in depth, and its scope, ordering and alternative routing are adequate for correct invocation. Minor omissions (paging behavior, relation to the other list siblings) keep it from a 5.

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

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

Schema description coverage is 100%, so the schema already documents kind, limit, offset, from_date and to_date with formats and ranges. The description only alludes to 'the same filter' without adding syntax or defaults, so the baseline of 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 ('List payments'), immediately enumerates the returned fields (amount in Toman, payer, description, isPaid, payment code), and names sort order ('newest first') plus the total count. It also explicitly routes the agent to the sibling payping_get_payment for full detail, so it is distinguishable 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?

The second sentence gives a clear alternative and the condition that selects it ('Use payping_get_payment with a code for full detail'). It does not, however, state when to prefer this over the other list siblings (invoices, withdrawals, customers), so guidance is strong but not complete.

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 two useful bits beyond that: amounts are in Toman (a currency-unit detail absent from the schema) and a total count is returned alongside the page. It says nothing about pagination limits or ordering, so this is a modest rather than rich contribution.

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

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

One front-loaded sentence with the resource named first and the payload enumerated via a colon list; no filler, no restatement of the name or annotations.

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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile; the description nonetheless briefly characterizes the payload (which is helpful for a Toman-currency, status-bearing list). The only meaningful gap is the absence of routing guidance against the get_withdrawal / list_transactions siblings.

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 (1-50, default 20) and offset (paging) are fully documented in the schema. The description adds no parameter syntax or defaults of its own, 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 ('List') and resource ('settlements (withdrawals to your bank account)'), and disambiguates from the sibling list tools (transactions, invoices, customers) by naming the bank-account-settlement resource. It even enumerates the returned fields (date, amount, code, paid status), so an agent knows exactly what it gets.

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?

No when-to-use guidance, no prerequisites, and no reference to alternatives such as payping_get_withdrawal for a single withdrawal or payping_list_transactions for payment activity. The agent must infer routing 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 destructiveHint=true and openWorldHint=true, so the agent knows this has real-world, irreversible effects. The description adds the crucial detail that a human recipient is affected and user confirmation is needed, which is context annotations cannot express. It stops short of stating delivery failure 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?

Two short sentences, front-loaded with the action and outcome, then the confirmation warning. No wasted words.

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?

The output schema covers return values and annotations cover safety, and the description supplies the human-impact warning. However, the sole required parameter is completely undocumented anywhere, which is a significant gap for a tool the agent must invoke 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?

One parameter ('code') with 0% schema description coverage and no explanation in the description. The agent cannot tell whether this is an invoice ID, a customer code, or something else, which is a real gap for a required identifier.

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: sending an invoice to its customer via SMS/email from PayPing. This distinguishes it from read siblings (get_invoice, list_invoices) and from create_invoice, but does not explicitly name those alternatives.

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 an explicit safety condition: the message reaches a real person, so the agent should confirm with the user first. It does not name a sibling as an alternative, but the when-to-use framing is concrete.

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