Skip to main content
Glama

Hail Communication for AI

Quote phone numbers

quote_numbers
Read-onlyIdempotent

Compare available phone numbers and their prices without buying or charging.

    Returns ``offers``, ``recommended_quote_id`` and ``expires_at``.
    Each offer includes ``e164``, ``number_type``, ``capabilities``, ``quote_id``,
    ``monthly_cents``, ``setup_cents``, ``readiness``, ``requirements``,
    ``subject_types``, ``verifications``, ``locality`` and ``region``.
    Prices are USD cents. ``locality`` and ``region`` tell apart cities with the same name.
    Quotes expire after ten minutes. Expired quotes cannot authorize a purchase.
    ``recommended_quote_id`` identifies a ready offer or is null when none is ready.

    ``subject_types`` identifies eligible personal or business registrations.
    ``verifications`` contains accepted registrations, with approved entries first.
    Entries include ``id``, ``state``, ``subject_type`` and ``subject_name``.
    ``readiness="verification_required"`` means registration approval is still needed.
    Registration requirements are specific to the quote and applicant type.
    An offer with ``by_request=true`` has no assigned number and requires a manual support order.
    Such offers remain valid for registration but are unavailable for automatic purchase.
    An upstream failure returns an error.

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": {
      "country_code": "<country_code>"
    },
    "name": "quote_numbers"
  }
}

Input Schema

NameRequiredDescriptionDefault
cityNoCity name as carriers list it, such as ``Austin``. Omitted: any city.
regionNoUS state or Canadian province code from ``list_number_regions``, to tell apart cities with the same name. Omitted: any region.
area_codeNoFirst digits of the number as dialed inside the country, such as ``415``. Omitted: any digits.
llm_modelNoModel ID of the calling agent. Optional. Recorded for analytics only.
number_typeNoOffer only this kind of number, for example ``toll_free`` for a number callers reach for free. Omitted: every kind.
capabilitiesNoWhat every offered number must do: calls (``voice``), texts (``sms``) or both. Omitted: both.
country_codeYesISO 3166-1 alpha-2 country code, such as ``US``.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 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 / number_type / description
      Previous value: -"Only numbers of this kind: local, mobile, national (non-geographic) or toll-free. Omitted: every kind."New value: +"Offer only this kind of number, for example ``toll_free`` for a number callers reach for free. Omitted: every kind."
  2. Changed10 schema fields changed
    • changedInput schema / properties / area_code / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "pattern": "^[0-9]{1,6}$",
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / area_code / description
      Previous value: -"Area code or number prefix in national format, such as ``415``."New value: +"First digits of the number as dialed inside the country, such as ``415``. Omitted: any digits."
    • changedInput schema / properties / capabilities / anyOf
      Previous value: -[
      -  {
      -    "items": {
      -      "type": "string"
      -    },
      -    "type": "array"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "items": {
      +      "enum": [
      +        "voice",
      +        "sms"
      +      ],
      +      "type": "string"
      +    },
      +    "maxItems": 2,
      +    "minItems": 1,
      +    "type": "array"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / capabilities / description
      Previous value: -"Required capabilities: ``voice``, ``sms`` or both."New value: +"What every offered number must do: calls (``voice``), texts (``sms``) or both. Omitted: both."
    • changedInput schema / properties / city / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "maxLength": 64,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / city / description
      Previous value: -"City name, such as ``Austin``."New value: +"City name as carriers list it, such as ``Austin``. Omitted: any city."
    • changedInput schema / properties / number_type / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "local",
      +      "mobile",
      +      "toll_free",
      +      "national"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / number_type / description
      Previous value: -"Only this type: ``local``, ``mobile``, ``national`` or ``toll_free``."New value: +"Only numbers of this kind: local, mobile, national (non-geographic) or toll-free. Omitted: every kind."
    • changedInput schema / properties / region / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "pattern": "^[A-Za-z]{2}$",
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / region / description
      Previous value: -"US state or Canadian province code from ``list_number_regions``, to tell apart cities with the same name."New value: +"US state or Canadian province code from ``list_number_regions``, to tell apart cities with the same name. Omitted: any region."
  3. First observed

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered; the description goes further by disclosing a ten-minute expiry, the consequence of expiry (cannot authorize purchase), USD-cent pricing, upstream error behavior, and the by_request manual-order caveat. The only weakness is that a large share of the text enumerates return fields rather than behavior.

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

Conciseness3/5

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

The key constraint is front-loaded in sentence one, but the middle block is a long enumeration of offer fields (e164, number_type, capabilities, quote_id, monthly_cents, setup_cents, ...) that largely restates what an existing output schema already provides. The later sentences about readiness and by_request earn their place; the field list does not.

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

Completeness4/5

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

For a read-only quote tool, the definition covers pricing units, expiry window and consequences, readiness semantics, registration subject types, and the by_request exception, which is enough for correct invocation and interpretation. It is slightly padded by return-field enumeration that the output schema already carries, but nothing an agent needs 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 is already documented, including city/region disambiguation and the area_code format. The description adds essentially no filtering semantics beyond that baseline, so the neutral baseline of 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 first sentence states a specific verb and resource ("Compare available phone numbers and their prices") and adds the crucial scope qualifier "without buying or charging," which separates it from purchase-oriented siblings such as acquire_number. An agent can identify the operation without opening the schema.

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 makes the comparison-then-purchase workflow clear via "without buying or charging" and "Expired quotes cannot authorize a purchase," which tells the agent quotes are a prerequisite step for acquisition. It does not explicitly name acquire_number as the follow-up tool or state when-not to use it, so the routing is implied rather than spelled out.

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