KaiCalls

Buy Phone Number

buy_number

DestructiveIdempotent

Request a real phone-number purchase. This is APPROVAL-GATED: the carrier bills immediately on execution, so the tool only prepares a request for authenticated owner review. Caller-supplied human_confirmed, dashboard_session, or system_policy fields never authorize execution. Relay the stored request and review URL to the owner; do not claim a number was purchased while approval is pending. Existing entitlement and carrier reservation checks still apply. Mirrors POST /api/v1/phone-numbers/purchase via numbers.purchase.

Input Schema

TableJSON Schema

Name	Required	Description
`actor`	No	Who is asking: { type: agent\|human\|system\|integration, id, display_name }.
`reason`	No	Optional reason recorded in the durable audit.
`dry_run`	No	Validate tenant, scope, and policy without buying anything.
`agent_id`	No	Agent ID to route this number to directly once purchased (optional; requires the number to also be voice-runtime-imported, which is not guaranteed at purchase time — prefer a follow-up attach_number call).
`authority`	No	Attribution only. human_confirmed and other caller-supplied modes cannot authorize a purchase. Authenticated owner review of the exact stored request is required.
`source_ref`	No	External source reference, such as a ticket or automation run ID.
`business_id`	No	Business ID (optional only when the token can access exactly one business).
`phone_number`	Yes	The exact E.164 phone number to purchase, as returned by search_available_numbers.
`idempotency_key`	No	Stable key for the purchase request; repeating it returns the original outcome. Defaults to a key derived from the phone number — pass your own to retry a previously failed purchase.
`queue_for_approval`	No	Create a durable owner-review request (default true). Setting false returns needs_approval, but an authority-envelope retry still cannot execute.

Output Schema

TableJSON Schema

Name	Required	Description
`code`	No
`error`	No	Present when success is false
`result`	No	On executed: { number, vapi_registered, agent_attached, compliance: { high_risk_category, disclosure_note } }.
`status`	No
`message`	No
`success`	Yes	Whether the tool completed successfully
`summary`	No
`approval`	No
`request_id`	No
`risk_level`	No
`business_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 10, 2026

changedInput schema / properties / authority / description

Previous value: -"How the purchase was authorized: { mode, confirmed_by, confirmed_at, confirmation_ref }. human_confirmed requires all three confirmation fields; anything weaker returns pending_approval."New value: +"Attribution only. human_confirmed and other caller-supplied modes cannot authorize a purchase. Authenticated owner review of the exact stored request is required."

changedInput schema / properties / queue_for_approval / description

Previous value: -"When authority is insufficient, create a durable dashboard approval (default true). Set false to get needs_approval and retry yourself with the same idempotency_key once a human confirms."New value: +"Create a durable owner-review request (default true). Setting false returns needs_approval, but an authority-envelope retry still cannot execute."

Changed19 schema fields changedJul 18, 2026

addedInput schema / properties / actor

Added value: +{
+  "description": "Who is asking: { type: agent|human|system|integration, id, display_name }.",
+  "type": "object"
+}

changedInput schema / properties / agent_id / description

Previous value: -"Agent ID to route this number to directly once purchased (optional; requires the number to also be Vapi-imported, which is not guaranteed at purchase time — prefer a follow-up attach_number call)."New value: +"Agent ID to route this number to directly once purchased (optional; requires the number to also be voice-runtime-imported, which is not guaranteed at purchase time — prefer a follow-up attach_number call)."

addedInput schema / properties / authority

Added value: +{
+  "description": "How the purchase was authorized: { mode, confirmed_by, confirmed_at, confirmation_ref }. human_confirmed requires all three confirmation fields; anything weaker returns pending_approval.",
+  "type": "object"
+}

addedInput schema / properties / dry_run

Added value: +{
+  "description": "Validate tenant, scope, and policy without buying anything.",
+  "type": "boolean"
+}

addedInput schema / properties / idempotency_key

Added value: +{
+  "description": "Stable key for the purchase request; repeating it returns the original outcome. Defaults to a key derived from the phone number — pass your own to retry a previously failed purchase.",
+  "type": "string"
+}

addedInput schema / properties / queue_for_approval

Added value: +{
+  "description": "When authority is insufficient, create a durable dashboard approval (default true). Set false to get needs_approval and retry yourself with the same idempotency_key once a human confirms.",
+  "type": "boolean"
+}

addedInput schema / properties / reason

Added value: +{
+  "description": "Optional reason recorded in the durable audit.",
+  "type": "string"
+}

addedInput schema / properties / source_ref

Added value: +{
+  "description": "External source reference, such as a ticket or automation run ID.",
+  "type": "string"
+}

addedOutput schema / properties / approval

Added value: +{
+  "type": [
+    "object",
+    "null"
+  ]
+}

changedOutput schema / properties / business_id / type

Previous value: -"string"New value: +[
+  "string",
+  "null"
+]

addedOutput schema / properties / code

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

removedOutput schema / properties / compliance

Removed value: -{
-  "properties": {
-    "disclosure_note": {
-      "type": "string"
-    },
-    "high_risk_category": {
-      "type": "boolean"
-    }
-  },
-  "type": "object"
-}

addedOutput schema / properties / message

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

removedOutput schema / properties / number

Removed value: -{
-  "type": "object"
-}

addedOutput schema / properties / request_id

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / result

Added value: +{
+  "description": "On executed: { number, vapi_registered, agent_attached, compliance: { high_risk_category, disclosure_note } }.",
+  "type": [
+    "object",
+    "null"
+  ]
+}

addedOutput schema / properties / risk_level

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / status
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / summary

Added value: +{
+  "type": [
+    "object",
+    "null"
+  ]
+}

AddedJul 9, 2026

TDQS

A4.4/5.0

Behavior5/5

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

The description adds critical behaviors well beyond what annotations indicate: it says the carrier bills immediately on approval, supplies caller-supplied authorization is insufficient, and emphasizes not to claim the purchase is complete while approval is pending. It states that existing entitlement and carrier reservation checks apply, giving a clear failure-mode expectation. This is valuable behavioral disclosure not present in annotations.

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?

The description is front-loaded with the key purpose, approval-gating status, and immediate consequence, which is excellent. The final 'Mirrors POST /api/v1/phone-numbers/purchase' sentence is perhaps a token technical detail that might be redundant, but the six-sentence structure is compact and informative without being overly verbose.

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 tool with high safety implications, approval gating, and several behavioral caveats, the description addresses the most crucial things an agent needs to know to invoke it correctly: it's approval-gated, how to handle the response, what never authorizes, and that existing checks apply. With the output schema present, there is no need to explain return values here, so the description is complete.

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?

The schema covers 100% of the 10 parameters with detailed descriptions, so the top-line description does not need to explain them. The description mentions caller-supplied fields (human_confirmed, dashboard_session, system_policy) only to state they never authorize, which slightly deepen the meaning of the authority parameter but mostly repeats what is already in the schema. Baseline 3 applies.

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?

The description clearly states the tool 'Request a real phone-number purchase' and immediately breaks the meaning of the name buy_number by signaling it is approval-gated, so it only prepares an owner-review request rather than authorizing an immediate purchase. This distinguishes it from a simple car-buying action and is distinguishable from sibling tools like request_extra_number, especially since the description describes a specific API flow and an explicit 'Mirrors POST /api/v1/phone-numbers/purchase' behavior.

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

Usage Guidelines4/5

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

The description clearly sets the context: use this tool to purchase a real number, and after invocation you must relay the stored request and review URL to the owner rather than treating the purchase as complete. It does not explicitly name when not to use this tool or alternative sibling tools (e.g., attach_number), but the approval-gated flow and the 'do not claim a number was purchased' instruction are strong usage guidance.

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

All KaiCalls tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.