Skip to main content
Glama
vobiz-ai

Vobiz MCP Server

Official
by vobiz-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Buy a phone number

buy_phone_number
DestructiveIdempotent

Purchases one available Vobiz phone number and adds it to your account after verifying fees, balance, inventory, and purchase limits; requires explicit confirmation and an idempotency key.

Instructions

Buy one phone number from Vobiz inventory and add it to this account. The setup fee plus the first monthly fee are charged to the account balance immediately (a sub-account's parent is charged). Before buying, the server checks in order: provisioning enabled, the number is not already owned, it is in inventory (else not_found), setup + monthly fee within VOBIZ_MAX_NUMBER_COST, enough available balance (postpaid accounts skip this), and the daily purchase cap. Find candidates with search_available_numbers first; configure the bought number with update_phone_number and undo a purchase with release_phone_number. Requires confirm: true after showing the user the number and its fees, plus an idempotency_key; repeating the key replays the first result and never buys twice.

Input Schema

NameRequiredDescriptionDefault
confirmYesMust be true, set only after the user explicitly approved: buying this number at the quoted fees. If your client supports MCP elicitation, the server asks the user to approve directly and this flag is not relied on; otherwise it is your attestation that the user approved.
currencyNoISO 4217 code (e.g. INR, USD) of the wallet to charge. Defaults to the number's listed currency, then the server's configured balance currency, then the account's primary wallet.
phone_numberYesThe number to buy, in E.164 form exactly as search_available_numbers listed it (e.g. +918065551234).
idempotency_keyYesUnique key for this intended operation (e.g. a UUID). Repeating it replays the first result instead of acting again.

Output Schema

NameRequiredDescriptionDefault
okNoTrue on success. On a failure the result is isError with ok: false plus `error` (kind), `message`, `retryable` and sometimes `http_status`.
numberNoThe number record Vobiz returned after purchase (e164, status, fees), or null if it sent none.
purchasedNoTrue when the number was bought by this call.
complianceNoSet when the number needs Aadhaar verification in the Vobiz console before use; otherwise null.
http_statusNoHTTP status Vobiz answered with.
backend_messageNoStatus message from Vobiz (e.g. 'created' or 'changed'), when it sent one.
charged_estimateNoWhat the purchase is expected to cost; the wallet transaction is authoritative.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.4.2
    • changedInput schema / properties / confirm / description
      Previous value: -"Must be true, set only after the user explicitly approved: buying this number at the quoted fees."New value: +"Must be true, set only after the user explicitly approved: buying this number at the quoted fees. If your client supports MCP elicitation, the server asks the user to approve directly and this flag is not relied on; otherwise it is your attestation that the user approved."
    • addedInput schema / properties / currency / description
      Added value: +"ISO 4217 code (e.g. INR, USD) of the wallet to charge. Defaults to the number's listed currency, then the server's configured balance currency, then the account's primary wallet."
    • changedInput schema / properties / phone_number / description
      Previous value: -"Number from search_available_numbers, E.164."New value: +"The number to buy, in E.164 form exactly as search_available_numbers listed it (e.g. +918065551234)."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "backend_message": {
+      "description": "Status message from Vobiz (e.g. 'created' or 'changed'), when it sent one.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "charged_estimate": {
+      "additionalProperties": {},
+      "description": "What the purchase is expected to cost; the wallet transaction is authoritative.",
+      "properties": {
+        "amount": {
+          "description": "Setup fee plus first monthly fee, as quoted in inventory.",
+          "type": "number"
+        },
+        "currency": {
+          "description": "Wallet currency charged.",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "compliance": {
+      "description": "Set when the number needs Aadhaar verification in the Vobiz console before use; otherwise null.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "http_status": {
+      "description": "HTTP status Vobiz answered with.",
+      "type": "number"
+    },
+    "number": {
+      "anyOf": [
+        {
+          "additionalProperties": {},
+          "propertyNames": {
+            "type": "string"
+          },
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The number record Vobiz returned after purchase (e164, status, fees), or null if it sent none."
+    },
+    "ok": {
+      "description": "True on success. On a failure the result is isError with ok: false plus `error` (kind), `message`, `retryable` and sometimes `http_status`.",
+      "type": "boolean"
+    },
+    "purchased": {
+      "const": true,
+      "description": "True when the number was bought by this call.",
+      "type": "boolean"
+    }
+  },
+  "type": "object"
+}
  2. First observedv1.1.1

TDQS

A4.6/5.0
Behavior5/5

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

Annotations cover the safety profile (destructive, idempotent, openWorld), but the description adds substantial context beyond them: immediate charging of setup + first monthly fee to the account balance (parent charged for sub-accounts), the exact ordered precheck list including not_found and VOBIZ_MAX_NUMBER_COST and postpaid balance skip, and idempotency replay semantics. This is exactly the kind of billing/side-effect disclosure that annotations cannot convey.

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

Conciseness4/5

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

Dense but front-loaded: the core action and immediate billing consequence lead, followed by prechecks, then alternatives. Every clause carries operational weight, though the description is long and could tighten the precheck enumeration slightly.

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

Completeness5/5

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

For a destructive, billed mutation with an output schema present, the description covers billing timing, precheck ordering, idempotency, confirmation, and the sibling workflow. Nothing an agent needs to invoke it safely is missing; return values are correctly left to the output schema.

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

Parameters3/5

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

Schema description coverage is 100% and the schema already documents confirm, idempotency_key, currency, and phone_number in detail. The description's 'requires confirm: true ... plus an idempotency_key' largely restates the schema rather than adding new per-parameter semantics (e.g. currency behavior is untouched). Baseline 3 applies 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.

Purpose5/5

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

Opens with a precise verb+resource+scope: 'Buy one phone number from Vobiz inventory and add it to this account.' It distinguishes itself from the obvious siblings by naming search_available_numbers (find candidates), update_phone_number (configure), and release_phone_number (undo). An agent can route correctly 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.

Usage Guidelines5/5

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

Gives explicit prerequisites and sequencing: find candidates with search_available_numbers first, configure with update_phone_number, undo with release_phone_number, and confirm:true only after showing the user the number and fees. The server-side precheck ordering is spelled out, so the agent knows exactly what conditions must hold before invoking.

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

Deploy Server

Other Tools