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

No annotations are provided, so the description carries the full burden. It helpfully discloses the underlying mechanism (a read of the active asset list) which implies the call is non-mutating, but it says nothing about failure signaling, error behavior when the key is invalid, or whether any state changes as a side effect.

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

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

A single compact sentence with the action and mechanism front-loaded and zero filler. Nothing could be removed without losing meaning.

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 parameterless check, the description covers the what and how, but with no output schema it should also indicate what a successful vs. failed check looks like so the agent knows how to interpret the result. That return-value gap keeps it at minimum-viable rather than 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 takes zero parameters, so there is nothing to disambiguate; the baseline for a parameterless tool is 4. The description correctly implies no input is needed since the API key is already configured.

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 (بررسی می‌کند / checks) with a specific resource (the configured API key) and even names the mechanism (fetching the store's active asset list). It is clearly distinct from siblings such as create_store_api_key or revoke_store_api_key, though it does not name any 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?

Usage is only implied: an agent can infer this is a verification step after configuring a key, but there is no explicit 'use this when...' statement, no mention of when not to use it, and no pointer to alternatives like get_account or list_stores that also touch connection state.

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

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

With no annotations, the description carries the full disclosure burden. It usefully reveals that the status is fetched fresh from TheyPaid and that a PAID response is required before confirming, plus that expected asset/amount are cross-checked — but it omits what happens on mismatch, whether mismatches raise errors or return a flag, and what the tool returns.

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 action front-loaded and no filler; the confirmation rule follows immediately. Slight deduction because the middle sentence about confirmation and the last about comparison could be merged without loss.

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 3-parameter read tool with no annotations and no output schema, the description covers purpose and the PAID confirmation rule but not the return shape (status values beyond PAID, mismatch outcome) or error behavior. Adequate but with clear gaps an agent would hit on first 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 0%, so the description must compensate. It does explain the two optional parameters semantically: if expectedAssetId/expectedAmountInTether are supplied, they are compared against the invoice. However, it leaves the consequence of a failed comparison unspecified, and invoiceId is only implicitly covered by the tool's purpose.

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 first sentence states a concrete verb+resource: it re-reads invoice status from TheyPaid, and it adds the confirmation rule (only PAID counts). However, it never distinguishes itself from sibling tools like theypaid_get_invoice, theypaid_recheck_invoice, or theypaid_wait_for_payment, which an agent could easily confuse with this one.

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 a decision rule ('only declare the payment confirmed when the response is PAID'), which implies this is a verification call. But it offers no explicit guidance on when to choose this over recheck_invoice, get_invoice, or wait_for_payment, nor whether it should be polled repeatedly or called once.

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

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

With no annotations, the description carries the behavioral burden. It helpfully discloses that the code is not stored or returned in the response, but it does not explain authentication prerequisites, success/failure behavior, or what happens to the pending session after submission.

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 the core purpose front-loaded and no wasted wording. The second sentence adds a useful behavioral caveat rather than repeating the title or 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 one-parameter tool with no annotations and no output schema, the description covers purpose, basic timing, and one important response caveat. It still omits prerequisites, expected outcome, and error conditions, so it is adequate but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate for the single parameter. It adds that the code is the current six-digit login code, but does not elaborate beyond what the regex pattern already enforces.

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: sending the current six-digit code to complete a pending TheyPaid login. It is distinguishable from sibling tools like register_account or connect_account, though it does not explicitly contrast itself with 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?

It clearly indicates use during a pending TheyPaid login, which is a meaningful usage condition. It does not name exclusions or related alternatives, but the context is clear enough for an agent to know when this tool applies.

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

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

With no annotations, the description carries the full burden and does well: it discloses that credentials come from the server's secure environment, that passwords/tokens are neither accepted as input nor returned, and that 2FA is handled out-of-band. It omits what happens on failure, whether an existing session is superseded, and whether the call is idempotent/repeatable.

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

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

Three short sentences, front-loaded with what the tool does, followed by the security constraint and the 2FA handoff. Every sentence adds information an agent needs; nothing is padded.

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

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

For a no-parameter, no-output-schema login tool with no annotations, this covers the essentials: credential source, non-disclosure, and the 2FA split. Remaining gaps are the return signal (success vs. 2FA-required) and interaction with an existing session, which a sibling like theypaid_check_connection could clarify but the description does not.

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, which is the baseline-4 case. The description adds useful meaning by explaining why the schema is empty – credentials are pre-configured in the server environment rather than passed by the caller.

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 ('وارد حساب TheyPaid می‌شود' – logs into the TheyPaid account), and explicitly distinguishes itself from the two-factor sibling by saying the OTP step is completed separately. An agent can route to theypaid_complete_two_factor versus this tool 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?

Explicitly routes the 2FA case to a separate step, naming the condition (two-factor enabled) and the action (complete OTP separately). It stops short of stating that this must be called before store/wallet/payment operations or that it replaces an existing session, so usage context is clear but not exhaustive.

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

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

With no annotations, the description carries the full burden and does well: it discloses that this is a mutation gated on explicit user approval, and it warns that secrets (private key / recovery phrase) must never be supplied — a real safety-relevant trait the schema cannot express. It stops short of describing what happens to a previously connected wallet or any failure/limits.

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

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

Three short sentences, no filler, with the core action first and the safety warnings immediately after. Every sentence carries distinct 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 mutation tool with no annotations and no output schema, the description covers the critical decision factors (approval gate, secret-handling prohibition). It omits what the call returns and whether it overwrites an existing wallet binding, which is the main remaining gap.

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

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

Schema coverage is 0%, so the description must compensate. It explains publicValue (public address or xpub, never secrets), confirm (only true after user approval), and implies storeId via 'the selected store'. Only asset is left unexplained, but its 13-value enum of tickers is self-describing.

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+resource: validates a public address/xpub and connects it to the selected store. This implicitly separates it from theypaid_validate_wallet (validation only) and theypaid_update_wallet, though it never names those siblings 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?

It gives one concrete precondition — set confirm to true only after the user approves — and a prohibition on entering private keys or seed phrases. But it never says when to choose this over theypaid_validate_wallet or theypaid_update_wallet, or what to do about an existing wallet connection.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that this is a mutating operation, that it returns a real paymentLink, and that a timed-out request should be checked against invoice list/details before retrying, which is useful safety context. However, it omits permission/auth requirements, idempotency guarantees, and whether retries risk duplicate invoices.

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

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

Three sentences, front-loaded with purpose, followed by usage constraints and timeout guidance. Every sentence adds operational value with no filler.

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

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

For a mutation tool with no annotations, no output schema, six undocumented parameters, and no schema descriptions, the description is only partially complete. It covers purpose, explicit-request gating, assetId sourcing, and timeout recovery, but leaves most parameter semantics and auth/idempotency behavior unexplained.

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% across six parameters, so the description must compensate. It only explains where to get assetId and does not clarify the meaning or expected format of amountInTether, acceptToleranceInTether, requiredConfirmations, redirectUrl, or description.

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: it creates an invoice via TheyPaid Merchant API and returns its real paymentLink. It is clear what the tool does, but it does not explicitly differentiate itself from the sibling theypaid_create_payment_link, even though both appear related to payment links.

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 concrete usage conditions: execute only on explicit user request, and first obtain assetId from the store's active assets. It also provides a timeout recovery procedure. It does not name alternative tools or explain when to choose another sibling instead.

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

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

No annotations are provided, so the description carries the full burden and does a fair job: it discloses the return value (a real pay.theypaid.io link), a time-based side effect (the invoice expires after 30 minutes), and validity preconditions on the asset. It does not describe failure behavior, permission/auth requirements, or what happens when the required 'confirm' flag is absent.

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?

Four short sentences, front-loaded with purpose and return value, followed by constraints and the confirmation rule. Nothing is redundant, though the expiration note and the confirmation instruction could be ordered more tightly around the core action.

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

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

With no output schema and no annotations, the description does cover the return value and the 30-minute expiry, which are the essentials. But for a 5-parameter mutation with zero schema descriptions it should also clarify store resolution (storeId vs. the selected store from theypaid_select_store) and what a rejected 'confirm' looks like.

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

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

Schema description coverage is 0%, so the description must compensate. It explains amountInTether (a dollar-equivalent amount) and implicitly assetId (asset must be active and have a conversion rate), but leaves storeId, description, and confirm's const-true semantics undocumented beyond a general 'confirm with the user' remark.

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 ('creates an invoice via the store payment link path') and adds the distinguishing output ('returns the real pay.theypaid.io link'), so an agent knows exactly what the call produces. However, it never names or contrasts with the sibling theyypaid_create_invoice, so an agent cannot tell from this description alone which of the two invoice-creation paths to choose.

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 clear preconditions ('the asset must be active in the store and have a conversion rate') and an explicit usage instruction ('confirm the amount and asset with the user before executing'). What is missing is routing guidance against alternatives, particularly theypaid_create_invoice, which occupies similar territory.

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

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

With no annotations present, the description must carry the full behavioral load, and it does disclose two valuable traits: the secret stays inside the MCP process and only a masked value is returned. It omits other important behaviors for a mutation tool — whether the operation is idempotent, whether an existing key is replaced, what permissions/scope are granted, and what the masked value looks like.

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

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

Three short sentences with no filler, and the core purpose is front-loaded before the secret-handling caveat. Nothing is repeated from 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 credential-creating mutation with no annotations and no output schema, the description does well on secret handling and return shape. It falls short on parameter meaning (storeId, its optionality) and on lifecycle behavior, so an agent can call it but not fully predict the outcome.

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 storeId parameter, so the description must compensate, but it never mentions storeId or its UUID format. It is also silent on the notable fact that storeId is not required — presumably defaulting to the selected store — which is a behavior an agent needs to understand.

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+resource: creating a store-scoped Merchant API key in TheyPaid, and clarifies the return value is only a masked key. It implicitly contrasts with theypaid_revoke_store_api_key by establishing the create side, though it does not name 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?

The final sentence ('the key is used for invoice and payment tools in this session') implies when to use it, giving real context for provisioning. However, there is no explicit when-not guidance, no statement about whether creating a new key invalidates a prior one, and no mention of prerequisites such as being connected to the account.

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

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

With no annotations the description carries the full burden and does well: it discloses non-custodial/local storage, that the recovery phrase and private key are encrypted to a local file and never returned, and the required environment secret. The notable gap is what happens on a repeat call for an already-created asset — whether it overwrites or fails — which matters for a key-material-generating operation.

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

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

Front-loaded with purpose, then mechanics, then prerequisite, then next step — a sensible ordering with little waste. The inline enumeration of all thirteen assets duplicates the schema enum and costs length without adding much.

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 wallet-creation tool with no annotations and no output schema, the description covers prerequisites, key-handling behavior, and the follow-up call. It stops short of saying what a successful response actually contains (address/xpub/path), which an agent would want before reporting back to a user.

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%, so the description must compensate, and it does: it restates the enum values and, more importantly, explains that the asset choice determines the wallet derivation type. It does not however explain the catalog constraint precisely (must the asset already be enabled on the store?).

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 (creates a local non-custodial wallet) scoped to the TheyPaid store asset catalog, and enumerates the supported assets. It also distinguishes the two internal code paths (UTXO → extended public key, account-based → receive address), so an agent knows exactly what this call produces.

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

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

Gives a clear precondition (THEYPAID_WALLET_PASSWORD must be set in the MCP server environment) and an explicit follow-up routing to theypaid_connect_wallet for validation and store connection after user confirmation. It does not state when NOT to use it — e.g., behavior when a wallet already exists for that asset, or whether theypaid_update_wallet is the right sibling instead.

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

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

With no annotations at all, the description carries the full burden and does most of it well: it discloses that deletion is permanent and non-reversible, that the current store name must be confirmed exactly, and that a 2FA code may be required. It omits cascade effects (assets, API keys, invoices) and what happens on a name mismatch, which would matter for a destructive call.

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

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

Two sentences, both load-bearing, with the destructive nature and irreversibility front-loaded ahead of the preconditions. No filler or restatement of the title.

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

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

For a destructive tool with zero annotations and no output schema, the description covers the safety essentials but not the surrounding consequences: whether the store must be empty or inactive first, what happens to linked assets/API keys, or what is returned on success. Adequate for the core action, incomplete for a delete in a store with many related sibling operations.

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%, so the description must compensate and it does only partially: it clarifies that confirmStoreName must match the current name exactly (beyond the bare 1-100 char constraint) and that code is a 2FA code. It never mentions storeId, leaving one of three parameters completely undocumented, and 'sometimes' gives no rule for when code is required.

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 (deletes permanently) and resource (the store and its settings) in TheyPaid, which clearly separates it from update/setup/select siblings. It stops short of explicitly naming the softer alternative (theypaid_set_store_active), so differentiation is implied rather than stated.

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

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

The description implies when to use it by flagging that the action is irreversible and needs exact-name confirmation, and it mentions a conditional 2FA step. But it never tells the agent when NOT to use it or points at the deactivation alternative, so guidance remains inferred.

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

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

With no annotations present, the description carries the full burden and does well: it discloses that state is destroyed and, crucially, scopes the destruction to this MCP process's memory rather than server-side account data. It also gives the post-disconnect recovery procedure. It stops short of saying whether the operation is reversible or whether re-authentication is required.

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 destructive effect followed by the recovery instructions. Every clause carries information the agent needs; nothing is padding.

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

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

For a zero-parameter, no-output-schema, no-annotation mutation tool, the description covers what is destroyed, the blast radius (process memory only), and how to recover. The main remaining gap is whether server-side credentials or session tokens persist after this call.

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 there is no parameter semantics to convey; the baseline of 4 applies. The description correctly does not invent parameter discussion.

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 (clears/purges) and enumerates exactly what is affected: session, account info, the selected store, and API keys. That level of resource specificity is well beyond a bare 'disconnect', though it never explicitly contrasts itself with connect_account or register_account.

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 implies the recovery path (reconnect after MCP restart using configured credentials), which hints at when this tool is appropriate. But it never states the conditions under which an agent should call it versus leaving the session intact, nor does it name an alternative tool.

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

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

No annotations are provided, so the description carries the full behavioral burden. The verb 'reads' implies a safe read-only operation with no mutation, and the note about service credit versus wallet crypto adds useful domain context. However, it does not mention authentication/connection prerequisites beyond 'connected account', nor return shape or any 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?

The description is two sentences and front-loads the core purpose. The second sentence adds useful disambiguation about service credit versus wallet cryptocurrency, though it could be slightly tighter.

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 zero parameters and no output schema, the description does a reasonable job stating that stores and service credit balance are read. It stops short of describing the account-overview response structure or connection prerequisites, which leaves some contextual gaps for an agent invoking it cold.

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 parameter semantics to clarify, and the description appropriately focuses on what the operation returns rather than on nonexistent inputs.

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 ('reads') and names the resources: stores and service credit balance for the connected account. It also clarifies that service credit is distinct from the merchant wallet's cryptocurrency. It does not explicitly differentiate itself from siblings like theypaid_get_credit or theypaid_list_stores, which keeps it from a 5.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as theypaid_get_credit or theypaid_list_stores. The overview nature is implied by the title and by reading both stores and credit, but no exclusions or routing conditions are 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?

No annotations exist, so the description carries the full burden. It discloses the returned content (asset list plus each asset's current ID) but says nothing about read-only nature, authentication or store-scoping prerequisites, or whether IDs change over time beyond the word 'current'.

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 the return content front-loaded and the usage note second. No waste, though the first sentence's phrasing ('assets of the store settings list') is slightly awkward and could be more direct.

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 no output schema and no annotations, the description gives a partial return-value sketch but omits whether a store must be selected first and how the catalog differs from the supported-assets sibling, which is the most likely source of a wrong-tool call.

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 is nothing for the description to clarify, and it correctly implies a parameterless catalog fetch.

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?

A specific verb and resource: shows the store's configured assets and the current identifier of each. This is clearer than the name alone, but it never disambiguates from the sibling theypaid_get_supported_assets, which an agent could easily confuse it with.

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 tells the agent what to do with the returned IDs ('use them when connecting a wallet or creating an invoice'), which implies downstream context, but it gives no guidance on when to call this tool versus theypaid_get_supported_assets or whether a store must already be selected.

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

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

No annotations are provided, so the description must carry the full burden. It does signal that the operation is a read ('می‌خواند') and clarifies the semantics of the value (fee credit, not wallet crypto), but it omits auth/account prerequisites and says nothing about the shape of the returned balance (amount, currency, expiry).

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 what is read, followed by the one disambiguation that matters. No filler or restatement of the title.

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

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

For a no-parameter read with no output schema, the description covers what the value is and what it is not. A brief note on the returned fields (e.g., amount and currency) or on the auth requirement would close the remaining 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?

The tool takes zero parameters, so there are no argument semantics to explain; baseline 4 applies. Nothing in the description conflicts with the empty 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 states a specific verb (می‌خواند / reads) and a specific resource (the TheyPaid credit balance used for invoice processing fees). The second sentence rules out a plausible confusion with the crypto balance in the merchant's wallet, which meaningfully disambiguates it from wallet/asset 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?

Usage is implied — this is the way to check the fee credit balance — and the negative statement (not the wallet's crypto balance) hints at when it is not the right tool. However, no sibling is named explicitly, and it does not point to theypaid_topup_credit or theypaid_recheck_credit_topup as the follow-up when the balance is insufficient.

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

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

No annotations are provided, so the description carries the full behavioral burden. It signals a read ('می‌خواند') but never says whether the status is served from cache or freshly fetched from the provider — critical given a sibling named theyypaid_recheck_invoice — nor what happens when the invoice is missing or unauthorized, and no output schema documents the shape of the returned 'details and status'.

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

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

A single short sentence with the action and the keying mechanism front-loaded; nothing is redundant. It is efficient, though its brevity edges into under-specification rather than tight information design.

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 annotations, no output schema, and an undocumented parameter, this description leaves too much open for an agent working in a 32-tool surface dense with invoice-related siblings. At minimum it should clarify the read semantics versus recheck_invoice and check_payment.

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

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

Schema description coverage is 0%, so the description must compensate. It does establish that the single parameter is the invoice identifier, which is more than the bare schema says, but it adds no format, sourcing, or validity guidance (the pattern and length limits exist only in the schema).

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

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

States a specific verb and resource: it reads ('می‌خواند') the invoice details and current status from TheyPaid, keyed by ID. That is enough to separate it from mutation siblings like theyypaid_create_invoice or theyypaid_delete_store, but it does not explicitly distinguish itself from theyypaid_list_invoices, theyypaid_check_payment, or theyypaid_recheck_invoice.

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

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

The phrase 'with its ID' implies usage: call this when you already hold an invoice identifier. It never says when to prefer it over the closely related siblings (list_invoices for discovery, recheck_invoice for a forced provider refresh, wait_for_payment for polling), leaving a genuinely ambiguous choice to inference.

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

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

With zero annotations the description carries the full burden, and it does add one genuinely useful disclosure: the wallet address and derived public key are deliberately excluded from the response. However, it says nothing about required permissions, error behavior, or what the 'active assets' payload contains.

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, no filler, and the core purpose leads. The response caveat is appended in a natural second position, though the description is arguably under-specified rather than merely concise.

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 no annotations, no output schema, and an undocumented parameter, the description covers only the headline purpose plus one exclusion note. It leaves unresolved which store is returned and what the asset information actually comprises.

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

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

Schema coverage is 0% and the single storeId parameter is never mentioned in the description. Since storeId is optional (required=0), the agent cannot tell whether omitting it uses a previously selected store or fails — a critical ambiguity the schema does not resolve either.

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 concrete verb+resource: reads store settings and active-asset information. That is specific enough to separate it from mutation siblings like theypaid_update_store or theypaid_set_store_active, though it never explicitly contrasts with read siblings such as theypaid_list_stores or theypaid_get_account.

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 indication of when to call this versus the many sibling read tools, no prerequisites (auth, connection state), and no note on what happens when storeId is omitted even though it is optional. 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?

With no annotations, the description carries the full burden; it does disclose the key behavioral trait that only 'active' assets are returned and that the payload carries usable assetIds. It stays silent on permissions/auth requirements, what happens if no store is selected, and whether the list is paginated.

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 zero waste: the retrieval statement comes first and the actionable follow-up second. 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 no output schema and no annotations, the description should sketch the shape of the returned asset list (fields beyond assetId, ordering, whether wallet/network info is included). It only names assetId, leaving the return contract partially opaque for an agent that must then act on that 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The mention of the response's assetId adds useful context even though no input exists.

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: it lists the active assets of the currently selected store, which tells an agent exactly what it retrieves. It does not differentiate itself from the sibling theypaid_get_asset_catalog, so an agent cannot tell from the text alone which of the two to call.

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 clear downstream context: use the exact assetId from the response when creating an invoice, which routes the agent toward theypaid_create_invoice. It does not state prerequisites (a store must first be chosen via theypaid_select_store) nor when to prefer this over the asset catalog.

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

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

With no annotations at all, the description carries the full behavioral burden, yet it discloses only that pagination is offset/limit based — which the schema already shows. It says nothing about ordering, what happens when no store is configured, auth/credit requirements, or whether the listing covers all invoice states; for a read-only list tool the risk is low, but the disclosure is thin.

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

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

A single compact, front-loaded sentence with no filler; the resource comes first and the pagination mechanism follows. The terseness is under-specification rather than bloat, so it is efficient but not exemplary.

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

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

No output schema and no annotations, so the description should at least sketch the returned invoice shape, ordering, or the precondition that a store be selected. Instead an agent gets only the fact of pagination, leaving it unable to predict the result or failure modes before calling.

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

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

Schema description coverage is 0%, so the description must compensate. It names both parameters and classifies them as offset/limit pagination, which does add the meaningful signal that this is offset-based rather than cursor-based paging. It does not mention defaults (20/0) or the maximum of 100, and the schema itself already encodes those bounds and types, so the added value is limited.

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 ('فاکتورهای ... را ... فهرست می‌کند' = lists invoices) scoped to the configured store, which separates it from theypaid_get_invoice, create_invoice, check_payment and recheck_invoice. It does not explicitly name a sibling or say how it differs beyond the list/read distinction, so it falls short of 5.

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

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

Usage is only implied: the word 'تنظیم‌شده' (configured) hints that a store must already be selected, but that prerequisite is never stated. There is no guidance on when to use this versus theypaid_get_invoice or theypaid_check_payment, and no 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?

There are no annotations, so the description carries the full burden. It does add one genuinely useful behavioral fact: wallet address and public key are withheld from the response, which tells an agent it cannot rely on this tool to obtain them. However, it says nothing about ordering, empty results, or whether access is scoped to the current connection, so the read-only, zero-parameter profile is only partly explained.

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 with no filler: the purpose comes first, and the field-omission caveat comes second. Every sentence earns its place.

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

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

With no output schema, the description has to explain the return shape, and it only says what is excluded rather than what a store record contains. For a simple zero-parameter list that may be enough, but an agent cannot predict the response structure.

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 no parameters, which is the baseline-4 case. The description correctly adds no input guidance and does not fabricate filtering options.

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: 'فروشگاه‌های حساب متصل TheyPaid را فهرست می‌کند' (lists the stores of the connected TheyPaid account). The scope 'connected account' distinguishes it meaningfully from mutating or store-registration siblings such as theyypaid_setup_store and theyypaid_connect_account, though it never explicitly distinguishes it from theyypaid_get_store.

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 prerequisite that an account must already be connected, which gives some context for when this tool applies. It never names an alternative, such as single-store lookup via theyypaid_get_store, and gives no when-not-to-use guidance; usage is therefore left to inference from the title.

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

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

With no annotations, the description carries the full burden. It usefully discloses domain semantics—that only PAID status means confirmed payment and that credit is distinct from the acceptor wallet balance—and implies a remote re-check with possible state refresh. However, it does not state whether the recheck mutates state, what happens for non-PAID invoices, or any auth/rate-limit 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?

Two compact sentences with the action front-loaded and no filler. The second sentence adds a meaningful semantic caveat rather than padding, so the length is appropriate for the tool's complexity.

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 tool performs a recheck plus a balance read with no output schema, so the description should clarify what is returned and how results relate. It conveys the PAID status meaning but does not describe the response shape (invoice status plus credit balance) or failure behavior, leaving a moderate gap.

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

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

Schema coverage is 0% and the single invoiceId parameter is undocumented in the schema beyond structural constraints. The description only refers to 'account invoice', loosely tying to invoiceId, but gives no guidance on where the ID comes from or what form it takes, so it does not compensate for the coverage gap.

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

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

The description states a specific compound action: it asks TheyPaid to re-check the account invoice and then reads the service credit balance. The verb and resource are concrete, though the description says 'account invoice' rather than explicitly 'credit top-up invoice', so the distinction from the sibling theypaid_recheck_invoice must be inferred from the tool name/title.

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 statement of when to use this tool versus alternatives such as theypaid_recheck_invoice, theypaid_check_payment, or theypaid_get_credit, nor any when-not condition. Usage is only implied by the name and the mention of re-checking an invoice, leaving an agent to guess among several close siblings.

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

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

No annotations are provided, so the description carries the whole burden. 'اجرا' (execute/run) implies a server-side action beyond a pure read, but it does not say whether this mutates invoice state, whether it hits the payment provider, whether it costs credit or is rate-limited, or whether it is synchronous or long-running. The only behavioral disclosure is that it returns the 'latest recorded status'.

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 compact sentence with the action front-loaded and the return behavior appended — no filler. It is arguably too terse rather than bloated, but structurally it is sound.

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

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

There is no output schema and no annotations, so the description must cover both input sourcing and return shape; it only gestures at 'latest recorded status' without saying what that status contains or how it differs from a plain get. For a recheck operation with possible side effects, that leaves key questions unanswered.

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% and the single parameter invoiceId has only pattern/length constraints, with no explanation of where the ID comes from or what form it takes. The description never mentions invoiceId, so it adds nothing over the schema for the one required input.

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 (recheck / بررسی دوباره) on a specific resource (invoice / فاکتور) and adds that it returns the latest recorded status. It does not, however, distinguish itself from close siblings such as theypaid_get_invoice, theypaid_check_payment, or theypaid_wait_for_payment, so an agent still has to infer why it would recheck rather than simply fetch.

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 offers no when-to-use or when-not-to-use guidance and names no alternative. It never says whether to call this instead of theypaid_get_invoice when a status looks stale, nor whether it should follow theypaid_check_payment or theypaid_wait_for_payment — the choice is left entirely to the tool 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?

With no annotations, the description carries the full burden and delivers the least obvious behavioral fact: credentials come exclusively from the THEYPAID_ACCOUNT_EMAIL and THEYPAID_ACCOUNT_PASSWORD environment variables and must not be passed as input, which prevents a common misuse. It also discloses the two-step nature of registration (request, then email confirmation). It does not say what the call returns, what happens on duplicate registration, or whether the request is idempotent.

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

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

Three short sentences, front-loaded with the action, then the credential constraint, then the follow-up step. Every sentence contributes actionable information and none repeats the title.

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

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

For a zero-parameter, annotation-free tool with no output schema, the description covers the essentials: what it does, where secrets come from, and the required post-step. It stops short of describing the return value or failure modes, which matters more here because no output schema exists to fill that 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?

The tool takes zero parameters, so the baseline is 4. The description reinforces the empty schema by explicitly stating that credentials must not be sent in the tool input, which prevents an agent from inventing or passing arguments.

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 and resource — it registers an account-creation request in TheyPaid — and adds that the process finishes with an email confirmation. It is clear what the tool does, though it never explicitly contrasts itself with the sibling theypaid_connect_account, leaving the boundary between 'register' and 'connect' to inference.

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

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

Usage is only implied: an agent can infer this is the entry point for a new account and that a verification email must then be confirmed. There is no explicit statement of when to prefer this over theypaid_connect_account, nor what to do if an account already 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?

With no annotations, the description carries the full burden and does disclose the key traits: the removal is permanent, it may halt payment acceptance for that asset, user confirmation is required, and a two-step verification code may be needed. It does not say whether wallet settings are recoverable or what happens on failure, keeping it below 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 sentences, zero padding: the destructive scope is front-loaded, followed by the prerequisite/2FA caveat. 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?

For a destructive mutation with no annotations and no output schema, the description covers the main risks (irreversibility, confirmation, 2FA). It still leaves the optional storeId and the mandatory confirm=true semantics unexplained, which 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?

Schema description coverage is 0%, so the description must compensate. It hints at the 6-digit `code` parameter (two-factor login code) and at `confirm` ('after user confirmation'), but never explains `storeId` (optional, likely the selected store) or that `confirm` must be true.

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

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

States a specific verb and resource: permanently removes the selected asset and its receiving-wallet configuration from the store. The word 'permanently' plus 'from the store' implicitly separates it from the toggle-style sibling theypaid_set_asset_status, though no sibling is named.

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

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

'پس از تأیید کاربر اجرا کنید' gives a precondition but not a true when-to-use/when-not rule, and the natural alternative (theypaid_set_asset_status, disabling rather than deleting) is never named. Usage context is implied only via 'may stop accepting payments with that asset'.

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

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

With no annotations at all, the description carries the full burden and does well: it discloses that the effect is destructive and irreversible until a new key is created, that payment requests are blocked as a consequence, that the session copy is wiped, and that 2FA may be required. The only gap is whether the revoke can be undone or re-issued without full re-setup.

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

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

Three short sentences, front-loaded with the action and its effect, then the consequence, then the prerequisites. No filler 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?

For an annotation-free destructive mutation with no output schema, the description covers the critical ground: what is destroyed, what breaks downstream, and what authorization is required. It leaves minor ambiguity about the conditional 2FA trigger condition and default store resolution.

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

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

Schema description coverage is 0%, so the description must compensate, and it does map all three parameters semantically: the 'selected store' (storeId), 'user confirmation' (confirm), and the 'two-factor login code' (code). It does not state the 6-digit format for code or that storeId falls back to the currently selected store when omitted, so it stops short of full 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 states a concrete verb and resource — revoking the selected store's API key in TheyPaid — plus the second effect of clearing the token cached in session memory. It implicitly separates itself from theypaid_create_store_api_key by noting payment requests stay halted 'until a new key is created', 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?

Usage context is implied rather than stated: the agent learns a user confirmation is needed and that a 2FA code is sometimes required, which signals this is a confirm-gated, user-facing operation. There is no explicit when-to-use / when-not-to-use guidance or named alternative (e.g. rotate vs. revoke), so the agent must infer.

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

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

No annotations are provided, so the description carries the full burden. It does disclose two useful behaviors (a membership check against the connected account, and a persistent selection), but says nothing about what happens if the store is not a member, whether selection is per-session or account-wide, or whether a prior selection is replaced — all critical for a stateful 'select' operation.

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

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

A single front-loaded sentence that covers both the validation and the selection, with no filler. It is dense but not padded; only the missing prerequisites keep it from being exemplary.

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 stateful, prerequisite-dependent operation with no annotations and no output schema, the description omits the failure mode when membership check fails, the prerequisite of a connected account, and whether selection persists. Those are exactly the facts an agent cannot get from any structured field here.

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 (storeId, uuid) with 0% schema description coverage, and the description never mentions it. The agent gets no confirmation that the identifier is the store to be selected, nor where such an id comes from (e.g. theyypaid_list_stores).

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 pair (checks membership, selects the store) and the resource is unambiguous, and it adds scope: the selection is what later asset configuration and payment operations act on. It stops short of explicitly distinguishing itself from near siblings such as theyypaid_get_store, theyypaid_setup_store, or theyypaid_set_store_active, so an agent must infer that 'select' is stateful rather than a plain read.

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

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

Usage is implied by 'selects it for setting up assets and payment operations', which suggests calling this before asset/payment tools. There is no explicit 'call this when...' instruction, no stated prerequisite (e.g. that an account must already be connected), and no naming of alternatives for read-only inspection.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that deactivation stops new payments and preserves wallet settings, and that explicit user confirmation plus sometimes a two-factor code are required. It does not describe the effect of activation, idempotency, permission requirements, or error behavior, leaving notable gaps for a mutation 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?

Three sentences with no wasted wording. The purpose, main side effect, and confirmation/2FA requirement are front-loaded and easy to scan.

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

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

For a mutation tool with no annotations, no output schema, and 0% schema description coverage, the description covers the central behavior and confirmation requirements. It still lacks details about activation effects, permissions, idempotency, and failure modes that an agent would need for full confidence.

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

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

Schema description coverage is 0%, so the description must compensate, and it does mention all five parameters semantically: the asset, the selected store, the enabled/disabled state, explicit user confirmation, and a two-factor login code. It does not explain enum values, the UUID format, the 6-digit code pattern, or that confirm must be true, but the core semantics are present.

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+resource: activating or deactivating a registered asset in the selected store via TheyPaid. It is clear enough to distinguish from store-level operations, but it does not explicitly name or contrast with the closest sibling, theypaid_remove_store_asset.

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 by explaining that deactivation stops new payments while keeping the wallet setting, which is a meaningful distinction from removing an asset. However, it never explicitly names alternatives such as theypaid_remove_store_asset or states exclusion conditions, so usage guidance remains implied rather than explicit.

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

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

With no annotations, the description carries the full burden and does add real behavior: deactivation halts NEW payment acceptance, and the call requires user confirmation and sometimes a second-factor code. It does not clarify whether existing/pending payments are affected or whether the change is reversible.

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

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

Three short sentences, front-loaded with the action, then the consequence, then the auth requirements. No filler 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?

For a mutation tool with no annotations and no output schema, the description covers the key safety-relevant facts (effect of disabling, confirmation, 2FA). It leaves gaps an agent would want: how storeId is resolved, what happens to in-flight payments, and what a successful response looks like.

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

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

Schema coverage is 0% across 4 params, so the description must compensate. It explains the intent of 'confirm' (user confirmation) and 'code' (2FA login code), but says nothing about 'storeId' (optional, presumably defaults to the selected store) and only implicitly covers 'active'.

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: changing a store's active status in TheyPaid. It is distinguishable from mutation siblings like update_store or delete_store because the effect is explicitly a status toggle. It stops short of naming those siblings for contrast.

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

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

Usage is only implied: the agent can infer this is the tool for enabling/disabling payment acceptance rather than editing store details. There is no explicit when-to-use vs update_store / delete_store guidance and no mention of prerequisites such as needing a selected store.

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

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

No annotations are provided, so the description carries the full burden. It does disclose two important traits: the authentication prerequisite and the side effect of selecting the new store for the session, plus that asset/API-key setup is not done here. It omits duplicate-name behavior, error handling, permission scope, and whether credit is consumed, so it is not yet enough to call the tool confidently.

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 creation action and followed by the session-selection effect and the follow-up step. It is efficiently sized; the only loss of value comes from not spending those words on the parameters.

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?

This is a mutation tool with no annotations, no output schema, and four undocumented parameters. The description covers prerequisites and the selection side effect but leaves the parameter meanings, the return value (for example, the new store ID), and failure modes unexplained; too much is missing for a write 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 0%, and the schema provides only types and length limits for name, website, industry, and description. The description mentions none of these parameters, so nothing compensates for the coverage gap; an agent must guess formats such as whether website needs a scheme.

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+resource: it creates a store via the authenticated TheyPaid account and selects it for this MCP session. It also implies a combined effect (create + select) that distinguishes it from the sibling theyypaid_select_store, though it never names the sibling or explains the difference 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?

It hints at context: an authenticated account is required, and the store is auto-selected for the session. It also tells the caller to configure asset and API key separately afterward, which is useful sequencing. However, it never says when to call this versus theyypaid_select_store or theyypaid_connect_account, and no exclusions 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?

With no annotations, the description carries the full burden. It usefully discloses that this creates a real invoice, requires prior user confirmation of amount and asset, and yields a payable invoice back to the user. It omits permissions/auth requirements, whether the top-up actually debits funds, idempotency, and failure behavior, leaving notable gaps for a mutation 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?

Two tight sentences, front-loaded with the action and scope, followed by the execution precondition and handoff step. No filler or redundant restatement of the title.

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

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

For a 3-parameter mutation tool with no annotations and no output schema, the description covers the core flow and even hints at the return value (the payable invoice). However, it leaves auth requirements, idempotency, and the meaning of the 'confirm' flag unaddressed, so it is only adequately 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?

Schema coverage is 0%, so the description must compensate. It references the two business-meaningful inputs (amount and asset, both needing user confirmation), which helps, but says nothing about the required 'confirm' boolean, the asset enum values, or the amount bounds. Partial compensation only.

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 ('می‌سازد' – creates) and resource ('فاکتور' – invoice) and scopes it to the credit top-up path ('از مسیر شارژ اعتبار'), which meaningfully separates it from siblings like theypaid_create_invoice. It is clear but does not explicitly name or contrast with that closest 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?

It gives an explicit precondition ('پس از تأیید مبلغ و دارایی توسط کاربر اجرا کنید') and a post-step (hand the returned invoice to the user for payment), which is strong usage context. It stops short of naming when NOT to use it or pointing to alternatives such as theypaid_create_invoice or theypaid_create_payment_link.

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

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

With no annotations at all, the description carries the full burden. It does add real value by disclosing partial-update semantics (only supplied fields change), which tells the agent omitted fields are preserved. However, it says nothing about required permissions, reversibility, or the response shape for a mutation on an authenticated account.

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 zero waste: the mutation scope is front-loaded and the partial-update rule follows immediately. Nothing is repeated or padded.

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

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

There are no annotations and no output schema, and the description omits the required storeId parameter, the UUID/length constraints, and any indication of what is returned or whether the operation can fail. Adequate for the mutation scope but incomplete for a five-parameter tool with no structured safety metadata.

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 schema gives types and lengths but no meaning. The description names four of the five parameters (name, website, industry, description), adding semantic context, but never mentions storeId (the required parameter) or explains formats, offsetting only part of the coverage gap.

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

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

The description uses a specific verb (changes/edits) plus the resource (store in the authenticated TheyPaid account) and enumerates the editable fields (name, website, industry, description), which implicitly separates it from siblings like set_store_active or delete_store. It does not explicitly name a sibling, so full 5-level differentiation is not reached.

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 clause 'only submitted fields are edited' implies partial-update usage, but there is no explicit statement of when to choose this over setup_store or get_store, nor any prerequisites or exclusions. Usage is inferable 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?

With no annotations at all, the description carries the full burden, and it does disclose meaningful traits: validation happens before the swap, the effect is limited to future payments, a confirm gate guards the mutation, and 2FA may be demanded. It stops short of saying whether the previous address stops working immediately, whether the operation is reversible, or what happens on validation failure — important gaps for an unannotated destructive write.

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

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

Three sentences, front-loaded with the core action, then consequence, then the confirmation/2FA caveat. Every sentence carries information; nothing is redundant. Slightly compressed at the end where the 2FA note is stated as a bare possibility.

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 mutation with no annotations and no output schema, the description covers the essential mechanics but leaves storeId and asset selection unexplained and says nothing about the return value or failure modes. It is adequate to attempt the call, not adequate to call it confidently in edge cases.

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

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

Schema description coverage is 0%, so the description must compensate for all five parameters. It explains publicValue (public address or xpub), confirm (true only after user approval), and code (six-digit 2FA), but asset and storeId are only obliquely gestured at via 'the asset configured in this store' — an agent cannot tell from the text that both are explicit required/optional inputs, nor what the asset enum means.

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 compound action: validate a new public address or xpub with TheyPaid and replace the receiving wallet for the store's configured asset. That is a clear verb+resource pairing an agent can act on. It does not, however, contrast itself with close siblings such as theypaid_validate_wallet, theypaid_create_wallet, or theypaid_connect_wallet, so the boundary is left to inference.

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 real usage context: the change affects subsequent payments, and confirm must be set to true only after user approval, with a possible six-digit 2FA step. What it never says is when to choose this over the sibling wallet tools (validate/create/connect), nor what prerequisites must already hold (e.g., whether the store must be selected or the asset enabled first).

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

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

No annotations exist, so the description carries the full burden. It correctly narrows scope to format checking (not registration or validation on the TheyPaid side) and adds a safety constraint about never supplying a private key or recovery phrase. It does not state that the call is read-only/side-effect free, nor what the response or failure looks like.

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

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

Three short sentences, front-loaded with what is checked, then the sibling routing, then the safety warning. Every sentence carries distinct information and none repeats 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 two-parameter, read-only-implied validator with no annotations and no output schema, the description covers purpose, the key alternative, and the critical secret-handling rule. The remaining gap is what a successful versus failed validation yields, which an agent would otherwise have to discover by calling.

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%, so the description must compensate. It usefully reveals that publicValue accepts either a public address or an xpub, which the bare string schema does not, and ties the value to a supported asset. It says nothing about the asset enum semantics or length/format constraints, leaving real gaps.

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 (checks/validates) and resource (public address or xpub format) scoped to a supported asset, and explicitly separates itself from theypaid_connect_wallet. An agent can tell it is a format pre-check, not an actual wallet connection, without reading any schema.

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

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

Explicitly routes the agent to theypaid_connect_wallet when the goal is validating in TheyPaid and connecting to a store, which is a genuine alternative-selection rule. It stops short of spelling out the reverse case (e.g. that this tool is only the pre-check step), so it is strong but not exhaustive.

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

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses the polling behavior and terminal states, plus that it returns the latest status when the wait ends, but it omits important details such as blocking behavior, possible intermediate statuses, error handling, and permission/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?

The description is a single dense sentence with no wasted words and front-loads the core polling behavior and terminal conditions. It is appropriately sized, though the semicolon construction is slightly compressed for the amount of behavioral nuance it tries to convey.

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 polling tool with no annotations, no output schema, and 0% schema description coverage, the description is not complete enough. It explains the core wait condition and return summary, but leaves the three parameters, return format, and failure/error behavior undocumented.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It only indirectly implies a wait-time concept and says nothing about invoiceId being required, timeoutMs defaults/limits, or intervalMs controlling polling frequency.

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 a specific verb and resource: reading invoice status from TheyPaid, polling until PAID, INSUFFICIENT, EXPIRED, or timeout, then returning the latest status. This distinguishes it as a waiting/polling tool rather than an immediate check, though it does not explicitly name sibling alternatives such as check_payment or get_invoice.

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

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

The description implies when to use the tool: when the caller wants to wait for an invoice to reach a terminal payment state or timeout. However, it does not explicitly state when not to use it or contrast it with nearby tools like check_payment, recheck_invoice, or get_invoice.

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