Skip to main content
Glama

Hail Communication for AI

Buy a phone number

acquire_number
DestructiveIdempotent

Buy a quoted phone number with explicit price confirmation.

    This charges the setup fee and first month immediately, then renews monthly.
    The purchase requires the user's authorization for that number and cost.
    Expired or changed offers return 409 without authorizing a different price.
    Each quote can buy at most one number.

    A retry with the same quote and ``idempotency_key`` refers to the original purchase.
    After a timeout, a new quote starts a different purchase and can buy a second number.
    A returned retry key is available after a timeout or server error.
    A 4xx failure returns no retry key; that failed request cannot be reused.
    A rejected or ambiguous registration selection returns 422.
    A purchase does not assign an answering agent automatically.
    Returns the number record and ``idempotency_key``, or an error with any available retry key.
    

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "quote_id": "<quote_id>",
      "country_code": "<country_code>",
      "number_type": "<number_type>",
      "confirm_total_cents": "<confirm_total_cents>"
    },
    "name": "acquire_number"
  }
}

Input Schema

NameRequiredDescriptionDefault
quote_idYes``quote_id`` of one offer from ``quote_numbers``.
llm_modelNoModel ID of the calling agent. Optional. Recorded for analytics only.
number_typeYesKind of number being bought: copy the offer's ``number_type`` from ``quote_numbers``. Hail checks it against the offer.
country_codeYesCountry of the number being bought, as an ISO alpha-2 code: the ``country_code`` sent to ``quote_numbers`` for this offer.
subject_typeNoWhose approved registration may be used: the user's own (``person``) or their company's (``business``). Omitted: either.
idempotency_keyNoRetry key. The ``idempotency_key`` from an earlier response refers to that original request instead of starting a new one. Omitted: a new key is generated and returned.
verification_idNoWhich approved registration covers this purchase: an ``id`` from the offer's ``verifications``. Give it when the offer lists more than one approved registration. Omitted: the only approved one, if any.
confirm_total_centsYesThe offer's ``setup_cents`` plus ``monthly_cents``, in USD cents, as the user authorized it.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / llm_model
      Added value: +{
      +  "description": "Model ID of the calling agent. Optional. Recorded for analytics only.",
      +  "type": "string"
      +}
    • changedInput schema / properties / verification_id / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "format": "uuid",
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / verification_id / description
      Previous value: -"Approved registration to use, from the offer's ``verifications``. Required when several approved registrations are eligible."New value: +"Which approved registration covers this purchase: an ``id`` from the offer's ``verifications``. Give it when the offer lists more than one approved registration. Omitted: the only approved one, if any."
  2. Changed5 schema fields changed
    • changedInput schema / properties / country_code / description
      Previous value: -"The offer's ISO alpha-2 country code."New value: +"Country of the number being bought, as an ISO alpha-2 code: the ``country_code`` sent to ``quote_numbers`` for this offer."
    • changedInput schema / properties / number_type / description
      Previous value: -"The offer's ``number_type``."New value: +"Kind of number being bought: copy the offer's ``number_type`` from ``quote_numbers``. Hail checks it against the offer."
    • addedInput schema / properties / number_type / enum
      Added value: +[
      +  "local",
      +  "mobile",
      +  "toll_free",
      +  "national"
      +]
    • changedInput schema / properties / subject_type / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "person",
      +      "business"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / subject_type / description
      Previous value: -"Limit eligible registrations to ``person`` or ``business``."New value: +"Whose approved registration may be used: the user's own (``person``) or their company's (``business``). Omitted: either."
  3. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations declare the safety profile (destructive, idempotent, open world), and the description goes well beyond that: immediate charge of setup fee plus first month, monthly renewal, authorization requirement, 409 on changed price, 422 on rejected registration selection, and the fact that no answering agent is assigned automatically. The retry semantics are the most valuable addition — same key resumes the original purchase, a fresh quote after a timeout creates a second purchase, and 4xx failures return no retry key.

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 billing warning and authorization requirement are front-loaded before the error and retry details, which is the right ordering for a destructive purchase. It is somewhat long and includes a return-value sentence that partly duplicates the existing output schema, plus a couple of facts stated twice across the description and schema.

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 an open-world, destructive, idempotent purchase tool with 8 parameters, the description covers cost, timing, authorization, idempotency, the specific error codes 409/422, and the post-purchase state (no agent assigned). The output schema and annotations already handle return shape and safety hints, so nothing an agent needs before calling 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 description coverage is 100%, so every parameter already carries its own explanation, which sets the baseline at 3. The description reinforces the intent of confirm_total_cents ('as the user authorized it') and the one-number-per-quote constraint on quote_id, but it adds no format or selection detail that the schema lacks.

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 opens with a specific verb and resource ('Buy a quoted phone number') and adds the gating condition ('with explicit price confirmation'), which immediately separates it from read-side siblings like get_number or list_numbers. It also names the upstream tool that produces the required input ('quote_id of one offer from quote_numbers'), so an agent knows this is the terminal step of a quote-then-buy flow.

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?

It gives clear preconditions (must hold a quote, must have the user's authorization for that number and cost) and hard limits ('Each quote can buy at most one number', expired quotes return 409). It does not explicitly name a sibling alternative or when NOT to call it (e.g. reusing an existing number via list_numbers instead of buying), which keeps it short of a 5.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources