Africa's Talking MCP by usefulapi

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

The annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, and the description adds substantial behavioral detail beyond them: oldest-first ordering, default batch size, the pagination loop, and response fields such as has_more, count, and next_last_received_id.

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: it establishes the resource and ordering, then explains pagination mechanics, filters, and the endpoint without wasted text. Every sentence contributes to correct 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?

There is no output schema, so the description needed to sketch return behavior; it does so by naming has_more, count, and next_last_received_id. It does not describe the message payload fields or auth requirements, but it is otherwise sufficient for a read-only paginated fetch tool.

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

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

Schema description coverage is 100%, so the per-parameter meanings are already well documented. The description adds cross-call meaning for last_received_id, including how to use next_last_received_id and when to stop based on count, which goes beyond the schema's individual field descriptions.

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: fetching incoming SMS received on shortcodes/numbers. It also specifies ordering and batch behavior, and 'incoming' clearly distinguishes it from the send_sms sibling without needing to name it.

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 pagination usage: start with last_received_id=0, then pass next_last_received_id from the previous reply, and keep calling until count is 0. Optional shortcode and keyword filters are noted, but it does not explicitly name an alternative tool or a when-not-to-use case.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond the annotations: it is a GET lookup, it returns status/amount/destination/discount, and it is keyed by the original send response id. It does not discuss error cases, rate limits, or auth requirements, but those are secondary for a simple read endpoint.

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 one compact sentence that front-loads the purpose, identifier origin, returned fields, and HTTP method. Every clause adds value with no filler.

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

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

For a single-parameter read tool, the description is complete: it identifies the lookup key, its source, and the key result fields. With annotations covering safety and a 100%-covered schema, no critical agent-facing information 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 the single parameter is already documented with an ATPid_ example. The description adds useful semantic origin by noting this is the requestId/ATPid_ from a send reply, which helps an agent know where to get the value. That goes slightly beyond the schema, though the schema already carries most of the burden.

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

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

States a specific verb and resource: look up an airtime transaction by transaction id. It names the exact identifier format (requestId / ATPid_...) and enumerates the returned fields, making it easy to distinguish from `africastalking_send_airtime` and `africastalking_find_mobile_data_transaction`.

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

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

The description clearly establishes the usage context: the transaction id comes from a send reply, so this tool is for checking a previously submitted airtime transaction. It does not explicitly state when not to use this tool or name the sibling finder for mobile data, but the intended scenario 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=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by identifying the GET endpoint and the fields returned, though it does not discuss not-found behavior or rate limits.

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

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

The description is two compact sentences: the first front-loads purpose and returned data, and the second adds the endpoint. There is no redundant or wasted text.

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 lookup, the description provides the operation, source of the identifier, and returned fields. No output schema exists, and the listed return fields adequately compensate.

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

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

Schema description coverage is 100%, so the parameter is already documented. The description adds provenance by noting the transactionId comes from a send reply, which helps an agent know where to obtain the required value.

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

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

The description uses a specific verb and resource: "Look up a mobile data transaction" by transactionId. It also names the returned fields (status, product, destination, cost) and the endpoint, which clearly distinguishes it from the sibling airtime transaction tool.

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 context for use: the transactionId comes "from a send reply", implying this is a follow-up lookup after sending mobile data. It does not explicitly name alternatives such as find_airtime_transaction, but the mobile-data scope makes the intended use 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=true, destructiveHint=false and openWorldHint=true. The description adds real context beyond them: a concrete return payload example, the sandbox-has-no-balance caveat, and the underlying endpoint GET /version1/user. It stops short of covering auth requirements or error behavior.

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

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

Three short, front-loaded fragments with no filler, and the sample response is the most useful single piece of information. The telegraphic style and inline JSON are slightly rough but every element earns its place.

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

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

With no output schema, the example response carries the return-value burden, and the sandbox caveat prevents a common misuse. Missing are auth/prerequisite context and any mention of failure modes, which matters given openWorldHint=true implies an external network dependency.

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

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

Zero parameters, so there is nothing for the schema or description to disambiguate; baseline applies. The description correctly implies a parameterless call.

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 the specific resource (the Africa's Talking app balance for the SMS/airtime wallet) and the parenthetical 'SMS/airtime wallet' implicitly separates it from the sibling get_mobile_data_wallet_balance. The verb is carried by the title rather than the description text, and no sibling is named explicitly, so it falls short of a 5.

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

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

Usage is only implied: an agent infers 'call this to check SMS/airtime credit'. The note that 'The sandbox app has no balance' is a valuable precondition, but there is no explicit when-not guidance and no routing to get_mobile_data_wallet_balance for data-wallet balances.

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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value by showing a sample success payload ({"status": "Success", "balance": "KES 500.0000"}) and the underlying endpoint, but says nothing about failure modes, auth requirements, or currency/locale behavior.

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

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

Two compact fragments, both front-loaded with the resource and a concrete example. The raw endpoint string is marginally useful, but nothing here is padding.

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

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

For a no-argument read tool with a safety annotation and no output schema, the inline sample response is the one thing the description needed to supply and it does. Only error behavior and prerequisites are unstated, which is a minor gap.

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

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

Zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies.

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

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

Names the specific resource (mobile data wallet balance) and includes a concrete sample return payload, which makes it distinguishable from africastalking_get_balance. It never states the verb explicitly or contrasts itself with the sibling that returns the general account balance, so an agent must infer the distinction from the name alone.

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

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

There is no guidance on when to call this versus africastalking_get_balance or the data-transaction finder tools. The only usage cue is the implicit one carried by the name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'a read: nothing is changed' restates structured data. What does add value is the 'Live apps only' scope limit and the note that this is a POST endpoint performing a read, which prevents an agent from assuming a side effect from the HTTP verb. No auth, rate-limit, or empty-queue behavior is described.

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 fragments, result described first, then eligibility, then a clarifying note on the HTTP verb. Every clause carries information; nothing is padded.

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

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

With no output schema, the description does at least say the return is a per-number queue count, and annotations cover the safety profile. Minor gaps remain around what an empty queue or an unowned number yields, but the definition is sufficient 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?

There is a single parameter with 100% schema coverage, including a regex pattern and a 1-20 item range, so the schema carries the load. The description adds nothing about the phone_numbers array beyond 'your voice numbers'. Baseline 3 applies.

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

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

States a specific resource and quantity: 'Number of outbound calls currently queued on each of your voice numbers', plus the underlying endpoint. No sibling tool touches voice queues, so an agent can pick it out immediately 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?

The 'Live apps only' qualifier gives one real eligibility constraint, and the implied context (check queue depth on your own numbers) is inferable. But there is no explicit when-to-use, no when-not-to-use, and no named alternative.

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, open-world, non-idempotent writes, and the description adds substantially more: the call is billed and rings real phones, the confirm gate exists to protect credit, the sandbox has no voice service, and the per-number queue status return. This is the kind of cost and side-effect context an agent needs before a destructive write.

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

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

Opens with the WRITE marker and the core action, then layers cost, confirmation, environment limits, and return shape in dense, waste-free sentences. Every clause carries operational information.

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

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

With no output schema, the description still tells the agent what comes back (per-number queue status), and it covers the billing, confirmation, and environment caveats. Nothing an agent needs in order to call this destructive write 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?

Schema description coverage is 100%, so every parameter is already documented with format and constraints. The description reinforces 'up to 10 phone numbers' and that call_from must be an Africa's Talking voice number, but adds little beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb and resource ('place an outbound voice call'), plus concrete scope ('from one of your Africa's Talking numbers to up to 10 phone numbers'). That is clearly distinguishable from the SMS, airtime, and mobile-data siblings 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?

Gives strong preconditions: confirm=true only after the user approved the numbers, and live apps only because the sandbox has no voice service. It also explains where the spoken content originates (the dashboard callback URL). It stops short of naming an explicit alternative when voice is unavailable, so it falls 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?

Goes well beyond the annotations: discloses that credit is spent immediately, that the operation cannot be reversed, that idempotency_key makes retries safe (particularly useful given idempotentHint=false), and that it returns per-number status plus requestId. Annotations already flag destructiveHint, but the description supplies the operational consequences.

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

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

A single dense paragraph with the write-risk warning and the credit-spend caveat front-loaded, followed by prerequisites, currency semantics, retry guidance, and return shape. Every sentence carries information; the endpoint string is the only arguable 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 destructive, non-idempotent financial mutation with no output schema, it covers the safety gate, reversibility, idempotency, currency units, batch limit, return shape, and follow-up path. Nothing an agent needs before invoking it 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 67%; the description adds meaning the schema lacks, notably that amounts are denominated in the given ISO currency and gives examples (KES, UGX, TZS) where the schema only has an uppercase-3-letter pattern. The idempotency_key and confirm semantics largely restate what the schema already documents well.

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 ('top up mobile airtime') with an explicit scope (up to 25 phone numbers) and a WRITE marker, which cleanly separates it from send_sms, send_mobile_data, and read-only siblings like get_balance.

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 for calling (confirm=true only after the user approved each number and amount) and routes follow-up to africastalking_find_airtime_transaction. It does not explicitly distinguish when to pick this over send_mobile_data, but the resource difference makes that reasonably 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?

Goes well beyond the annotations by disclosing the financial consequence (spends wallet credit), irreversibility (cannot be reversed), a hard 25-recipient cap, the origin of product_name, and the shape of the return value. The retry guidance complements idempotentHint=false rather than contradicting it — the call itself is not idempotent, but a supplied key makes duplicates safe.

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?

Every sentence carries a distinct fact — write semantics, cost, confirm gate, product_name origin, idempotency, return shape, endpoint. The destructive/cost warning is front-loaded where an agent will see it first.

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

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

No output schema exists, so the description explicitly states what comes back (per-number status and transactionId) and where to look it up. Combined with the cost, irreversibility, and confirmation requirements, an agent has everything needed to call this safely.

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 already 75%, yet the description adds meaning: product_name must pre-exist in the Africa's Talking dashboard, confirm is a user-approval gate rather than a plain boolean, and the 25-number ceiling on recipients. It doesn't explain unit/validity enums, but those are self-describing.

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

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

Specific verb and resource: "send mobile data bundles to up to 25 phone numbers from your Africa's Talking data wallet." The resource is clearly distinct from the sibling send_airtime and send_sms tools, so an agent can select it without opening a schema.

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

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

Explicit preconditions are given: confirm=true only after the user approved each number and bundle, and an idempotency_key for safe retries. It also routes to africastalking_find_mobile_data_transaction for the resulting transaction. It stops short of naming when to prefer send_airtime or send_sms instead, so no explicit alternatives clause.

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?

Goes well past the annotations (destructive, non-idempotent, open-world) by disclosing that real credit is spent, that messages reach real phones while the sandbox app only hits the simulator, that the call is never retried, and what the vendor returns including statusCode 101. This is exactly the behavioral context an agent needs before an irreversible spend.

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 dense sentences, front-loaded with the WRITE marker and the core action, then prerequisites, then return shape, ending with the endpoint. Nothing is redundant with the title or schema.

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

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

With no output schema, the description correctly takes on the return contract (per-recipient status, statusCode 101, message ids, cost) and pairs it with the safety prerequisite and non-retry semantics. An agent has everything needed to call this safely and interpret the result.

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 all four parameters (to, message, confirm, sender_id) are fully documented in structured data, setting the baseline at 3. The description reinforces the confirm gating and recipient cap but adds no new parameter-level detail such as format or defaults.

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?

Opens with a specific verb-resource pair ('send one text message') plus the scope limit (up to 100 phone numbers). The resource (SMS text) is inherently distinct from the send_airtime, send_mobile_data and make_voice_call siblings, so an agent can select it 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?

Explicitly states the prerequisite for use: confirm=true only after the user approved the exact recipients and text. It also clarifies the sandbox-vs-live distinction. It stops short of naming when to use a sibling tool instead, 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.