SIMcloud

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

Annotations already cover read-only, non-destructive and idempotent behavior, so the description only needs to add context — and it does, by clarifying that no purchase or wallet debit occurs. It does not say whether an unsupported meter returns a false flag or raises an error, which is the remaining behavioral gap.

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

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

Two short sentences, usage constraint first, negation second. Nothing wasted and no repetition of the title.

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

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

An output schema exists, so explaining return values is not required, and the pre-requisite ordering is fully stated. Only the failure-mode semantics (error vs. negative result) are left implicit, which is minor for a one-parameter read tool.

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

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

Single parameter with 100% schema description coverage, so the defensive baseline applies. The description only restates that the input is a prepaid meter number and adds no format or normalization detail beyond the schema.

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

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

States a specific verb and resource ('check whether a prepaid electricity meter is supported') and scopes it as a pre-flight validation, which cleanly separates it from the create_/get_ siblings. An agent can identify the tool's job without opening the schema.

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

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

Explicitly says to use it 'before create_electricity_order', naming the sibling and the ordering dependency. It also states the negative case ('does not buy electricity or spend wallet funds'), removing the main ambiguity in a wallet-spending API surface.

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 (destructive, non-idempotent, open-world), it discloses that the call spends wallet funds, queues an irreversible external transaction, must not be auto-retried on an ambiguous result, and that duplicate same-MSISDN-and-amount requests within 5 minutes yield HTTP 409. The confirmation precondition adds further operational context.

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 sentences, front-loaded with the trigger condition, then the confirm-before-calling instruction, then the risk disclosure, then the retry/duplicate rule. Every sentence carries distinct and actionable 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?

The tool is a destructive, non-idempotent payment operation with an output schema, and the description covers the safety profile (wallet spend, irreversibility, no-retry, 409 dedupe) that the agent needs to call it correctly. Return values are handled by the output schema, so nothing material is missing.

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

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

Schema description coverage is 100% and each of the four parameters is documented in the schema, so the schema does the heavy lifting. The description restates the four fields to confirm (MSISDN, network, rand amount, reference) but adds no format or syntax detail beyond that, which is the baseline 3 case.

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 pairs a specific verb ('send or recharge') with a specific resource ('prepaid airtime to a South African mobile number') and enumerates the supported networks, which cleanly separates it from sibling create_data_order and create_vas_order. An agent can select this without opening the schema.

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

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

It states an explicit triggering condition ('when an authenticated SIMcloud user asks to send or recharge prepaid airtime') and constrains it to South African numbers on four networks. It doesn't explicitly name the sibling alternatives (create_data_order, create_vas_order) it is not, so it falls just short of a 5.

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

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

Annotations already declare destructive, non-idempotent, open-world behavior, and the description adds concrete operational context: wallet funds are spent, the external transaction is irreversible, and duplicate same-MSISDN-and-amount requests within 5 minutes return HTTP 409. That is exactly the extra context the annotations cannot express.

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

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

Five sentences with no filler. Usage and prerequisite come first, then cost and irreversibility, then retry and duplicate handling — each sentence carries distinct operational value.

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

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

For a destructive, non-idempotent mutation tool with an output schema, the description covers authentication context, the prerequisite data lookup, financial and irreversibility warnings, retry policy, and duplicate behavior. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds cross-parameter meaning: the network and amount must come from list_data_products, and the duplicate rule keys on the MSISDN-and-amount pair. It does not add detail for the reference parameter, but the schema already covers it.

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 ('send a confirmed South African mobile data bundle') and scopes it to an authenticated SIMcloud user, which cleanly separates it from create_airtime_order, create_electricity_order, and create_vas_order. An agent can identify the tool without opening the schema.

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

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

Explicitly names the prerequisite call (list_data_products first) and the condition for using it (user asks to send a confirmed bundle). It also gives a hard usage exclusion: never automatically retry an ambiguous result.

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 destructive=true, idempotent=false and openWorld=true, and the description adds genuinely new behavioral facts: it spends wallet funds, submits an irreversible external transaction, and must not be retried blindly. It also requires confirming meter, amount, reference and recipient before invocation, which no annotation conveys.

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: trigger first, confirmation checklist in the middle, risk warning last. Every clause carries operational weight, and the irreversibility warning is placed where it will be read before invocation.

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

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

For a destructive, non-idempotent, money-spending mutation tool, the description covers trigger, prerequisites, confirmation requirements, and the retry hazard; the output schema handles return values. No material gap remains for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an increment by tying all four parameters into a pre-call confirmation checklist and by naming the meter's provenance. It does not add range or format detail beyond the schema, but the workflow semantics around the parameters are a real addition.

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 ('buy prepaid electricity') and immediately scopes it to a meter confirmed via check_electricity_meter, which cleanly separates it from siblings like create_airtime_order or create_data_order. An agent can select this tool without opening 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?

Explicit trigger condition ('when an authenticated SIMcloud user asks to buy prepaid electricity'), an explicit prerequisite (meter already confirmed with check_electricity_meter), and an explicit failure-mode instruction ('do not automatically retry an ambiguous result'). Nothing about when to use this versus alternatives is left 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?

Beyond the annotations it discloses that the call spends wallet funds, queues an irreversible external transaction, and must not be retried on an ambiguous result – the last point is genuinely additive given idempotentHint=false. It also implies the authentication context, which no annotation covers.

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 dense sentences, front-loaded with the trigger, then the precondition, then the risk warning. No filler and nothing buried.

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

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

Return values are covered by the output schema, and the risk profile is well handled, but for a fund-spending purchase tool the required 'reference' parameter is left completely unexplained – an agent has no basis for constructing or reusing it. Adding one clause on reference semantics would make this 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 only 50%, so the description needs to compensate, and it does not: 'amount' and 'reference' are never explained, despite 'reference' being required and the operation being non-idempotent (where a caller would expect guidance on uniqueness or reuse). 'Available product and denomination' only loosely hints at product_id and voucher_type, which the schema already documents.

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 ('buy a confirmed VAS voucher') and scopes it to an authenticated SIMcloud user, which separates it from the read-side siblings like get_vas_order and list_vas_products. It stops short of explicitly contrasting with those siblings by name, but the intent is unambiguous.

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

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

Gives a concrete precondition (call list_vas_products first and use an available product and denomination) and an explicit when-not-to-act rule ('do not automatically retry an ambiguous result'). It does not say when to prefer this over the other purchase siblings (airtime/data/electricity), but the product naming makes those distinctions mostly self-evident.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context that the fetch is scoped to the authenticated account and is intended as a follow-up to creation, but it does not add further behavioral detail such as error handling or ordering guarantees.

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

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

The description is a single, front-loaded sentence with no redundant or filler content. Every clause contributes to purpose, timing, or parameter choice.

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

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

Given rich annotations, 100% schema description coverage, two simple parameters, and an output schema, the description provides enough context for correct invocation. The agent knows when to call it and how to identify the order.

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

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

Schema description coverage is 100%, and both parameters are documented in the schema. The description reinforces that the order can be fetched by request_id or orderno, but adds no format or example details beyond what the schema already provides.

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 (fetch), a specific resource (airtime order), and scope (authenticated account), while also naming how to identify it (request_id or orderno). This clearly distinguishes it from create_airtime_order and from sibling get_*_order tools for other resources.

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 use the tool: after create_airtime_order or after an ambiguous create result. It does not name when-not-to-use cases or alternative lookup paths, but the triggering context 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context about authenticated-account scope and reconciliation after ambiguous creates, but does not describe error behavior, permissions, or rate limits.

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

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

It is a single efficient sentence with no filler. The trigger condition, resource, and lookup keys are all 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?

The tool has an output schema, full parameter descriptions, and annotations covering safety and idempotency. The description supplies the remaining operational context needed 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 100%, and the schema's anyOf already documents that request_id or orderno is required. The description mirrors that either identifier can be used but adds no additional format or lookup semantics beyond the schema.

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

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

The description gives a specific verb and resource: fetch the authenticated account's data order. It also names the identifiers used to fetch it, making it distinguishable from sibling create/get tools for other order types.

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

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

It clearly states the triggering context: use after create_data_order or after an ambiguous create result. It does not explicitly contrast with alternative retrieval tools or state when not to use it, so it stops short of the top score.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds context beyond that: the call is scoped to the caller's authenticated account and is the intended remedy for a dangling/ambiguous create. It does not say what happens when none of the identifiers match an order (error vs empty), which keeps it short of a 5.

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

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

A single sentence with zero filler, front-loading the trigger condition before the lookup mechanics. Nothing repeats the annotations or the schema types.

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

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

An output schema exists, so return shape need not be described, and annotations cover the risk profile; what remains is the lookup contract, which the description mostly supplies. The only gap is failure behavior and identifier precedence when multiple keys could be passed.

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 names all three identifiers and implies a one-of choice, but the anyOf constraint is really conveyed by the schema. It gives no guidance on what a client_reference is versus an order_reference_id, format expectations, or which to prefer when several are known.

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 ('fetch') and resource ('authenticated account electricity order') and enumerates the three lookup keys accepted. It is clearly distinguishable from the create_* siblings and from the other get_*_order tools, which target different product types.

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 anchors usage to a lifecycle: 'after create_electricity_order, or after an ambiguous create result.' That names the sibling that precedes it and the exact situation (uncertain create outcome) that selects this tool, which is the kind of routing guidance agents need.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds useful context — the ordering dependency on send_sms and that the lookup is scoped to the authenticated account — but says nothing about eventual consistency or whether polling is needed for a 'pending' 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 sentence, no filler, with the precondition (after send_sms) front-loaded before the action. Nothing to trim.

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

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

A simple one-parameter read with an output schema for return values and annotations covering the safety profile — the description supplies the missing prerequisite and scope. Only the polling/freshness nuance is absent, which is minor for this tool's complexity.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning; it does so only minimally by tying sms_id to the SMS created by send_sms. The single integer parameter is largely self-explanatory from its name and type, so no more depth is strictly needed, but nothing is added about ID sourcing or validity.

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 (fetch) and resource (delivery status of an authenticated account SMS) and identifies the key (sms_id). Referencing send_sms as the predecessor clearly separates it from the sibling that creates SMS, though it doesn't differentiate itself from the other get_* retrieval 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?

'Use this after send_sms' gives an explicit precondition and context for invoking the tool. No exclusions or when-not-to-use guidance are given, but for a simple status lookup the trigger condition is unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds useful context: it confirms the read-only scope and explains the SMS success semantics ('successful only after a delivery receipt'), which is not captured by annotations. It does not mention rate limits or pagination behavior, but those are minor given the 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?

The description is two tight sentences: the first front-loads purpose and scope, the second covers required/optional parameters and the SMS nuance. No sentence is wasted.

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

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

With rich annotations, an output schema, and strong parameter descriptions, the description covers purpose, scope, date requirement, filtering, and SMS semantics. It omits pagination guidance and the 90-day range limit, but those are already covered in the schema, so the definition is sufficiently 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 80%, so the schema already documents date formats, the 90-day cap, cursor rules, and limit bounds. The description only restates that a date range is required and repeats that the type filter is comma-separated, adding little beyond the schema.

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

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

The description states a specific verb and resource ('retrieve read-only transaction history') and scopes it to the authenticated SIMcloud account across named channels. It is clearly distinguishable from sibling tools like get_airtime_order or get_wallet_balance, which handle single orders or balances.

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 usage context: date range is required and an optional service filter can narrow results. It does not explicitly name alternatives (e.g., 'use get_airtime_order for a single order'), so guidance is strong but not complete.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds two valuable facts beyond that: the lookup is confined to the authenticated account's own orders, and the tool is the recovery path after an ambiguous create response. It does not describe not-found behavior, which is the main remaining gap.

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

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

One sentence, usage trigger front-loaded, no filler. Every clause carries information.

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

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

For a simple read-only fetch with an output schema and full annotations, the description is nearly sufficient: it covers sequencing, auth scope, and both lookup keys. Only the not-found/ambiguity resolution semantics are left implicit.

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

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

Schema description coverage is 0%, so the description must carry the parameters and it only names them ('by order_id or transaction_id') without explaining that exactly one is required, the UUID format of transaction_id, or which key to prefer. It confirms the either/or lookup intent but adds no format or selection guidance beyond what the schema structure already encodes.

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 (fetch) and resource (VAS order) scoped to the authenticated account, and names the two lookup keys. It is trivially distinguishable from get_airtime_order, get_data_order and get_electricity_order, which are the obvious near-miss 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?

Gives an explicit trigger: use after create_vas_order, or after an ambiguous create result, naming the sibling to sequence with. It does not state when to prefer the other getters instead, but the resource specificity makes mis-selection unlikely.

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?

Adds domain context beyond the annotations by clarifying the balance is for the authenticated account and that calling it does not spend funds — reassuring for a wallet tool where an agent might fear side effects. Annotations already cover read-only/idempotent/no-destroy, so the remaining value is the no-charge guarantee and implicit auth requirement.

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

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

Two sentences, front-loaded with the usage trigger and followed by the return value and safety guarantee. 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?

An output schema exists, so return-shape detail is unnecessary; the description still tells the agent what conceptually comes back (available balance) and that it costs nothing. Currency/account-selection nuance, if any, is left to the output schema.

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 schema is empty and closed (additionalProperties false), consistent with the 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?

Names a specific verb and resource (get wallet balance) and scopes it to the authenticated SIMcloud account, which clearly separates it from the order/transaction siblings. It stops short of explicitly contrasting with history-type tools, but the resource is unambiguous.

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

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

Gives concrete triggering conditions: before a wallet-funded SIMcloud transaction, or when the user asks for their balance. No alternatives or exclusions are named, but no realistic alternative exists among the siblings for a balance read.

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 non-destructive, so safety is covered. The description adds that values are 'current' and 'available for API ordering', implying live fetchable inventory, but says nothing about pagination, empty results, or rate/coverage 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?

One sentence, front-loaded with the usage directive and then the resource and scope. No filler and nothing buried.

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

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

An output schema exists so return values need not be explained, there is only one optional parameter, and the description supplies the workflow context an agent needs. Slightly short only on what a filtered vs unfiltered result 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 100% and the sole parameter's description already explains accepted formats ('friendly network name or internal code, for example mtn or pd-mtn'). The description only adds that the filter is South-Africa-scoped and optional, which is marginal beyond the schema.

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

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

States a specific verb and resource ('list ... SIMcloud data bundle products'), and distinguishes itself from the sibling write tool and from list_vas_products by naming 'data bundle products' and 'sell values'. An agent can tell immediately what it returns conceptually.

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 prescribes sequencing ('Use this before create_data_order'), which is the key workflow signal. It does not explicitly exclude or compare against list_vas_products or lookup_network, so it falls short of the when/when-not bar.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description's only added behavioral detail is that results are filtered to 'active' products; it says nothing about auth/registration requirements or result cardinality.

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

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

A single sentence, front-loaded with the usage trigger before the resource description. No padding, no 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?

With an output schema present and zero parameters, the description only needs to convey purpose and call timing, which it does. The remaining gap is that it never clarifies its relationship to list_data_products or whether a registered SIMcloud user is a prerequisite.

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 for the description to explain — the baseline of 4 applies. The description correctly implies the call is unfiltered and returns the full product/denomination set.

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

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

States a specific verb (list), resource (SIMcloud VAS voucher products), and scope qualifier (active) plus the returned attribute (available denominations). It is clearly separable from the order-creation siblings, though it never explicitly contrasts itself with the near-identical list_data_products.

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?

Tells the agent exactly when to call it: before create_vas_order, implying it supplies the product/denomination values that create_vas_order needs. No when-not conditions or comparison to list_data_products are given, so it stops short of full routing 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 state this is not read-only and not destructive, and the description adds important context that the lookup is recorded in authenticated account history. That explains the non-read-only side effect and auth scoping, though it does not discuss idempotency or rate limits.

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

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

Two sentences, front-loaded with the primary use case and followed by the account-history side effect. There is no redundant or filler language.

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

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

For a one-parameter lookup with full schema coverage and an output schema, the description covers purpose, timing, auth context, and the recording side effect. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, including an explicit South African mobile number example, so the schema already carries parameter meaning. The description adds only that the number is for a South African network, without additional format or validation details beyond the schema.

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

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

The description states a specific verb and resource: identify the South African mobile network for a number. It also scopes the purpose to airtime, data, or SMS prep, which separates it from sibling order-creation and SMS-sending tools.

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

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

It gives a clear when-to-use condition: when the user needs the network before sending airtime, data, or SMS. It does not explicitly name alternatives or when-not-to-use cases, but the context strongly routes the agent away from create/send tools.

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

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

Annotations declare the mutation profile (destructive, open-world, non-idempotent), so the description need not restate safety. It does add real value: the account is created as a child of the authenticated account, and the response carries a child API token that must be stored securely and scoped to that child. It omits any warning that repeated calls create additional accounts, which is the one gap given non-idempotency.

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

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

Three tight sentences: purpose first, then the pre-call precondition, then the post-call handling of the returned token. Nothing is repeated from the schema and every sentence carries operational weight.

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 non-idempotent, destructive creation tool with 10 parameters, the definition covers purpose, prerequisites and the sensitive return value well. It stops short on the optional business/identity parameters and gives no guidance on what happens to the account after creation or on duplicate handling, leaving meaningful gaps for a tool of this complexity.

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

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

Schema description coverage is only 30% across 10 parameters, so the description carries the burden — but it only reiterates cell, email and password, which are already the documented fields. The seven undocumented parameters, particularly the optional vatno, address, id_number, business_reg and business_name, are never explained as to when they should be supplied or how they change the created account.

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

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

States a specific verb and resource ('Create a normal SIMcloud account under the authenticated account for a client application user') and scopes the account type and parent relationship. None of the sibling tools (orders, SMS, wallet, lookups) register users, so the distinction is unambiguous without opening the schema.

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

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

Gives a pre-call checklist ('Confirm that the person consents... and that their cell number, email and password are correct'), which implies when the tool is appropriate. However, it never states when not to use it, and with idempotentHint=false it gives no warning about duplicate registration on repeat calls. Usage context is 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?

Annotations already declare destructive, openWorld and non-idempotent, but the description adds materially new facts: the send is irreversible, it may spend wallet funds, and ambiguous outcomes must not be auto-retried. Those are exactly the operational risks an agent needs before invoking a spend-capable, non-idempotent 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 short sentences, front-loaded with the usage trigger, then confirmation prerequisite, then the irreversible/retry risk. No filler and no repetition of schema details.

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

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

An output schema exists so return values need no explanation, and the description covers auth, confirmation, cost and retry policy. It leaves a small gap: it does not point to get_sms_status as the way to resolve an ambiguous result, which is the exact scenario it warns about.

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

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

Schema description coverage is 100%, so both recipient and message (with min/max length) are already documented. The description only adds a geographic constraint on the recipient that the schema example implies anyway. Baseline 3 with the schema doing the heavy lifting.

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

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

States a specific verb and resource (send SMS) plus scope constraints: an authenticated SIMcloud user, a confirmed message, and a South African recipient. This is clearly distinguishable from siblings like get_sms_status or create_airtime_order.

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 explicit preconditions: authenticated user, confirmed recipient and message, South African destination. It also warns against automatic retry on ambiguous results. It stops short of naming the alternative (get_sms_status) for verifying an ambiguous send, so the routing guidance is implicit rather than explicit.

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