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. On the acquisition surface, set_owner_phone must run first (or record a decline) — never buy a number for a signup with no way to be reached.

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.7/5.0

Behavior5/5

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

The description goes far beyond the annotations, which only indicate destructiveness and idempotency. It discloses that the tool is approval-gated, bills immediately on execution, only prepares a request, that caller-supplied authorization fields are never sufficient, and that a review URL must be relayed. This is rich, non-obvious behavior that the agent must know, and it does not contradict 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.

Conciseness5/5

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

The description is well-structured, front-loading the core purpose, then explaining the approval-gating and ordering constraints. Every sentence carries essential information; there is no filler or repetition. The length is justified given the tool's complexity and the critical safety implications.

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?

Given the tool's high complexity (10 params, nested objects, output schema) and the absence of output schema details in the description, the description still covers the essential workflow: the approval requirement, the billing consequence, the ordering with set_owner_phone, and the caveat about not claiming purchase prematurely. The output schema handles return values, so nothing critical is missing for correct invocation.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3. The description adds crucial semantics for the 'authority' parameter by explaining that caller-supplied modes (human_confirmed, dashboard_session, system_policy) cannot authorize execution and are attribution-only. This goes beyond the schema description and helps the agent avoid misuse of that field.

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 states a specific verb and resource ('Request a real phone-number purchase') and clearly distinguishes its scope: it prepares a request rather than executing a purchase. It also names the ordering requirement with set_owner_phone and the approval-gating, making it unmistakably different from sibling tools like attach_number or search_available_numbers.

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 gives clear context for when to use the tool (whenever a number must be acquired) and explicitly states that set_owner_phone must run first on the acquisition surface. It also warns against claiming purchase before approval. However, it does not explicitly name alternative sibling tools or state when NOT to use this tool in favor of another, leaving some inference to the agent.

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

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.