IMBA Agent Spend

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

With annotations declaring readOnlyHint=false, idempotentHint=true, and destructiveHint=true, the description adds important context: it issues a prepaid card, requires ext_id for idempotency, and clarifies that IMBA does not create the booking. It also warns against using payment_source=stars and client_id. This goes beyond the structured annotations without contradicting them.

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 dense and purposeful, with the core purpose front-loaded and usage constraints packed into a few sentences. Minor redundancy ('prepaid from this agent') and mixing endpoint info with instructions slightly hurt clarity but overall it's efficient.

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

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

For an 8-parameter tool with 25% schema coverage, the description explains the essential params and critical constraints. It doesn't detail every optional field, but the required usage context and idempotency semantics are covered. Some gaps remain around card product selection, but the reference to core.card_product.id helps.

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?

Input schema coverage is only 25%, so the description must clarify key parameters. It explicitly says ext_id is required and is an idempotency key, and that imba_product_id is core.card_product.id. It also warns against payment_source=stars (though payment_source isn't in the schema). This meaningfully compensates for the schema's 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?

The description states a specific action ('Issue a Visa/MasterCard prepaid') and the resource (a virtual card), plus the concrete use case (paying merchants that require a card). It also names the endpoint and disambiguates from other card operations by mentioning what IMBA does not do.

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 explains when to use this tool: when the agent needs to pay merchants requiring a card, and explicitly notes constraints like 'Never payment_source=stars' and 'Never pass client_id'. It doesn't explicitly name sibling alternatives, but the card-issuing context plus 'IMBA does not create the booking' gives useful routing context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds some context beyond annotations by stating the endpoint and that USDT is the spendable currency, but it does not describe response format, potential errors, or any other behavioral details.

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 short sentences with no filler. The endpoint is front-loaded and the currency clarification 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 zero-parameter, read-only, idempotent tool, the description is nearly complete: it gives the endpoint, method, and currency context. The main omission is the expected response shape, but no output schema exists and the tool is simple enough that the endpoint clarifies the return value.

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

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

There are zero parameters, so the schema requires no documentation. The description's currency note adds useful semantic meaning beyond the empty schema, meriting a solid baseline score.

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 resource ('/api/balance') with an explicit HTTP method ('GET'), and adds a meaningful currency detail ('USDT is the spendable catalog currency'). It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools beyond the name.

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

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

No guidance is given about when to use this tool versus alternatives such as get_spend_policy or get_deposit_address. The description is purely declarative and provides no context for selection.

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

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

Beyond the readOnly/idempotent annotations, it discloses the JWE-encrypted delivery of PAN/CVV when jwe_public_key is registered, masking without it, and a 'never logs raw PAN' guarantee. These are non-obvious behaviors an agent must know before calling. No contradiction with annotations.

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

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

Seven terse sentences each add a distinct fact: purpose, use case, encryption, masking, logging, default, and usage rule. The core purpose is front-loaded and there is 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?

The description captures the key response variations (encrypted vs masked PAN/CVV), the usage trigger, and a security/logging constraint despite having no output schema. It omits the full result shape and any error cases, but for the stated merchant-checkout purpose the essential information is present.

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

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

With the schema providing zero descriptions, the text adds essential meaning: card_id is restricted to cards the agent owns, cvv defaults to true, and client_id should never be passed. It doesn't spell out the response when cvv=false, but it compensates meaningfully for the schema 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 immediately states the tool is for fetching card payment credentials (PAN/CVV) for a card the agent owns and ties it to the concrete checkout use case. Mentioning the endpoint and ownership scope distinguishes it from list_cards, get_balance, and similar siblings without ambiguity.

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

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

It gives an explicit when: presenting PAN at merchant checkout for airline, datacenter, and SaaS purchases. It also supplies a firm do-not-do ('Never pass client_id'), but it never names alternate tools for other card-data needs, so it misses full when-not/alternative clarity.

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 all annotations set to false, the description carries the full behavioral burden. It explains the address is issued for the authenticated agent only, warns against caching, and discloses a 24h unfunded hold. This goes well beyond what the structured annotations provide.

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 compact set of six short, directive sentences. Every phrase earns its place: endpoint, blockchain, authentication scoping, re-etch rule, caching prohibition, asset restriction, and hold period. There is zero fluff and the most important operational warnings are highlighted.

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 tool, the description covers all essential aspects: the HTTP action, the targeted blockchain/asset, the ownership of the address, the re-etch/caching behavior, and the temporary hold. Nothing an agent needs to invoke this tool correctly is missing.

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

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

The input schema has zero parameters and 100% coverage, so the baseline is 4. The description adds the fixed blockchain=tron context and clarifies the scope, but since there are no parameters to document, no further semantic detail is needed.

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 the exact endpoint (POST /api/deposit_address), the target blockchain (tron), and the asset (USDT TRC-20), so the agent knows precisely what this tool does. It is clearly distinguished from sibling tools like get_balance or get_card_details by the explicit resource and purpose.

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 explicitly states the operational rules: always re-etch before send, do not cache, and USDT TRC-20 only. These rules effectively tell the agent when and how to use the tool, and the 'only' provides an exclusion for other assets/chains. No alternatives are needed because no sibling covers this deposit-address function.

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?

注释已经声明了readOnlyHint=true和idempotentHint=true，而描述中的'Read-only'只是重复了这一信息，没有增加新的行为细节，如权限要求、速率限制或数据范围。因此描述在行为透明度上几乎没有超出注释的贡献。

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?

描述仅用三句话承载了核心信息，没有冗余，关键信息（禁止轨道、允许目录）置于开头，最后以'Read-only'收尾。结构高效且易读。

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?

对于无参数、无输出模式的简单只读工具，描述覆盖了主要内容：禁止的轨道、层级规则和允许目录。但未说明策略的格式或如何使用返回结果，在完整性上有轻微不足。

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覆盖率为100%，因此描述无需添加参数语义。根据0参数基线，此项评分为4。

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?

描述以'Forbidden rails and tier rules'和'Allowed catalog'明确说明了工具返回的主题，并通过'Read-only'暗示了查询操作。虽然缺少显式动词'获取/检索'，但工具名称和只读声明使意图清晰，足以与列出策略明细的兄弟工具区分。

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?

描述未提及何时使用此工具，也未与其他类似工具或替代方案进行对比。没有说明使用场景、前提或排除条件，因此代理缺乏选择此工具而非其他工具的依据。

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

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

The annotations mark destructiveHint true, and the description fully discloses the side effect: 'Debits ~0.99 USDT from 2401.' It goes further with latency ('Space ~1s'), the explicit non-effects (no gating, banning, or unblocking), and the constraint 'Never pass client_id' — all beyond what annotations provide. No contradiction with annotations.

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

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

The description packs purpose, usage timing, endpoint, body, cost, side effects, latency, and exclusions into roughly 60 words, with the main action front-loaded. The only blemish is the likely typo 'Space ~1s' instead of something like 'Takes ~1s,' but the overall structure is efficient.

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

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

For a 3-parameter tool with no output schema, it covers the action, required parameters with an enum, cost side effect, timing, and non-behaviors. It falls short on the undocumented third 'refresh' parameter and does not describe report contents or error handling, but those gaps are unlikely to prevent correct invocation.

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

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

Schema description coverage is 0%, so the description carries the burden. It adds the network enum values ('tron_usdt | eth | btc'), names the two required fields (network, address), and warns against client_id. However, a third 'refresh' parameter appears in the schema but is completely absent from the description, so it's good but not fully complete.

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 opens with a specific verb and resource: 'Screen a crypto address for dirt (sanctions / mixer exposure).' It also disambiguates by explicitly listing what it does not do ('does not gate deposit, does not ban or unblock') and by noting that TON is not in the catalog, so an agent can distinguish this screening tool from enforcement or lookup 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?

It provides explicit trigger contexts: 'Use BEFORE you accept a TRC-20 send, or AFTER a wallet is blocked and the reason is unclear.' It also clarifies non-use boundaries like 'does not gate deposit, does not ban or unblock,' telling the agent when not to rely on it for enforcement.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the agent knows this is safe and repeatable. The description adds meaningful behavioral context beyond annotations: the polling requirement, the 404 for non-own checks, and the warning that client_id must never be passed. It does not describe the report shape, but with no output schema and a read-only poll operation, the core behavior is well covered.

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, information-dense sentences. Every sentence earns its place: what it does, how it behaves (poll), when to use it, and what not to do. Front-loaded with the HTTP method and resource path; 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 simple one-parameter read-only poll tool with rich annotations, the description covers the essential context: purpose, polling behavior, ownership restriction, and usage sequence. The only notable gap is that it doesn't describe what the returned 'dirt report' contains, but since there is no output schema and the tool is read-only/idempotent, that is a minor omission rather than a critical gap.

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

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

Schema description coverage is 0% and there is only one parameter (id). The description does not explicitly re-document the id parameter, but it indirectly clarifies that the id is the identifier of the check/report obtained from kyt_check and that client_id must not be included. For a single required integer id, this provides enough operational context, though explicit naming would have made it flawless.

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

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

The description identifies a specific resource (KYT check report) and the action (poll until ready), with the nuance of being read-only. It clearly differentiates the tool from its siblings: it is used after kyt_check and is distinct from kyt_checks, the list endpoint. However, the tool name and title already convey the core purpose, and a slightly stronger statement of the resource would push it to 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?

Excellent usage guidance: it explicitly states when to use this tool ('Use after kyt_check when a wallet was blocked'), tells the agent it must poll, and gives a critical exclusion ('Never pass client_id'). It also warns of the 404 behavior for non-own checks, which is valuable for an agent deciding whether this is the right call.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds useful behavioral context beyond that: the scope is 'Own' history, latency is roughly 1 second, and client_id must never be passed. No contradiction with annotations.

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

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

The description is short and front-loaded with the endpoint and purpose. Every clause adds value: scope, use case, latency, and a critical safety warning. There is no redundant 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?

The core purpose is clear, and the ownership and safety constraints are helpful. However, since there is no output schema and no parameter descriptions, the description leaves pagination behavior and the exact response shape under-explained for an agent that needs to page through history.

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 description does not explain 'limit' or 'last_id' or how pagination works. The parameter names hint at pagination, but the description adds no meaning beyond the schema's raw integer bounds.

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 identifies the tool as a KYT history lookup: 'Own KYT history plus quote fields. Use to find a past address check.' This distinguishes it from sibling tools like kyt_check, kyt_quote, and kyt_check_get, which are about creating, quoting, or fetching individual checks rather than browsing history.

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 explicit use context: use this to find a past address check. It also adds a safety constraint with 'Never pass client_id,' but it does not explicitly name alternatives or say when not to use this tool, so it stops short of full guidance.

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

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

Annotations already cover read-only and idempotent behavior, and the description adds meaningful context: pricing is not debited, debit occurs on kyt_check at ~0.99 USDT from 2401, service is feature-flagged, latency is ~1s, and TRON deposits are unaffected. This significantly enriches the agent's understanding beyond the annotations.

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

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

Extremely compact and information-dense, with the endpoint and core purpose first, then cost, availability, exclusions, and latency. Every clause earns its place and no redundant wording appears.

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 parameterless read-only quote endpoint, the description is complete: it states purpose, pricing behavior, feature flags, exclusions, endpoint family, and performance. There is no output schema, but the description's 'price' purpose sufficiently frames the expected response without needing to over-specify.

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

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

The tool has zero parameters, so the schema already covers everything. The description adds no parameter details, but none are needed; baseline 4 is appropriate for a parameterless tool.

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

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

States a specific endpoint and purpose: price for a paid crypto-address screen via Didit. Explicitly distinguishes itself from kyt_check (debit happens there, not on quote) and from /api/client/kyt_* and partner endpoints.

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 context on when the tool is available (requires didit.enabled and didit.agent_api) and when it is not relevant (does not gate TRON deposit, not partner endpoint). Could more explicitly state 'use kyt_check for the actual screen/debit, use this for pricing first,' but the debit distinction strongly implies the workflow.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, so the description only needs to add context beyond that. It adds a rate-limit requirement and documents that the response contains an id consumed by create_card, which is useful behavioral information and does not contradict the annotations.

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

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

The description is very short and every part earns its place: the endpoint, the downstream use of the returned id, and the rate-limit instruction. There is no filler or repetition of annotation information.

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

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

For a zero-parameter, read-only list call, the description covers the key operational details: purpose, the important id mapping to create_card, and call pacing. It does not fully spell out the response shape, but the information needed to invoke the tool and use its result is largely sufficient given the tool's simplicity.

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

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

The input schema has no properties, so there are no parameter semantics to describe; the baseline is 4. The description adds meaningful semantics about the response id being used as imba_product_id for create_card, which helps the agent connect the tools.

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 title 'List card products' plus the endpoint /api/card_products make the operation and resource clear. However, the description itself lacks an explicit verb and does not differentiate this tool from the similarly named sibling list_cards, so it does not reach a 5.

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

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

The description gives clear workflow context: the returned id should be used as imba_product_id when calling create_card for Visa prepaid. It also provides pacing guidance by telling the agent to space catalog calls about 1 second apart, though it does not explicitly state when not to use this tool versus alternatives.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by naming the exact endpoint and indicating the operation is scoped to the authenticated agent. It does not describe return values or pagination, but that is a minor gap given the strong annotation coverage.

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

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

Two short sentences with no filler. The endpoint and scope are front-loaded, and the clarification about client_id is a useful final note. 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?

For a zero-parameter, read-only list operation with annotations already covering the safety profile, the description provides enough to call the tool: the endpoint, the auth scope, and the absence of a client_id requirement. It does not explicitly say that a list of cards is returned, but the title and endpoint make that sufficiently clear.

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

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

The input schema has zero parameters and 100% schema description coverage, so there is little parameter burden. The description usefully confirms that no client_id argument is expected, which helps prevent an agent from inventing a parameter based on sibling tools. This goes slightly beyond the empty schema, earning a 4.

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

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

The description identifies the resource (/api/cards), the HTTP method (POST), and the scope (authenticated agent), and the title conveys the listing operation. It is concrete but does not explicitly state 'lists the agent's cards' in the description, and the POST method could initially be misread as a create operation, so it does not fully distinguish itself from create_card.

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

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

The phrase 'for the authenticated agent' implies this tool is for retrieving the current agent's own cards, and 'No client_id argument' hints that no client_id is needed. However, there is no direct guidance about when to choose this over siblings like list_card_products or get_card_details, and no explicit exclusions are provided.

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

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

The annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond that: the HTTP method, a fixed provider value, and a pacing constraint ('Space catalog calls ~1s apart (agent catalog_gap)'). This adds value without contradicting the annotations.

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

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

The description is compact and front-loaded, with five short fragments that each carry useful information. No filler is present, and the endpoint, domain, provider, optional filter, follow-up action, and pacing guidance all earn their 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 simple listing tool with read-only annotations, no required parameters, and no output schema, the description covers the endpoint, provider, optional country filter, downstream purchase action, and rate limiting. An explicit return-shape note is absent, but the title and 'plan id' reference make the response concept predictable enough.

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 prose must carry the semantic weight. The description does this by explaining 'esim_provider=yesim' and 'Optional country ISO2', giving both parameters meaning and format guidance that the bare schema lacks.

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 the exact endpoint and resource ('POST /api/esim/plans'), and the title states 'List eSIM plans' clearly. It also distinguishes this listing step from the purchase step via 'Use plan id with purchase_esim', so an agent can separate catalog discovery from purchasing.

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 provides clear context (travel/data eSIM), specifies the provider value, marks country as optional, and directs the plan id to purchase_esim. It does not explicitly state when-not-to-use this tool or list all alternatives, but the purchase_esim reference gives enough routing for the common workflow.

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

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

It discloses operational behavior beyond the annotations: the catalog is live, has ~20k positions / ~2k unique items across named categories, requires throttling (~1s spacing), and warns against assuming a SKU. The annotations already declare read-only and idempotent, and the description adds rate-limit and data-freshness context that is genuinely useful.

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 terse but dense with signal: endpoint, catalog scope, categories, optional query, downstream purchase usage, rate-limit advice, and an anti-SKU caveat. Every clause earns its place and important constraints are front-loaded.

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

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

For a simple list tool with no output schema, it covers the essential context: live catalog scope, optional query, rate limiting, and how the results relate to purchase_gift via offer_id and ext_id. The main gap is that query semantics and return shape are implied rather than explicitly described.

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

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

Schema coverage is 0%, so the description must compensate for the undocumented query parameter. It only says 'Optional query string,' which adds little beyond the schema's property name and optionality. It does not explain what the query filters on, what syntax to use, or how it affects results.

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

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

The description identifies the resource as a live gift catalog and enumerates categories, and it is clearly distinguishable from the sibling purchase_gift because it is positioned as the catalog lookup that feeds purchase_gift. However, the action 'list' is carried mainly by the name/title; the description itself is fragmentary rather than a direct verb statement.

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

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

The description gives clear usage context: call this before purchase_gift, pass offer_id + ext_id to purchase_gift, and space catalog calls ~1s apart. It does not explicitly state when not to use this tool or name an alternative tool, but the sequential instruction is strong enough.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: payload.code is the source of truth, SMS/Telegram must not be used, category=codes is for OTP, and calls should be spaced ~1s apart. This goes well beyond the annotations.

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

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

The description is compact and dense, with useful front-loaded information about the endpoint and use case. However, the terse fragments and unexplained term 'Space catalog' make it slightly less structured than ideal.

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

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

It covers the core 3-D Secure polling scenario well, including code handling, category filter, and rate spacing. But without an output schema, it still lacks response shape details, pagination semantics for prev_id/prev_ts, and full category meanings, leaving some gaps for an agent trying 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 explains category=codes but says nothing about limit, prev_id, prev_ts, or what the other category values (all, support, tx) mean. Most parameter semantics remain undocumented.

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 resource (notifications), a specific action (poll), and a concrete triggering scenario (Visa 3-D Secure). It also gives the exact endpoint and differentiates this tool from alternative delivery channels like webhook and email.

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 explicitly says when to poll (when Visa payment asks for 3-D Secure) and provides operational rules: keep payload.code, never SMS/Telegram, use category=codes, and space calls ~1s apart. It mentions webhook/email alternatives but does not fully specify when to prefer them over polling.

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

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

Annotations already declare the tool as mutating, destructive, and idempotent. The description adds useful behavior beyond that: the POST endpoint, the SQL new-eSIM path triggered by omitting iccid, the ownership precondition for a set iccid, and the 'Never Stars' prohibition. The cryptic 'Never Stars' is a minor weakness but does not contradict the annotations.

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

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

The description is only a few sentences, front-loaded with the endpoint and core action, and packs the key usage constraints into compact language. Every sentence contributes actionable information without 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 mutating purchase tool with no output schema and no parameter descriptions, more context would help: how to obtain plan_id, what payment_source accepts, and what the response contains. That said, the critical iccid special-case and ownership precondition are covered, and annotations handle the mutation/idempotence/destruction profile.

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 meaningfully explains iccid's optional new-eSIM behavior and the ownership requirement, and it notes ext_id is required. However, plan_id and payment_source are left undefined, and 'Never Stars' is too vague to serve as clear payment_source guidance.

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 ('Buy') and a specific resource ('travel/data eSIM plan'), and even names the exact endpoint. It is clearly distinguishable from siblings like list_esim_plans and purchase_gift.

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 actionable usage guidance: omit blank/null iccid for the new-eSIM path, only set iccid if it already belongs to the agent, and ext_id is required. It does not explicitly name alternatives, but the context is clear enough from the sibling list and the 'Buy...eSIM plan' framing.

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

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

Annotations already mark the operation as non-read-only, idempotent, and destructive, so the description does not need to re-state mutation. It adds a critical value restriction ('Never payment_source=stars') and notes the offer list is live, but it does not disclose charging or irreversibility beyond what 'Buy' implies.

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 clauses front-load the endpoint and purpose and avoid filler. Every sentence adds some information, though 'POST /api/purchase' is partly redundant with the tool name/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 5-parameter purchase tool with no output schema and zero schema descriptions, this is thin: it omits how to discover valid offers, what expected_price/required_fields mean, and what a successful purchase returns. Annotations provide idempotency/destruction flags but not enough operational detail.

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

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

Schema coverage is 0%, so the description carries the burden for five parameters. It adds only two param-related hints—ext_id is required and payment_source must not be 'stars'—and leaves offer_id, expected_price, and required_fields semantically unexplained.

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

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

The description states a specific verb ('Buy'), a concrete resource ('a brand gift code'), and gives examples (Apple, Steam, Google Play). It clearly distinguishes the operation from sibling tools like purchase_esim and list_gift_offers.

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 operational constraints ('ext_id required', 'Never payment_source=stars') but does not explain when to prefer this tool over related siblings or when not to use it. Selection context is only implied by the 'gift code' phrase, with no explicit exclusions or alternatives.

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

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

Annotations already signal destructive and non-idempotent, but the description adds critical non-obvious behavior: the previous HMAC dies immediately, the plaintext HMAC is returned only once, and it is never a Wallet JWT. This is exactly the context an agent needs before invoking a destructive secret-rotation 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?

The description is dense and front-loaded: endpoint, immediate consequence, prerequisite, failure mode, and one-time secret all fit in five short sentences. Minor redundancy and the slightly ambiguous 'here' keep it from a 5.

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

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

Core behavior, prerequisite, failure mode, and secret return semantics are covered. However, two of three parameters are undocumented, there is no output format beyond 'plaintext HMAC returned once,' and the only error condition mentioned is the 400 for callback_url. For a mutation tool with no output schema and no parameter descriptions, this is incomplete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains callback_url's role in the PATCH-before-rotate flow, but email and jwe_public_key are completely unexplained. The agent is left guessing what those optional parameters do, which is a substantial 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 names the HTTP endpoint, the verb (POST), the resource (webhook HMAC), and the core effect: rotating the HMAC makes the previous one die immediately. This is clearly distinguishable from sibling tools like set_webhook and leaves no doubt about what the tool does.

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 states the prerequisite of an existing callback_url, the 400 failure if absent, and the ordering requirement to PATCH the webhook first. It does not explicitly name an alternative sibling tool, but the context of when rotation is allowed versus when a webhook must be patched first is clear.

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

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description discloses a crucial one-time behavior: 'HMAC plaintext is shown once when a URL is first accepted.' It also reveals the stateful prerequisite with hmac/rotate. This adds real operational value that an agent cannot infer from annotations or schema alone.

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

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

The description is compact and front-loaded: endpoint, primary action, optional parameters, then the critical one-time HMAC caveat. Every sentence adds information, and the 'Not SMS' exclusion is a useful terse clarification rather than fluff.

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 three-parameter configuration tool, the description covers all parameters, key prerequisites, and the most important behavioral caveat. It does not describe the response shape or error conditions, and with no output schema those are minor omissions for invoking the tool correctly.

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

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

With schema description coverage at 0%, the description carries the full semantic burden and does so well: callback_url is tied to hmac/rotate, jwe_public_key is tied to card_encrypted, and email is tied to 3DS OTP. It does not provide exhaustive format details or explicitly note that all parameters are optional, but it gives enough meaning beyond the raw 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 operation ('Sets https callback_url'), lists the optional parameters and their purposes, and even notes the callback_url prerequisite for hmac/rotate. This is enough for an agent to distinguish it from related sibling tools like rotate_hmac without opening their schemas.

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

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

The description provides clear usage context: callback_url must be set before hmac/rotate, jwe_public_key is for card_encrypted, and email is for 3DS OTP. It also adds an explicit exclusion ('Not SMS'). However, it does not name alternative sibling tools or say when NOT to use this tool beyond the SMS note.

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

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

Annotations already declare destructiveHint, idempotentHint, and readOnlyHint, so the description does not need to repeat those. It adds meaningful behavioral context: the SQL owner guard prevents cross-agent top-ups, and 'Never Stars' imposes a strict currency limitation. This goes beyond what annotations provide, though it does not explain idempotency or destructive effects.

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 short and has no filler, but the first sentence is grammatically awkward and ambiguous ('from this agent 2401 USDT'). It front-loads the endpoint and core constraint, yet the lack of clarity in key phrasing reduces effectiveness.

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, idempotent write operation with no output schema, the description should clarify the effect, return behavior, idempotency semantics, and parameter meanings. It provides only ownership and currency constraints, leaving important operational details 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, but it only restates that ext_id is required and that card_id must belong to the same agent. It does not explain the meaning of amount, the role of ext_id (likely an idempotency key), or how the '2401 USDT' phrase relates to the amount parameter.

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

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

The description identifies the operation as topping up a card via the named endpoint and adds specific constraints: the card must belong to the agent and the currency is USDT, not Stars. It is not a tautology and the core action is clear, though the phrase 'from this agent 2401 USDT' is cryptic and could confuse the amount or agent meaning.

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

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

There is no guidance on when to use this tool versus alternatives like create_card or get_card_details. The description only states constraints ('card_id must belong to the same agent', 'Never Stars') rather than explaining the selecting context or when not to use it.

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