BulkSMS MCP by usefulapi

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

Annotations already declare write/destructive/idempotent, but the description adds value beyond them: a send to a blocked number fails with FAILED.BLOCKED and still costs credits, and the block is irreversible through the API. That reversibility and cost detail is not available from the annotations. No rate limits or response shape described, so not a full 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?

Three dense sentences with the write marker and core effect front-loaded, then the consequence, then the irreversibility warning, then the endpoint. Zero 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?

With annotations covering the safety profile and no output schema to explain, the description supplies everything an agent needs: side effects, irreversibility, cost implications, and endpoint. Nothing material is missing for a single-parameter mutation 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 coverage is 100%, so the international-format example is already in structured data (baseline 3). The description adds the cardinality constraint 'ONE phone number,' which matters because the 'bulksms' name might otherwise suggest batch input, but it adds no format or validation detail beyond the schema.

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

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

The description opens with a specific verb and resource ('adds ONE phone number to the account's blocked list') and states the exact effect, including the endpoint (POST /blocked-numbers). It is immediately distinguishable from the read-side sibling bulksms_list_blocked_numbers.

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 trigger condition ('do it only when the user asks for it') and a strong exclusion backed by consequences ('This API has no way to remove a block again'). An agent knows when to call this and when to hesitate, with the reason spelled out.

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 the description reinforces this with the GET /messages/{id} endpoint mapping, which is useful REST context. It stops there, disclosing nothing about auth requirements, rate limits, message retention, or error behavior for unknown ids.

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 front-loaded sentence naming the resource and returned fields, followed by a compact endpoint reference. No wasted words.

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 usefully enumerates the returned fields (body, recipient, delivery status, parts, credit cost), which is exactly what compensates for the missing return definition. Only auth/error behavior is unaddressed.

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 single message_id parameter is fully documented in the schema, including where ids originate. The description's 'by its id' adds no format or constraint detail beyond that baseline.

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

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

States a specific verb (get) and resource (one sent/received message) plus the fields returned, which clearly separates it from the singular-by-id case. It never names list_messages as the plural alternative, so the sibling contrast is only implicit rather than explicit.

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

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

Usage is implied: fetch one message when you already have its id. There is no statement of when-not to use it or why an agent would pick this over bulksms_list_messages, leaving the selection logic to inference from the schema note that the id comes from list_messages or send_message.

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, so the safety profile is covered; the description still adds boundary context by naming the fields included and explicitly excluding 'Company and billing details.' It does not mention auth requirements or any rate-limit behavior, but for a read-only profile endpoint that omission is minor.

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 dense sentence enumerating returned fields, front-loaded with the resource, plus a short endpoint note. Nothing is padded, though the trailing 'BulkSMS REST: GET /profile' line is developer bookkeeping rather than agent-facing guidance.

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 compensates well by listing the returned fields and the excluded ones. It stops short of describing response shape or failure behavior, but for a simple no-input profile read it is nearly sufficient.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly implies no input is needed, and nothing in the text contradicts the empty schema.

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

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

States a specific verb and resource ('Show the BulkSMS account') and then enumerates exactly which fields are surfaced: username, credit balance, credit limit, credit-transfer allowance, daily quota, and permitted sender ids. No sibling tool overlaps with account-profile retrieval, so 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?

Usage is only implied: a zero-parameter read of the current account naturally follows from the description, and no alternative siblings (e.g. message or block-list tools) could plausibly serve the same need. However, there is no explicit statement of when this should be called, e.g. before sending to check remaining quota, which would have added real routing value.

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 already covers the safety profile, so the description's job is to add context — which it does by explaining the provenance of entries (API, recipient STOP reply, BulkSMS) and the pagination contract. It stops short of auth requirements, rate limits, or return ordering, so it is not exhaustive.

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

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

Three tight sentences with the core purpose front-loaded, followed by the paging rule and the endpoint mapping. Nothing is redundant and nothing reads as 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 two-optional-parameter read-only list with no output schema, the description covers what is listed, where entries come from, and how to page. Minor gaps remain around returned fields and sort order, but an agent has enough 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 coverage is 100%, so baseline is 3, but the description genuinely adds value: it explains the cursor pattern ('min_id = the largest id of the previous page + 1'), which the schema only states as a bare threshold. That is real operational semantics beyond the structured field.

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 (List) plus resource (blocked numbers), and it goes further by defining what a blocked number means — a number the account may not send to — and enumerating the three ways entries get there. An agent immediately understands the content and can distinguish it from bulksms_block_number or the other list 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?

Usage is implied rather than stated: the agent can infer you call this to audit who cannot be messaged, and the paging instruction gives operational guidance. However, there is no explicit when-to-use statement, no mention of bulksms_block_number as the mutation counterpart, and no exclusions or prerequisites.

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

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

readOnlyHint=true already establishes the safety profile, and the description adds genuinely useful behavior: the newest-first default ordering, the 7-day implicit window that silently truncates results, and the two cursor conventions. These are non-obvious traits an agent could not infer from 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?

Four sentences, front-loaded with what the tool returns, then constraints, then paging, then the REST mapping. Reasonably tight, though the cursor explanation duplicates what the schema already says for before_id/after_id.

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 10-parameter read-only list with no output schema, the description covers ordering, the window constraint, and paging well enough to call correctly. It does not describe the returned message shape or pagination termination (how the agent knows it has reached the end), which are the remaining gaps.

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

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

Schema description coverage is 100%, so all ten parameters are already documented in the schema, including enum meanings and paging cursors. The description largely restates the before_id/after_id mechanics rather than adding format or constraint detail beyond the schema, so the 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?

Specific verb+resource with scope: 'List sent (SENT) and received (RECEIVED) SMS messages, newest first by default', plus the underlying REST endpoint. It does not, however, differentiate itself from the sibling bulksms_list_replies, which an agent could reasonably confuse with the RECEIVED half of this listing.

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 real operational context: the 7-day default window and the condition that lifts it (submission_date_from), plus which paging cursor to use under each sort_order. It stops short of stating when to prefer this tool over bulksms_list_replies or bulksms_get_message.

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 readOnlyHint already covering the safety profile, the description adds meaningful behavior: replies must be RECEIVED, they are linked to a sent message id, only REPLIABLE senders produce them, and an empty list is ambiguous. It does not cover pagination or rate limits, but it goes beyond the annotation.

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 definition is compact and front-loaded: it states the action, the key constraint, empty-list semantics, and the underlying REST endpoint in three efficient sentences. 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?

For a simple read-only list tool with one fully described parameter and no output schema, the description covers the important edge cases: RECEIVED-only results, REPLIABLE sender requirement, and empty-list meaning. It is complete enough 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 description coverage is 100% and the single parameter is fully documented in the schema as the SENT message id. The description reinforces that meaning but adds no syntax or format 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: list received replies linked to a sent message id. It distinguishes the result from general message listing by tying replies to a sent message and noting the REPLIABLE sender constraint.

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: only messages sent with a REPLIABLE sender have linked replies, and an empty list can mean no replies or an unknown id. It does not name alternative sibling tools to use for other message queries, so it falls short of explicit when-not/alternatives guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered, but the description adds real value: it discloses that only the host of each webhook URL is returned (path/query may hold a secret) and confirms this server never mutates webhooks. That redaction behavior is not derivable from the schema or 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?

Three short sentences that are front-loaded with the core action before the redaction caveat and the REST mapping. The trailing 'GET /webhooks' line is slightly redundant but adds traceability without bloat.

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

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

With zero parameters and no output schema, the description compensates by listing the returned fields and flagging the URL-host redaction. An agent knows exactly what it gets back and what it does not, so nothing needed to call it 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 tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly focuses on what comes back rather than inventing parameter 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?

States a specific verb and resource ('List the account's webhooks') and enumerates the returned fields (name, trigger SENT/RECEIVED, active flag, invoke option). This distinguishes it cleanly from siblings like bulksms_list_messages or bulksms_list_blocked_numbers.

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

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

Usage is implied by the clear scope, but there is no explicit when-to-use or when-not guidance, and no alternative tool is named (there is no sibling webhook tool to route to). The read-only note gives a mild cue that this is a safe inspection 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 declare destructive/openWorld/non-idempotent, and the description goes well beyond them: irreversibility, the credit-cost formula, that blocked numbers still cost credits, that template placeholders are rejected, and that non-GSM characters become '?' unless auto_unicode is set. This is exactly the behavioral context an agent needs before spending money.

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?

Dense but front-loaded: the WRITE/irreversible/spends-credits warning leads, and cost and encoding caveats follow. Slightly over-packed and repeats the +447700900000 example already in the schema, but nearly every sentence 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 destructive, cost-incurring tool with no output schema, the description covers cost accounting (creditCost on sent messages), irreversibility, validation failures, encoding behavior, and recipient limits. Nothing needed to invoke it safely 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%, so baseline is 3, but the description adds genuine value beyond the schema: the cost model tied to parts and recipients, the shorter-part/higher-cost tradeoff for auto_unicode, and the ban on {F0###}/{fn###}/{sn###} placeholders in body. Only the recipient-format example duplicates 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?

Opens with a specific verb and resource ('SENDS REAL SMS'), names the write nature and the resource it consumes (credits), plus the underlying REST call. It is easily distinguished from siblings like list_messages, get_message, and block_number.

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 operating guidance ('Only send what the user explicitly asked for, confirm the text and recipients first') and excludes unsupported modes ('No groups, no scheduling'). It does not name sibling tools as alternatives, but there is no competing send tool, so the routing is effectively complete.

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