MCP server for JoltSMS — provision dedicated real-SIM US phone numbers and receive SMS/OTP codes through AI agents.
Built on the Model Context Protocol, this server gives AI agents (Claude Code, Claude Desktop, Cursor, etc.) the ability to rent phone numbers, wait for incoming SMS, extract OTP codes, and manage billing — all through standardized tool calls.
Create a JoltSMS account and generate an API key at Dashboard → Settings → API Keys.
Add to your .mcp.json (Claude Code) or MCP settings (Claude Desktop, Cursor):
{
"mcpServers": {
"joltsms": {
"command": "npx",
"args": ["-y", "@joltsms/mcp-server@2"],
"env": {
"JOLTSMS_API_KEY": "jolt_sk_your_key_here"
}
}
}
}Your AI agent now has access to all 12 JoltSMS tools. Try:
"List my saved cards, then rent the next available number using the card I choose."
Related MCP server: @saperly/mcp
Tool | Description |
| List active numbers with service labels, tags, and unread counts |
| Full details for a single number |
| Set service label, tags, or notes on a number |
| List masked saved cards and payment method IDs |
| Rent the next available number, optionally using a selected saved card ($50/mo) |
| End auto-renew at period end, or cancel an unpaid initial checkout |
| List recent SMS with parsed OTP codes and message IDs |
| Reply to an eligible inbound message (up to 15 characters) |
| Mark single or bulk messages as read |
| Poll until an SMS arrives (key tool for OTP flows) |
| Get the most recent parsed verification code |
| Check up to 10 subscriptions with billing health |
The most common use case — automated phone verification:
1. joltsms_provision_number({ payment_method_id: "pm_chosen_from_saved_cards" })
→ Number provisioning started! Use joltsms_list_numbers to check when it is ACTIVE.
2. joltsms_list_numbers({})
→ Once provisioning completes: +16505551234 (ACTIVE)
3. joltsms_update_number({ number_id: "+16505551234", service_name: "PayPal" })
→ Tagged for easy lookup later
4. [Agent enters phone number on PayPal and requests OTP]
5. joltsms_wait_for_sms({ number_id: "+16505551234", timeout_seconds: 120 })
→ SMS received after 8.2s: "Your PayPal code is 847291"
→ OTP Code: 847291
6. joltsms_mark_read({ number_id: "+16505551234" })
→ Inbox clean
7. [Agent enters 847291 on PayPal — verification complete]Variable | Required | Description |
| Yes | Your API key ( |
| No | API base URL (defaults to |
A patched Node.js release: 22.23.4+ within 22.x, 24.22.1+ within 24.x, or 26.12.1+ within 26.x
A JoltSMS account with a payment method on file
If payment authentication is required, open the hosted invoice URL returned by the tool
SMS replies require an API key with the SMS replies capability
Version 2.0.1 requires the October 21, 2026 Node.js security patches. It checks the Node runtime at startup and exits with an upgrade message on an older patch, unsupported major, or prerelease. npm's engine warning alone does not enforce this requirement.
For npx installations, update Node on the machine that launches your MCP client,
check node --version in that environment, then restart the MCP connection.
Clients can use a different PATH from your terminal; ensure their environment
selects the patched Node binary too. Installing a new npm package does not
replace Node itself. The Docker build uses node:22.23.4-slim in both stages;
rebuild and replace existing containers to use the patched runtime.
The API key, executable names, and all 12 tools are unchanged.
Use one of the patched Node.js versions above, change a pinned MCP configuration to
@joltsms/mcp-server@2, and restart the MCP connection. Your existing JoltSMS API
key and the mcp-server / joltsms-mcp executable names still work.
Area codes are not selectable. Remove the old area_code argument: rentals use
the next available dedicated U.S. mobile number. Each provisioning call orders
one number; grouped checkout remains in the dashboard.
To choose a saved card, call joltsms_list_payment_methods, let the user select
one, and pass its payment_method_id to joltsms_provision_number. Omitting it
uses a valid account default or the sole saved card. If authentication is needed,
the tool returns a hosted invoice URL and a pending subscription ID. An abandoned
unpaid checkout can be canceled with joltsms_release_number; paid rentals retain
service until the customer billing period ends.
Number details show customer service-through and next-charge/retry dates
separately. Provider rental expiry is not a customer service end date. The number
list and billing summary display at most 10 entries; use joltsms_get_number to
look up a specific number on larger accounts, or use the dashboard for the full
list.
Replies target an existing inbound message ID. They do not accept an arbitrary destination or enable outbound campaigns.
npm ci --ignore-scripts
npm test
npm run test:package
npm audit --audit-level=lowSee RELEASING.md for source synchronization, compatibility checks, and the separate npm and MCP Registry publication steps.
MIT
Check billing and subscription status for all your JoltSMS numbers.
Shows each subscription with billing health, price, renewal/cancellation dates, and auto-renew status. Cross-references with phone numbers for easy identification.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max subscriptions to show (1-10, default 10) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully enumerates the return fields (billing health, price, renewal/cancellation dates, auto-renew status), but does not disclose read-only nature, auth requirements, pagination, or that the 'all your numbers' claim is capped by the limit parameter (max 10).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the purpose, then return details and identification context. Every sentence earns its place with no redundancy.
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 status tool with one optional parameter, the description explains what is returned, compensating for the missing output schema. However, it does not reconcile the 'all' scope with the 1–10 limit, leaving a small completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single optional limit parameter is fully described in the schema (100% coverage), so the baseline of 3 applies. The description adds no syntax or meaning beyond the schema, and its 'all your numbers' phrasing slightly conflicts with the limit cap.
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 'Check' and resource 'billing and subscription status' scoped to JoltSMS numbers. It implies a distinct resource from sibling number-management tools, though it does not explicitly name an alternative, so it falls just short of full sibling differentiation.
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 no when-to-use guidance, prerequisites, or alternatives. An agent must infer from the purpose alone that this is the tool for billing status, with no exclusions stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the most recent parsed OTP code from a phone number.
Convenience tool — checks recent messages (last 10 minutes by default) for a parsed verification code. If no parsed code is found, returns the most recent message body for manual extraction.
Use joltsms_wait_for_sms if you need to wait for an OTP that hasn't arrived yet.
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | Only look at messages after this ISO 8601 datetime. Defaults to last 10 minutes. | |
| number_id | Yes | Number ID (UUID) or phone number (e.g. +17243213654 or 7243213654) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the description carries the burden and delivers the non-obvious behaviors: the default 10-minute lookback window and the fallback that returns the raw message body when no code is parsed. It does not cover error paths (e.g. number not provisioned), whether reading marks messages as read, or the exact return shape, so it falls short of full disclosure.
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 paragraphs, front-loaded with the core purpose, then the fallback behavior, then the routing hint. Every sentence carries distinct information with no 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?
Given a simple two-parameter read tool with no annotations and no output schema, the description covers purpose, default window, no-result fallback, and the sibling alternative. It leaves the exact response shape and edge-case failures undefined, which is a minor but real gap for a code-extraction 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 both parameters (since, number_id) are already fully documented in the schema. The description's mention of the 10-minute default duplicates what the 'since' schema entry already states, adding no new syntax or format detail.
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 ("Get the most recent parsed OTP code from a phone number") plus the scoping nuance that it looks at the last 10 minutes. This distinguishes it from the message-listing siblings and from joltsms_wait_for_sms without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative ("Use joltsms_wait_for_sms if you need to wait for an OTP that hasn't arrived yet") along with the condition that selects it. It also frames itself as a convenience path for already-arrived codes, so the when/when-not split is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details for a single phone number, including service label, tags, notes, message counts, billing dates, and subscription status.
Accepts a UUID or phone number (e.g. "+16505551234", "650-555-1234", "(650) 555-1234").
| Name | Required | Description | Default |
|---|---|---|---|
| number_id | Yes | Number ID (UUID) or phone number (e.g. +17243213654 or 7243213654) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose the response content (the fields it returns), which is useful, but says nothing about permissions, error behavior for a non-existent number, rate limits, or whether the lookup is scoped to the account.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and result set, then the accepted input formats. The field enumeration is slightly long but each item tells the agent what it will receive, so little 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 no output schema, the description compensates by listing the returned fields, which is exactly what an agent needs to decide whether to call it. The remaining gap is behavioral (auth/error handling) rather than structural.
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, but the description adds genuine meaning beyond the schema's single example by listing accepted input shapes: UUID, E.164 ('+16505551234'), dashed ('650-555-1234'), and parenthesized ('(650) 555-1234'). This tells the agent the lookup tolerates human-formatted numbers.
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 ('a single phone number') and enumerates the exact payload (service label, tags, notes, message counts, billing dates, subscription status). This clearly separates it from the list/update/provision siblings without needing to name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the word 'single' hints that this is the per-number lookup counterpart to joltsms_list_numbers, but no explicit when-to-use, when-not, or alternative is given. No prerequisites or conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent SMS messages received on your JoltSMS numbers.
Returns sender, body, parsed OTP code (if detected), and timestamps. Use number_id to filter to a specific number, or omit for all numbers. Use from_filter for exact-match sender filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max messages to return (1-10, default 10) | |
| since | No | ISO 8601 datetime — only return messages after this time. Example: "2025-01-15T00:00:00Z" | |
| cursor | No | Pagination cursor from previous response | |
| number_id | No | Filter by number ID (UUID) or phone number (e.g. +17243213654 or 7243213654). Omit for all numbers. | |
| from_filter | No | Filter by sender phone number (exact match, e.g. "+18005551234") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses what comes back (sender, body, parsed OTP code if detected, timestamps), which is real value given there is no output schema, but it says nothing about ordering, pagination limits, rate limits, or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with purpose, then return contents, then filtering hints; no filler. The final two sentences partly repeat schema content, which keeps it from being maximally lean.
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 read-only list tool with no annotations and no output schema, the description adequately covers purpose, returned fields, and basic filtering. It omits ordering/recentness semantics and pagination behavior (the cursor param is left entirely to the schema), leaving gaps an agent would want filled.
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 schema already documents limit, since, cursor, number_id, and from_filter thoroughly. The description restates number_id and from_filter semantics without adding format or edge-case detail beyond the schema, which matches the baseline 3.
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 recent SMS messages received on your JoltSMS numbers') with the scope (all numbers or filtered) made explicit. It is clearly distinguishable from get_latest_otp and wait_for_sms in spirit, but the description never names or contrasts those siblings, 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?
It gives parameter-level routing advice ('Use number_id to filter to a specific number, or omit for all numbers') but no tool-selection guidance against the many sibling readers (joltsms_wait_for_sms, joltsms_get_latest_otp, joltsms_mark_read). Usage is implied rather than framed as when-to-use/when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your active JoltSMS phone numbers. Returns phone number, status, service label, tags, message count, and subscription details.
Each number costs $50/month and receives unlimited inbound SMS with parsed OTP codes.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max numbers to return (1-10, default 10) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It helpfully discloses the cost ($50/month) and unlimited inbound SMS with parsed OTPs, but never states that this is a read-only operation, whether authentication is required, or how the default limit of 10 truncates results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the action and the concrete return fields, followed by the pricing/inbound detail. 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?
Since no output schema exists, the description appropriately enumerates the returned fields (number, status, service label, tags, message count, subscription). The only real gap is truncation/pagination behavior, which neither the description nor the schema addresses.
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 limit parameter is fully documented in the schema (range 1-10, default 10). The description adds no additional semantics about limit or pagination, 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?
States a specific verb and resource ("List your active JoltSMS phone numbers") and enumerates the returned fields, so the agent knows exactly what it gets back. It does not explicitly differentiate itself from joltsms_get_number or the other list-style siblings, 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?
There is no when-to-use or when-not-to-use guidance and no mention of the obvious alternative (joltsms_get_number for a single number). The word "active" hints at a filter, but nothing tells the agent under what circumstances this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List masked saved cards so the user can choose which card funds a number rental.
Returns card brand, last four digits, expiration, default status, and a payment_method_id. Never returns full card numbers or CVC.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max saved cards to return (1-100, default 25) | |
| cursor | No | Pagination cursor from the previous response |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does real work: it enumerates the return fields and gives an explicit security guarantee ('Never returns full card numbers or CVC'), which an agent cannot derive from the schema. It stops short of stating permission requirements or pagination 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 tight sentences, zero filler, and the purpose plus the key privacy constraint are front-loaded before the return-field list.
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 correctly compensates by listing the returned fields and the payment_method_id. It omits any note on ordering, pagination continuation, or auth context, which are minor but real gaps for a paged list 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% – limit and cursor are fully documented in the schema with ranges, defaults, and meaning. The description adds no syntax or semantics beyond that, 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?
States a specific verb and resource ('List masked saved cards') and adds the intent behind the call ('so the user can choose which card funds a number rental'). This is unmistakably distinct from the number, message, and OTP 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?
The purpose clause implies the usage moment (choosing a funding card for a number rental), but it never names a workflow sibling such as joltsms_provision_number or states a prerequisite. Usage is inferable, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark messages as read. Provide exactly ONE of:
message_id: Mark a single message as read (UUID)
number_id: Mark ALL messages on a number as read (UUID or phone number)
Use after extracting an OTP to keep the inbox clean.
| Name | Required | Description | Default |
|---|---|---|---|
| number_id | No | Mark ALL messages on this number as read. Accepts UUID or phone number. Provide exactly one of message_id or number_id. | |
| message_id | No | Mark a single message as read by its UUID. Provide exactly one of message_id or number_id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses scope — number_id marks ALL messages on a number, which is a real side effect — but says nothing about reversibility, idempotency, permissions, or what a failed/missing id returns. Partial behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the action in one line, then uses a tight bulleted structure for the two mutually exclusive modes, and closes with the motivating use case. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with no output schema, the essentials are present. The gap is minor: the schema permits an empty object while the description demands exactly one argument, and no confirmation/return behavior is described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters including accepted formats (UUID or phone number). The description restates the same information rather than adding syntax, defaults, or edge-case meaning beyond 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 ('Mark messages as read') and immediately differentiates the two granularities: single message via message_id versus all messages on a number via number_id. An agent knows exactly what this does 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 clear context ('Use after extracting an OTP to keep the inbox clean') and enforces the mutual-exclusion rule ('Provide exactly ONE of'). It does not name a when-not condition or point to a sibling alternative, but there is no competing mark-read tool in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rent the next available dedicated real-SIM US phone number ($50/month).
Optionally pass payment_method_id from joltsms_list_payment_methods. Omit it to use the valid account default or the sole saved card.
Provisioning is async — the number may take seconds to minutes to become ACTIVE. Specific area codes are not currently selectable.
If 3DS authentication is required, this tool returns a URL the user must visit to authorize payment.
| Name | Required | Description | Default |
|---|---|---|---|
| payment_method_id | No | Saved card ID from joltsms_list_payment_methods. Omit to use the valid account default or the sole saved card. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses recurring cost ($50/month), async provisioning with realistic latency ('seconds to minutes to become ACTIVE'), the unavailability of area-code selection, and the 3DS payment-authorization URL flow. It stops short of stating reversibility or what happens on provisioning failure.
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 core action and cost are front-loaded, followed by four short, non-overlapping sentences covering payment, async timing, a known limitation, and the 3DS branch. No sentence is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description covers the critical unknowns: billing, latency, area-code limitation, and the 3DS return path. It leaves the normal success payload (e.g., the new number ID/phone number) unspecified, which would help an agent chain into joltsms_get_number.
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 optional parameter is fully documented in the schema. The description restates the same omit/default rule rather than adding new semantics such as format, source, or failure behavior for an invalid ID, 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?
States a specific verb and resource with full qualification: 'Rent the next available dedicated real-SIM US phone number ($50/month).' This clearly distinguishes it from siblings like joltsms_list_numbers, joltsms_release_number and joltsms_update_number, which operate on numbers the agent already holds.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent to joltsms_list_payment_methods for the payment_method_id and explains the omit-to-use-default behavior, which is real selection guidance. It does not, however, state when this tool is preferable to alternatives such as joltsms_get_number or joltsms_update_number when the user already has a number.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel/release a rental. Paid numbers stay active until the end of the current billing period; abandoned unpaid initial checkouts are canceled immediately.
Requires the subscription ID from joltsms_list_numbers, or the pending subscription ID returned for an unpaid 3DS checkout. Paid rentals disable auto-renewal and release at period end; unpaid initial checkouts end immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| subscription_id | Yes | Subscription ID from joltsms_list_numbers, or the pending subscription ID returned for an unpaid 3DS checkout |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does so well: it discloses that paid numbers persist until end of billing period, that auto-renewal is disabled on release, and that unpaid initial checkouts are canceled immediately. The timing semantics are the key behavioral trait here and are clearly stated.
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 purpose is front-loaded, which is good, but the paid-vs-unpaid timing rule is stated twice — once in the first paragraph and again in the final sentence — making it redundant. Trimming the duplicate would leave a tighter definition.
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, annotation-free tool with no output schema, the description covers the important lifecycle semantics (release timing by billing state). It does not say what happens to the number or its messages after release, but nothing an agent needs to invoke 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?
Schema description coverage is 100% and the description repeats the same sourcing guidance already in the schema's subscription_id description. It adds no new syntax or format detail, so the baseline 3 for full schema coverage 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?
The description opens with a specific verb and resource: 'Cancel/release a rental.' An agent can immediately tell this is the inverse of a provisioning/rental tool. It does not explicitly name a sibling it is distinct from, but the action 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?
It tells the agent where the required ID comes from (joltsms_list_numbers, or the pending subscription ID from an unpaid 3DS checkout), which is useful routing context. However, it never states when NOT to use this tool or contrasts it against siblings like joltsms_update_number, leaving the choice to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reply to an existing inbound SMS by message ID.
The recipient is resolved server-side from the original inbound message. This tool cannot send to an arbitrary phone number and does not accept a destination field. Requires an API key created with the SMS replies capability.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | SMS reply content, max 15 characters. No destination can be provided. | |
| message_id | Yes | Inbound SMS message UUID to reply to. The recipient is resolved server-side from this message. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the server-side recipient resolution, forbids a destination field, and states an auth prerequisite ('API key created with the SMS replies capability'). It omits delivery behavior, failure modes, and whether the reply is queued or sent synchronously.
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 purpose, then the routing constraint, then the auth requirement. Slight redundancy with the schema on server-side recipient resolution, but no wasted 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 2-parameter mutation with no output schema and no annotations, the description covers purpose, routing constraint, and auth. The main remaining gap is expected return/failure behavior, but this is a simple tool and nothing essential to 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 description coverage is 100%, so both parameters are already documented in the schema, including the server-side recipient resolution and the 'no destination' note. The description reinforces but adds no new parameter-level meaning, matching the baseline of 3.
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 ('Reply to an existing inbound SMS by message ID') and immediately scopes the operation relative to alternatives. An agent can distinguish it from siblings like joltsms_list_messages or joltsms_wait_for_sms 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?
It clearly establishes the selection context and the key exclusion: it replies to an existing inbound message and 'cannot send to an arbitrary phone number.' It does not explicitly name an alternative tool for outbound-to-new-number scenarios, but the constraint effectively rules out a wrong call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update metadata on a phone number — set a service label, tags, or notes.
Only provided fields are updated. Omitted fields remain unchanged. Pass an empty array [] to clear tags, or an empty string "" to clear notes.
Examples: update_number("+16505551234", service_name="PayPal", tags=["production"]) update_number("+16505551234", notes="Linked to acme@company.com")
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags for categorization (e.g. ["production", "paypal"]). Max 20 tags, 50 chars each. Pass [] to clear. | |
| notes | No | Free-form notes (e.g. "Linked to acme@company.com"). Max 1000 chars. Pass "" to clear. | |
| number_id | Yes | Number ID (UUID) or phone number (e.g. +17243213654 or 7243213654) | |
| service_name | No | Service/platform label (e.g. "PayPal", "Discord Backup"). Max 100 chars. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses partial-update semantics ('Only provided fields are updated. Omitted fields remain unchanged') and clearing semantics for tags and notes. It still omits permissions/auth requirements and error behavior, but the core mutation behavior is well explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose, then states the partial-update rule, then shows concrete examples. Every sentence earns its place and the structure makes the key behavioral rule immediately visible.
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 four-parameter mutation tool with no output schema and no annotations, the description covers purpose, update semantics, and clearing behavior. It is nearly complete, though it does not mention auth requirements or failure modes, which an agent might want before mutating production metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter including clearing semantics and length limits. The description's field list and examples add only marginal meaning beyond the schema, so the baseline of 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 verb and resource ('Update metadata on a phone number') and enumerates the mutable fields ('service label, tags, or notes'). This is clearly distinct from read siblings like joltsms_get_number and lifecycle siblings like joltsms_provision_number/joltsms_release_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?
The description implies usage through purpose and invocation examples, but never states when to choose this tool over alternatives such as joltsms_get_number or when not to use it. No explicit routing guidance or preconditions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll for an incoming SMS message on a specific number. This is the KEY tool for OTP verification workflows.
Typical workflow:
Trigger OTP on a website/app using the JoltSMS phone number
Call this tool with the number_id
The tool polls every few seconds until an SMS arrives or timeout
Returns the message body and parsed OTP code
Use from_filter to only match messages from a specific sender. Default timeout is 120 seconds with 5-second polling intervals.
| Name | Required | Description | Default |
|---|---|---|---|
| number_id | Yes | Number ID (UUID) or phone number (e.g. +17243213654 or 7243213654) | |
| from_filter | No | Only match SMS from this sender (partial match) | |
| timeout_seconds | No | Max seconds to wait (10-300, default 120) | |
| poll_interval_seconds | No | Seconds between polls (3-30, default 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does real work: it discloses the blocking poll loop, the default 120s timeout, the 5s polling interval, and that the response includes the message body and parsed OTP. It omits what happens on timeout (error vs empty result) and any auth/rate-limit context, leaving a modest 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?
The purpose is front-loaded in the first sentence and the numbered workflow is easy to scan. There is minor redundancy between step 3 ('polls every few seconds') and the closing line ('default timeout is 120 seconds with 5-second polling intervals'), which costs a little tightness.
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 no annotations and no output schema, the description covers the essential behavior an agent needs: blocking polling, timeout and interval defaults, sender filtering, and the shape of the return value. The main remaining gap is timeout-outcome behavior, which is minor but non-trivial for a polling 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%, with every parameter documented including ranges and defaults, so the schema does the heavy lifting. The description echoes the from_filter purpose and default timeout/interval but adds no syntax or format 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?
States a specific verb and resource: 'Poll for an incoming SMS message on a specific number,' and frames its role as 'the KEY tool for OTP verification workflows.' It distinguishes itself functionally from list/reply siblings, though it does not explicitly differentiate itself from the closely related joltsms_get_latest_otp sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete numbered workflow showing when to reach for this tool (after triggering an OTP) and adds a targeted usage tip for from_filter. However, it names no alternatives and gives no when-not-to-use guidance, e.g. whether get_latest_otp is the better pick when a message has already arrived.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.0joltsms_billing_statusjoltsms_get_latest_otpjoltsms_get_numberjoltsms_list_messagesjoltsms_list_numbersjoltsms_list_payment_methodsjoltsms_mark_readjoltsms_provision_numberjoltsms_release_numberjoltsms_reply_to_smsjoltsms_update_numberjoltsms_wait_for_smsScored across 12 tools
Most tools target distinct resource+action pairs (list_numbers vs get_number vs provision_number vs release_number are clearly separated). There is mild overlap in the OTP retrieval cluster (wait_for_sms, get_latest_otp, list_messages), but the descriptions explicitly differentiate them (wait vs. latest vs. full listing), so misselection risk is low.
All tools share a consistent 'joltsms_' prefix and follow a verb_noun pattern (list_numbers, get_number, update_number, provision_number, release_number, mark_read, wait_for_sms). The one deviation is 'billing_status', which is noun-only and lacks a verb, but this is a minor blemish in an otherwise uniform scheme.
Twelve tools is well within the ideal range and each maps to a distinct, meaningful operation (number lifecycle, messaging, OTP retrieval, billing, payment methods). No obvious redundant or filler tools inflate the set.
The number lifecycle (list/get/update/provision/release), messaging (list/reply/mark_read/wait), OTP helpers, billing, and payment listing are all covered, giving solid CRUD coverage for the domain. Minor gaps exist—no adding payment methods, no message search/deletion—and sending to arbitrary numbers is intentionally unsupported, but agents can work around these.
Phone, SMS and email for AI agents. One remote MCP endpoint, OAuth login, zero install.
Give AI agents a phone number. Voice calls, SMS, and phone number management for MCP clients.
Give AI agents real phone numbers, messages, and voice calls via MCP.
The Mobile Text Alerts SMS MCP server enables your AI to send SMS messages & manage contacts
