TgPay Merchant API

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

Annotations already indicate this is not read-only and not destructive, and the description adds valuable nuance: it stops new signups but does not interrupt live subscriptions. This clarifies the actual behavioral effect beyond the annotation flags.

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 sentence, front-loaded with the key action, and the parenthetical adds critical behavioral detail without waste. Every word 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?

For a single-required-parameter tool with clear annotations and a fully documented schema, the description provides enough context to select and invoke the tool correctly. No output schema is present, but the operation's outcome is sufficiently described.

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 schema already fully documents plan_id as 'The plan to archive' with 100% coverage, so the description adds no new parameter-level detail. 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 ('Stop') and a specific resource ('new signups for a plan'), immediately distinguishing it from cancellation or deletion. The parenthetical clarifies that existing live subscriptions are unaffected, which is a meaningful scope distinction from siblings like cancelSubscription.

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

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

The description clearly implies when to use it: when you want to halt new signups while preserving ongoing renewals. It does not explicitly name sibling tools or exclusions, but the contrast with cancelSubscription is strongly 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 mark this as destructive, and the description adds a useful behavioral nuance: paid time continues until it runs out. This goes beyond the annotation by explaining the post-cancellation outcome.

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 conveys the action and its consequence. Every word earns its place, and the parenthetical adds necessary context without bloat.

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

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

For a single-parameter destructive action with no output schema and annotations covering the destructive hint, the description is complete. An agent knows what the tool does, what to pass, and what will happen after calling it.

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

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

Schema coverage is 100% and the sole parameter subscription_id is described as 'The subscription.' The description adds no extra meaning beyond the schema, so the baseline of 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?

Description uses a specific verb ('Stop future charges') and resource ('one subscription'), distinguishing cancellation from siblings like archiveSubscriptionPlan or getSubscriptions. The parenthetical clarifies the practical effect without ambiguity.

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

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

The description implies the use case: cancel a subscription to prevent future charges. However, it does not explicitly state when to choose this over alternatives, nor does it mention exclusions or conditions.

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 mark it as non-read-only and non-destructive. The description adds behavioral context beyond that: it creates a merchant-app request, returns a t.me link plus poll_secret, and requires human approval in a bot. This is valuable process-level disclosure not available from 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?

The description is compact yet information-dense: what it does, what it returns, how the human flow works, and when to use it. Every sentence earns its place, and the most important usage condition is 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?

With one simple parameter, no output schema, and annotations covering the safety profile, the description provides all necessary invocation context: input, return values, follow-up call, and usage condition. Nothing an agent needs to call this 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?

The single parameter app_name is fully described in the schema (100% coverage), so the schema carries the semantic weight. The description references the parameter only indirectly as 'Merchant app name' and adds no new format or constraint details. 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?

Starts with a specific verb 'Start token issuance', names the resource (merchant-app request), and explicitly contrasts with the 'Mini App UI' flow. It also distinguishes the follow-up tool connect_status, making its scope unambiguous among siblings.

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

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

Provides an explicit condition ('Use only when no API token is configured yet') and walks through the human-approval flow, ending with a pointer to connect_status. The agent knows exactly when to invoke this tool and what to do next.

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?

Discloses the critical one-time return of the token and the immediate handling requirement (save to .env, never log). It also explains the token's scope and limitations, which annotations alone do not convey. The description is consistent with readOnlyHint=false and destructiveHint=false because polling can consume the one-time token without being destructive.

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?

Each sentence earns its place: the core polling definition, the security-critical token handling, token scope, and polling cadence. It is front-loaded with the main operation and keeps warnings compact rather than duplicating structured fields.

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 tool with no output schema, it fully covers return states, the one-time token, storage/logging constraints, and polling interval. No essential calling information is missing; the 'from the connect tool' schema hint ties it to the required poll_secret.

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 only parameter, poll_secret, is fully documented in the schema ('The poll_secret from the connect tool'), so the baseline applies. The description adds context by identifying the request being polled but does not add extra parameter details beyond the schema.

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

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

States the specific action ('Poll a connect request') and the resource, and enumerates return variants (pending | denied | expired, or app id and API token). This clearly differentiates it from siblings like connect, which presumably creates the request, and from money-movement tools such as transfer/refundInvoice that use a different token.

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 instructs to poll every 3-5 seconds while pending, and frames the token's scope so an agent knows this path is for read/invoices/subscriptions/webhooks, not for moving money—transfers/refunds/checks require the primary token. This gives actionable when-to-use and when-not-to-use 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 signal this is neither read-only nor destructive, so the description does not need to restate mutation. It adds useful behavioral context beyond annotations: the invoice is one-off and the payer must open the returned mini_app_invoice_url. It does not mention webhooks or expiry, but the provided behavior is meaningful.

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?

The description is extremely compact and front-loads the action, then immediately gives the practical outcome the caller needs to know. The doc reference is a single short tail. Every part 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?

For a tool with 15 optional parameters and no output schema, the description only explains the creation action and the returned URL, then defers to documentation. It does not summarize the fiat/crypto modes, open-amount behavior, or which parameter combinations matter most. An agent could call it correctly but may under-specify an invoice without consulting the referenced docs.

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 schema covers 100% of the 15 parameters with individual descriptions, so the description need not repeat them. The tool description itself does not add param-level guidance, which is acceptable given the schema's complete coverage, but it also does nothing extra.

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

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

The description states a specific action and resource: "Create a one-off payment invoice". It also names the key output field, result.mini_app_invoice_url, which defines the tool's purpose. The "one-off" qualifier helps distinguish it from subscription-plan creation.

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 "one-off" wording implies a single-payment use case versus subscriptions, and the doc pointer offers an avenue for more detail. However, no alternative tool is named and no explicit when-to-use or when-not-to-use guidance is given, leaving the distinction from siblings like createCheck and createSubscriptionPlan implicit.

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

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

It discloses the consequential immutability of the plan and specifies the required follow-up action (send payers to result.mini_app_subscribe_url). Annotations already signal non-readonly and non-destructive intent, and the description adds behavioral value beyond them without contradiction.

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 conveys the core action. The follow-up instruction about mini_app_subscribe_url is essential, and the docs pointer is efficient. There is no fluff or repetition.

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 description covers the core action and the key follow-up field, but there is no output schema and it does not explain the full response shape, idempotency, or error behavior. It relies on an external doc reference for completeness, leaving gaps for an agent invoking the tool blind.

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 input schema documents all four parameters with 100% description coverage, so the description does not need to redefine them. It adds no extra parameter-level meaning such as defaults, dependencies, or formatting beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Create an IMMUTABLE recurring-billing plan.' The 'IMMUTABLE' qualifier is a key distinguishing trait that separates this from createCheck/createInvoice and signals a durable, non-editable resource.

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 clear context for when to use it: when creating a recurring-billing subscription plan, and it even tells the caller to send payers to result.mini_app_subscribe_url. It does not explicitly list alternative tools or exclusions, so it stops short of the top score.

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 mark this as destructive, and the description aligns by stating 'Delete'. It adds value by disclosing the refund side effect and the unclaimed precondition, going beyond what the annotation alone 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, front-loaded sentence with no filler. The verb, object, condition, and effect are all present and useful.

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 destructive operation with strong annotations and complete schema coverage, this description gives the essential constraint and side effect. It does not describe return values or error cases, but the low complexity means those are not critical 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?

The schema provides 100% coverage for check_id, already describing it as 'The check to delete.' The description reinforces the target state and side effect but does not add new parameter-level detail about format, constraints, or validation.

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

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

States the specific action ('Delete'), the resource ('an unclaimed check'), and a key effect ('refunds the hold'). The name and wording distinguish it from deleteInvoice, though it does not explicitly differentiate from a 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?

The qualifier 'unclaimed' implies the tool is intended for checks in that state, and the refund note clarifies what happens. However, it does not mention alternatives or when not to use this tool, so usage guidance is mostly 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 and readOnlyHint=false, so the destructive nature is covered. The description adds the 'unpaid' precondition, which is useful, but it does not disclose irreversibility, downstream effects, or required permissions beyond what annotations imply.

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?

The description is a single, front-loaded sentence with no wasted words. It conveys the essential action and condition efficiently.

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 tool with one parameter, strong schema coverage, and destructive annotations, the description is nearly complete. It clearly states the action and condition, though it could improve by explicitly routing paid invoices to a sibling like refundInvoice.

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 schema has 100% coverage for the single parameter invoice_id, so the description does not need to explain it. The 'unpaid' qualifier adds context but does not add parameter-specific semantic detail beyond the schema.

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

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

The description uses a specific verb ('Delete'), a clear resource ('invoice'), and a meaningful scope qualifier ('unpaid'). This distinguishes it from siblings like refundInvoice, which would apply to paid invoices.

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

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

The 'unpaid' qualifier implies when the tool should be used, and the sibling list suggests a contrast with refundInvoice. However, the description does not explicitly state when not to use it or name an alternative for paid invoices.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds meaningful behavioral context by specifying that balances are per asset and include both available and onhold amounts, which is not visible from the empty input 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 filler. Every phrase — merchant app, balance, per asset, available, onhold — adds useful 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 zero-parameter, read-only tool with safe annotations, this description is complete. It explains what is returned, how it is grouped, and what balance components are included, leaving no obvious gap an agent needs to call it 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?

There are zero parameters and schema description coverage is 100%, so the baseline is 4. The description correctly avoids inventing parameter information and the balance scoping it provides is sufficient.

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 — merchant app balance — and the exact scoping: per asset, with available and onhold components. It clearly distinguishes this from sibling getter tools like getCurrencies, getTransfers, and getMe.

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 usage context is implied: call this tool when you need the merchant app's balance broken down by asset. However, it does not explicitly mention when not to use it or which alternative to prefer, though no direct balance-related sibling exists.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds no further behavioral details such as pagination defaults, result ordering, or how the filter parameters combine.

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?

The description is extremely concise and front-loaded, but the brevity borders on under-specification. It wastes no words, yet it omits all usage context and resource clarification.

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 five-parameter list operation with no output schema and an ambiguous resource name, a two-word description is insufficient. Sibling tools like getInvoices and getStats show the need for disambiguation, which this description does not 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 coverage is 100%, so the schema already documents all five parameters. The description adds no parameter-level meaning, but it does not need to since the schema carries that burden.

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 clear verb and resource ('List checks'), so an agent knows this is a read operation over check records. However, it provides no context about what a 'check' is and does not distinguish it from sibling list tools like getInvoices or getTransfers.

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 getChecks instead of alternatives, no mention of prerequisites, and no typical use cases. The agent is left to infer the tool's role from its 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 readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the output includes code/name/decimals for crypto and includes fiats, but it does not disclose return shape, ordering, completeness, or whether the data is live or static. With annotations carrying the safety burden, this is adequate but not rich.

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?

The description is a single, compact phrase that conveys exactly what the tool returns without filler. Every element—supported assets, code/name/decimals, and fiats—earns its place. It is appropriately minimal for a parameterless lookup tool.

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?

Given zero parameters and no output schema, the description provides enough information for an agent to call the tool and interpret the response at a high level. It mentions the fields included and that both crypto and fiat are covered. It could be more explicit about the response structure, but for such a simple read-only tool it is largely 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 tool has zero parameters, so the input schema covers 100% of the parameter surface trivially. There is nothing for the description to add about parameters. The zero-parameter baseline of 4 applies because no guidance is needed or could be provided.

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 name 'getCurrencies' combined with the description 'Supported crypto assets (code/name/decimals) and fiats' clearly identifies a read operation that returns a list of supported assets and currencies. It distinguishes itself from siblings like getExchangeRates or getBalance by content type, but lacks an explicit verb in the description, so it doesn't quite reach the full 'specific verb+resource' standard.

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 does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or sibling tools. However, the purpose is simple and self-evident: an agent would use this when it needs the list of supported crypto assets and fiats. This qualifies as implied usage rather than explicit 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 readOnlyHint=true and destructiveHint=false, and the description's 'Read' verb is consistent with a safe, non-mutating operation. The description adds topic context but no deeper behavioral detail such as response format, error behavior, or auth requirements; annotations carry the safety burden adequately.

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 with no waste. The primary purpose and the 'START HERE' guidance are front-loaded, and the topic list is compact and useful.

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 operation, the description is nearly complete: it states what the tool does, when to use it, and the valid values. It does not describe the return format, but for a documentation retrieval tool that is minor and largely inferable from 'Read a ... doc'.

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 the single required 'topic' parameter and its allowed values. The description's list of topics is helpful but largely repeats the schema, adding no significant new meaning beyond what the agent can already see.

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 action ('Read') and resource ('TgPay Merchant API integration doc'), then enumerates the exact topics available. The tool is immediately distinguishable from the operational sibling tools, which perform API actions rather than retrieving documentation.

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 clear context for when to use it ('START HERE before integrating'), which is a strong usage signal. It does not explicitly name alternatives or when-not-to-use cases, but the 'start here' instruction effectively orients the agent before it touches the operational sibling tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only that rates are current and for display, which is mildly useful context but does not disclose format, basis, or update 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 noun phrase conveys the core purpose with no filler. For a zero-parameter tool this is appropriately sized.

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, a read-only annotation, and a self-explanatory purpose, the description is largely complete. It could specify what the returned display rates look like or the reference currency, but such details are optional for this simple 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?

The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics to document. The baseline for parameterless tools is 4, and the description does not need 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?

The description identifies the resource as current asset↔fiat display rates and implies a fetch operation for exchange rates. It conveys scope but lacks an explicit verb and does not contrast with sibling getCurrencies.

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 over siblings such as getCurrencies or getBalance. The phrase 'current' weakly implies time-sensitive rate lookup, but there are no explicit use cases or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful ordering behavior 'newest first', but does not mention default pagination, filter interaction, or response characteristics. This is some value beyond annotations but not extensive.

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?

The description is a single, front-loaded sentence with no wasted words. The ordering detail earns its place by adding behavioral information.

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

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

For a simple list operation, the schema documents all optional filters and defaults, annotations cover the read-only safety profile, and the description provides ordering. It omits return-format details, but there is no output schema and the endpoint is uncomplicated enough that this is a minor gap.

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

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

Schema description coverage is 100%, so each of the six parameters is already documented. The description adds no parameter-specific meaning, 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?

The description uses a specific verb ('List') and a specific resource ('invoices') and adds an ordering detail ('newest first'), making the action unambiguous. It clearly distinguishes this from invoice-mutating siblings like createInvoice, deleteInvoice, and refundInvoice.

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

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

The description implies that this tool is for retrieving invoice lists, and the resource name makes the basic use case obvious. However, it provides no explicit guidance about when to prefer it over other listing tools or any exclusions/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=true and destructiveHint=false. The description adds the response contents (app id, name, webhook config, token scopes), which is useful context beyond the read-only flag. However, it does not mention error behavior for invalid/expired tokens or any rate-limit/auth requirements.

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

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

A single, front-loaded sentence that states the action and the exact fields involved. No filler or repetition; every word contributes to the agent's understanding.

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

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

For a no-parameter, read-only tool without an output schema, the description sufficiently covers purpose and response content. It could add the structure of the webhook config or scopes, but nothing essential is missing for invoking the tool 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?

The tool has zero parameters, so the input schema is empty. Per the baseline for zero-parameter tools, the description does not need to add parameter semantics, and there is nothing to compensate for.

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 ('Verify') and a clear resource ('the token'), then enumerates the returned/checked fields: app id, name, webhook config, token scopes. This makes its purpose unambiguous and distinguishes it from siblings like getBalance or getInvoices.

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

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

The description implies when to use it (to verify a token and inspect its scopes/config), but it does not explicitly state exclusions or alternatives such as connect or connect_status. It is minimally serviceable but leaves routing 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 indicate readOnlyHint=true and destructiveHint=false, which covers the safety profile. The description does not add behavioral specifics beyond that, such as what exactly the 'stats' include, whether results are aggregated, or any edge cases. It adds minimal value over the annotations, so a low score 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?

The description is a single sentence: 'App volume/count stats for a period.' It is concise, front-loaded with the core purpose, and contains no redundant words. This is an exemplary level of conciseness, matching the efficiency seen in high-scoring examples.

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?

Given only two parameters with clear schema descriptions, read-only annotations, and no output schema, the description is adequate but minimal. It conveys the tool's purpose and domain but does not elaborate on the exact return format or the nature of 'volume/count.' It's sufficient for basic selection but leaves some ambiguity about what the stats represent, so a 3 is appropriate.

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?

Both parameters (start_at and end_at) have clear descriptions in the schema, so schema coverage is 100%. The description mentions 'for a period' which aligns with the parameters, but it does not add syntax or format details beyond what the schema already provides. With high schema coverage, the baseline of 3 is justified.

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

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

The description states a specific verb and resource: 'App volume/count stats for a period.' It clearly indicates this tool retrieves aggregate statistics for an app over a time range. While it doesn't explicitly name sibling alternatives, none of the sibling tools are stats-related, so it distinguishes itself functionally. The purpose is clear and not a tautology.

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 provides no guidance on when to use this tool versus alternatives. It does not mention any conditions for invocation, prerequisites, or exclusions. Since there are no other stats tools among siblings, the context might be implied, but the description itself offers no explicit usage direction.

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 readOnlyHint and destructiveHint annotations already declare this as a safe read operation. The description adds no behavioral context beyond the annotation, such as what is returned, whether archived plans are included, or any pagination or ordering 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?

The description is a single, concise sentence with no filler or redundant information. It is appropriately front-loaded and every word 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?

Given the low complexity, zero parameters, and read-only annotations, a one-line description is mostly sufficient. However, without an output schema, the description does not clarify what details are returned or whether archived/inactive plans are included, leaving minor ambiguity.

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

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

The tool has zero parameters and 100% schema description coverage, so there are no parameter semantics that the description needs to clarify. The baseline of 4 applies because no parameters exist.

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 uses a specific verb ('List') and resource ('subscription plans'), making the core function immediately clear. It does not explicitly differentiate from sibling tools such as getSubscriptions or createSubscriptionPlan, so an agent must infer the distinction from the resource 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?

The description gives no guidance on when to use this tool versus alternatives, such as getSubscriptions for user-specific subscriptions or createSubscriptionPlan for creating plans. There is no mention of exclusions, prerequisites, or preferred context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context beyond confirming a list operation, which aligns with the annotations but does not enrich them (e.g., no mention of pagination, ordering, or response format). This is adequate but not exceptional.

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?

The description is a single, concise sentence that efficiently states the function. It is front-loaded with the core purpose and contains no filler. However, it could arguably be slightly more detailed without losing conciseness, hence not a perfect 5.

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?

Given the simplicity of the tool (three optional filters, no output schema, read-only), the description is minimally sufficient. However, it lacks details about the return structure or any behavioral nuances, which might matter for an agent deciding how to process results. It is borderline adequate, so a 3 is fair.

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% and each parameter has a clear description in the schema. The description adds no additional meaning beyond what the schema already provides. Following the baseline for high coverage, a score 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?

The description clearly states the action ('List') and the resource ('subscriptions (subscribers)'). It is unambiguous and uses a specific verb. It does not explicitly differentiate from sibling tools like getSubscriptionPlans, but there is no direct sibling for listing subscriptions, so the clarity is sufficient.

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 provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, limitations, or typical use cases. An agent would have to infer context from the tool name and parameters alone, which falls short of helpful usage 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 readOnlyHint=true and destructiveHint=false, so the tool's safety profile is known. The description adds the app→user scoping detail, which is useful, but it does not mention pagination behavior, ordering, or what the response contains. The added value beyond annotations is modest.

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?

The description is a single, front-loaded sentence with no wasted words. It communicates the core purpose immediately and does not repeat schema 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 read-only list tool with fully documented optional parameters and no required inputs, the description plus schema gives an agent enough to understand what the tool does and what it accepts. The lack of usage guidance and output-format details is a minor gap but not critical given the simplicity of the operation.

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%, meaning all five parameters are already documented in the input schema. The description adds no extra parameter-level semantics, so the baseline of 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?

The description states a specific verb ('List') and a resource ('app→user transfers'), making the tool's purpose immediately clear. The directionality 'app→user' helps distinguish it from sibling tools like transfer and transferBatch, which are write operations, and from other list tools like getChecks or getInvoices.

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 is given about when to use this tool versus alternatives. The description only says what it does, not when it should be selected, and no exclusions or sibling comparisons are provided.

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 flag the tool as destructive and not read-only. The description adds useful behavioral context by specifying the direction of money movement and that partial refunds accumulate up to the face amount. It does not mention idempotency or failure modes, but the spend_id schema already covers idempotency.

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?

The description is a single, compact sentence with no wasted words. The core purpose is front-loaded, and the clarifying parenthetical adds only high-value behavioral details.

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?

Given the detailed input schema and the destructive annotation, the description adequately covers the essential behavioral context. It does not describe the return value or error behavior, but no output schema exists and the main invocation requirements are documented.

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 fully documents all three parameters. The description adds no parameter-specific semantics beyond what the schema already states, which is acceptable per the baseline for high schema coverage.

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 ('Refund'), a clear resource ('a paid invoice'), and the monetary side effect ('moves money app→payer'). This clearly distinguishes it from sibling tools like deleteInvoice or createInvoice.

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

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

It clearly states the intended context: refunding a paid invoice, and it notes partial refund behavior. It does not explicitly name alternative tools or exclusion conditions, but the context is clear enough that an agent can infer when to invoke it.

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 indicate this is a mutating operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds meaningful context by specifying the required auth scope/token and directing the agent to the webhooks doc for event types and signature verification.

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 no filler. The first sentence front-loads the action and target fields; the second provides auth and documentation pointers efficiently.

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, fully-optional 3-parameter update tool, the description plus schema covers the essentials: accepted fields, auth requirements, clearing behavior, and a pointer to the webhooks doc. It does not explicitly state partial-update semantics or the return value, but those are minor given no output schema and full param schema 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 coverage is 100%, so the input schema already documents all three parameters. The description mostly restates what the schema says ('https', 'opt-in list') without adding meaningfully new parameter-level details, keeping it at the baseline.

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?

Description states a specific action ('Update') on a clear resource (app) and names exactly which fields are affected: name, webhook_url, and webhook_events. This leaves no ambiguity about what the tool does and sets it apart from the payment/subscription-focused sibling tools.

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 explicit prerequisites: the 'webhooks' scope on the connect-issued token, or the primary token. It does not name alternatives or exclusions, but the auth guidance is clear enough for an agent to know when it is permitted to call this tool.

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