Skip to main content
Glama
vobiz-ai

Vobiz MCP Server

Official
by vobiz-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Return a number from a sub-account

unassign_number_from_subaccount
DestructiveIdempotent

Return a phone number from a sub-account to the parent Vobiz account pool. Use this to reverse a sub-account number assignment after user approval.

Instructions

Move a number from a sub-account back to this Vobiz account's pool (DELETE /account/{id}/numbers/{e164}/assign-subaccount). It is the undo of assign_number_to_subaccount. A 15-day cool-off applies: a number with a call in the last 15 days stays with the sub-account and the tool fails with not_allowed until the cool-off ends. Gated by VOBIZ_ENABLE_PROVISIONING and confirm: true.

Input Schema

NameRequiredDescriptionDefault
confirmYesMust be true, set only after the user explicitly approved: returning this number to the parent account pool. 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.
phone_numberYesThe number to take back, E.164; it must currently be assigned to one of this account's sub-accounts.

Output Schema

NameRequiredDescriptionDefault
okNotrue on success; false (with error and message) when the tool failed.
unassignedNotrue once the number is back in the main account's pool.
http_statusNoHTTP status Vobiz answered with.
phone_numberNoThe number, E.164.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.4.2
    • changedInput schema / properties / confirm / description
      Previous value: -"Must be true, set only after the user explicitly approved: returning this number to the parent account pool."New value: +"Must be true, set only after the user explicitly approved: returning this number to the parent account pool. 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 / phone_number / description
      Added value: +"The number to take back, E.164; it must currently be assigned to one of this account's sub-accounts."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "http_status": {
+      "description": "HTTP status Vobiz answered with.",
+      "type": "number"
+    },
+    "ok": {
+      "description": "true on success; false (with error and message) when the tool failed.",
+      "type": "boolean"
+    },
+    "phone_number": {
+      "description": "The number, E.164.",
+      "type": "string"
+    },
+    "unassigned": {
+      "description": "true once the number is back in the main account's pool.",
+      "type": "boolean"
+    }
+  },
+  "type": "object"
+}
  2. First observedv1.1.1

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description goes well beyond them: a 15-day call-activity cool-off, the specific not_allowed failure, a VOBIZ_ENABLE_PROVISIONING feature gate, and the confirm: true requirement. This is exactly the extra operational context 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.

Conciseness5/5

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

Front-loads the action and endpoint, then layers undo relationship, cool-off failure mode, and gating in descending order of importance. Dense but every clause carries distinct information with no redundancy.

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?

With an output schema present, return values need no explanation, and annotations cover the safety profile. The description fills the remaining gaps an agent needs: feature gate, confirmation attestation, and the failure mode. Nothing material is missing.

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 coverage is 100% and both parameters carry thorough inline descriptions (confirm's elicitation caveat, phone_number's E.164 pattern and assignment precondition). The description adds only the 'confirm: true' restatement and the env gate, which is behavioral rather than parameter detail, so the schema is doing 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?

States a specific verb and resource ('Move a number from a sub-account back to this Vobiz account's pool') and even cites the exact endpoint. The 'undo of assign_number_to_subaccount' framing lets an agent place it precisely against the assign sibling.

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 undo relationship to assign_number_to_subaccount clearly establishes the context in which this tool applies, and the cool-off condition tells the agent when the call will fail. It stops short of contrasting adjacent tools like release_phone_number or cancel_number_release, so there is no explicit when-not guidance.

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