Skip to main content
Glama

Hail Communication for AI

Submit a verification

submit_verification
Destructive

Submit authorized applicant details and documents for carrier registration.

    Submission is irreversible once sent for review. Carriers retain submitted documents.
    ``fields``, ``address``, ``documents`` and ``files`` follow the carrier's current requirements.
    SMS campaign text requires user review and approval before submission.

    ``purpose="number"``: the balance must cover the offer's setup fee plus first month;
    otherwise nothing is sent. That amount is reserved during review and pays for a
    later purchase using this registration. It is returned after rejection, cancellation
    or 30 days without purchase following approval.
    ``purpose="sms"`` registers US local numbers for US texting with carrier filing fees.
    Free toll-free verification uses type ``toll_free``, country ``US`` or ``CA``, the
    owned ``number_id`` and ``registration_kind=toll_free`` among the form fields.

    Base64 files are written into the tool call and add about a third to their size.
    Base64 files total at most 29 MiB, checked here; the API checks the 30 MB total of
    all files, uploads included. Slot names use letters, digits, hyphens and underscores,
    up to 64 characters. At most 100 fields are accepted.
    ``check_verification`` takes the same arguments and files nothing.

    Returns ``id``, ``state`` and ``subject_name``. Carrier review takes business days.
    A 409 identifies an existing registration; a timeout can leave a submission in progress.
    Carrier field errors include ``problems`` and leave no saved submission.

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>",
      "number_type": "<number_type>",
      "fields": "<fields>",
      "documents": "<documents>",
      "files": "<files>",
      "attest_authorized": "<attest_authorized>"
    },
    "name": "submit_verification"
  }
}

Input Schema

NameRequiredDescriptionDefault
filesYesThe document files, one per slot named in ``documents``. Use an upload: the ``id`` from ``create_file_upload`` with purpose ``verification_document``, within an hour of uploading. A very small file can go inline as base64 instead. Each file is at most 10 MiB.
fieldsYesApplicant answers keyed by the field names in ``get_verification_requirements``. Choice fields take comma-separated option keys.
addressNoThe applicant's address. Give it when the requirements include one; otherwise leave it out.
purposeNoWhat the registration is for: ``number`` registers the applicant so a number can be bought; ``sms`` registers US texting (local 10DLC or toll-free).number
quote_idNoThe number offer this registration lets the user buy: the offer's ``quote_id`` from ``quote_numbers``, the same one used for the requirements. Give it when ``purpose`` is ``number``; leave it out for ``sms``.
documentsYesMap from each needed document slot to ``{option, fields}``, with the option chosen from that slot in the requirements.
llm_modelNoModel ID of the calling agent. Optional. Recorded for analytics only.
number_idNoThe owned number this registration is for: its ID from ``list_numbers``, the same one used for the requirements. Give it for toll-free texting and when the form asks for the sending number; otherwise leave it out.
number_typeYesThe kind of number this registration covers. Copy it from the offer in ``quote_numbers`` or the number in ``list_numbers``.
country_codeYesISO 3166-1 alpha-2 country code, such as ``US``.
subject_typeNoWho the registration is for, matching the requirements: the user (``person``) or their company (``business``). It has no default; without it, nothing is sent.
attest_authorizedYesAttestation that the named person or business authorized this filing and supplied its details and files. Only ``true`` sends anything.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / properties / address / anyOf
      Previous value: -[
      -  {
      -    "properties": {
      -      "city": {
      -        "description": "City or locality.",
      -        "title": "City",
      -        "type": "string"
      -      },
      -      "country_code": {
      -        "description": "ISO alpha-2 address country.",
      -        "title": "Country Code",
      -        "type": "string"
      -      },
      -      "customer_name": {
      -        "description": "Name associated with the address.",
      -        "title": "Customer Name",
      -        "type": "string"
      -      },
      -      "postal_code": {
      -        "description": "Postal or ZIP code.",
      -        "title": "Postal Code",
      -        "type": "string"
      -      },
      -      "region": {
      -        "description": "State, province or region.",
      -        "title": "Region",
      -        "type": "string"
      -      },
      -      "street": {
      -        "description": "Street address.",
      -        "title": "Street",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "customer_name",
      -      "street",
      -      "city",
      -      "region",
      -      "postal_code",
      -      "country_code"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "properties": {
      +      "city": {
      +        "description": "City or town of the street address, as written on mail sent there.",
      +        "title": "City",
      +        "type": "string"
      +      },
      +      "country_code": {
      +        "description": "ISO alpha-2 address country.",
      +        "title": "Country Code",
      +        "type": "string"
      +      },
      +      "customer_name": {
      +        "description": "Name associated with the address.",
      +        "title": "Customer Name",
      +        "type": "string"
      +      },
      +      "postal_code": {
      +        "description": "Postal or ZIP code of the street address, such as `94103`.",
      +        "title": "Postal Code",
      +        "type": "string"
      +      },
      +      "region": {
      +        "description": "State, province or region.",
      +        "title": "Region",
      +        "type": "string"
      +      },
      +      "street": {
      +        "description": "Street address.",
      +        "title": "Street",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "customer_name",
      +      "street",
      +      "city",
      +      "region",
      +      "postal_code",
      +      "country_code"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / files / items / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "slot": {
      -        "pattern": "^[A-Za-z0-9_-]{1,64}$",
      -        "type": "string"
      -      },
      -      "upload_id": {
      -        "format": "uuid",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "slot",
      -      "upload_id"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "content_base64": {
      -        "contentEncoding": "base64",
      -        "type": "string"
      -      },
      -      "content_type": {
      -        "enum": [
      -          "image/jpeg",
      -          "image/png",
      -          "application/pdf"
      -        ],
      -        "type": "string"
      -      },
      -      "slot": {
      -        "pattern": "^[A-Za-z0-9_-]{1,64}$",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "slot",
      -      "content_type",
      -      "content_base64"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "slot": {
      +        "description": "The document slot this file fills: a key in ``documents``.",
      +        "pattern": "^[A-Za-z0-9_-]{1,64}$",
      +        "type": "string"
      +      },
      +      "upload_id": {
      +        "description": "The ``id`` from ``create_file_upload`` with purpose ``verification_document``.",
      +        "format": "uuid",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "slot",
      +      "upload_id"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "content_base64": {
      +        "contentEncoding": "base64",
      +        "description": "The whole file, base64-encoded.",
      +        "type": "string"
      +      },
      +      "content_type": {
      +        "description": "The file's format.",
      +        "enum": [
      +          "image/jpeg",
      +          "image/png",
      +          "application/pdf"
      +        ],
      +        "type": "string"
      +      },
      +      "slot": {
      +        "description": "The document slot this file fills: a key in ``documents``.",
      +        "pattern": "^[A-Za-z0-9_-]{1,64}$",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "slot",
      +      "content_type",
      +      "content_base64"
      +    ],
      +    "type": "object"
      +  }
      +]
    • 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: -"Kind of phone number: a local or mobile number, a national number (non-geographic), or a toll-free number."New value: +"The kind of number this registration covers. Copy it from the offer in ``quote_numbers`` or the number in ``list_numbers``."
    • changedInput schema / properties / quote_id / description
      Previous value: -"The offer this registration is for: its ``quote_id`` from ``quote_numbers``, the same one used for the requirements. Give it when ``purpose`` is ``number``; leave it out for ``sms``."New value: +"The number offer this registration lets the user buy: the offer's ``quote_id`` from ``quote_numbers``, the same one used for the requirements. Give it when ``purpose`` is ``number``; leave it out for ``sms``."
  2. Changed16 schema fields changed
    • changedInput schema / properties / address / anyOf
      Previous value: -[
      -  {
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "properties": {
      +      "city": {
      +        "description": "City or locality.",
      +        "title": "City",
      +        "type": "string"
      +      },
      +      "country_code": {
      +        "description": "ISO alpha-2 address country.",
      +        "title": "Country Code",
      +        "type": "string"
      +      },
      +      "customer_name": {
      +        "description": "Name associated with the address.",
      +        "title": "Customer Name",
      +        "type": "string"
      +      },
      +      "postal_code": {
      +        "description": "Postal or ZIP code.",
      +        "title": "Postal Code",
      +        "type": "string"
      +      },
      +      "region": {
      +        "description": "State, province or region.",
      +        "title": "Region",
      +        "type": "string"
      +      },
      +      "street": {
      +        "description": "Street address.",
      +        "title": "Street",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "customer_name",
      +      "street",
      +      "city",
      +      "region",
      +      "postal_code",
      +      "country_code"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / address / description
      Previous value: -"Applicant address with ``customer_name``, ``street``, ``city``, ``region``, ``postal_code`` and ``country_code``, when the requirements include one."New value: +"The applicant's address. Give it when the requirements include one; otherwise leave it out."
    • changedInput schema / properties / files / description
      Previous value: -"One entry per required file: ``{slot, upload_id}`` with the ``id`` from ``create_file_upload`` (purpose ``verification_document``, uploaded within the last hour), or ``{slot, content_type, content_base64}`` for a very small file. JPEG, PNG or PDF, 10 MiB each, 20 files at most."New value: +"The document files, one per slot named in ``documents``. Use an upload: the ``id`` from ``create_file_upload`` with purpose ``verification_document``, within an hour of uploading. A very small file can go inline as base64 instead. Each file is at most 10 MiB."
    • addedInput schema / properties / files / items / anyOf
      Added value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "slot": {
      +        "pattern": "^[A-Za-z0-9_-]{1,64}$",
      +        "type": "string"
      +      },
      +      "upload_id": {
      +        "format": "uuid",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "slot",
      +      "upload_id"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "content_base64": {
      +        "contentEncoding": "base64",
      +        "type": "string"
      +      },
      +      "content_type": {
      +        "enum": [
      +          "image/jpeg",
      +          "image/png",
      +          "application/pdf"
      +        ],
      +        "type": "string"
      +      },
      +      "slot": {
      +        "pattern": "^[A-Za-z0-9_-]{1,64}$",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "slot",
      +      "content_type",
      +      "content_base64"
      +    ],
      +    "type": "object"
      +  }
      +]
    • removedInput schema / properties / files / items / type
      Removed value: -"object"
    • addedInput schema / properties / files / maxItems
      Added value: +20
    • changedInput schema / properties / number_id / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "format": "uuid",
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / number_id / description
      Previous value: -"Owned number ID from ``list_numbers``, the same one used for the requirements. Required for toll-free texting verification and when the form asks for the sending number."New value: +"The owned number this registration is for: its ID from ``list_numbers``, the same one used for the requirements. Give it for toll-free texting and when the form asks for the sending number; otherwise leave it out."
    • changedInput schema / properties / number_type / description
      Previous value: -"``local``, ``mobile``, ``national`` or ``toll_free``."New value: +"Kind of phone number: a local or mobile number, a national number (non-geographic), or a toll-free number."
    • addedInput schema / properties / number_type / enum
      Added value: +[
      +  "local",
      +  "mobile",
      +  "toll_free",
      +  "national"
      +]
    • changedInput schema / properties / purpose / description
      Previous value: -"``number`` registers an applicant for a number purchase; ``sms`` registers US texting (local 10DLC or toll-free)."New value: +"What the registration is for: ``number`` registers the applicant so a number can be bought; ``sms`` registers US texting (local 10DLC or toll-free)."
    • addedInput schema / properties / purpose / enum
      Added value: +[
      +  "number",
      +  "sms"
      +]
    • changedInput schema / properties / quote_id / anyOf
      Previous value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "format": "uuid",
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / quote_id / description
      Previous value: -"``quote_id`` from ``quote_numbers``, the same one used for the requirements. Required for ``purpose=\"number\"``."New value: +"The offer this registration is for: its ``quote_id`` from ``quote_numbers``, the same one used for the requirements. Give it when ``purpose`` is ``number``; leave it out for ``sms``."
    • 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: -"Required. The actual applicant, ``person`` or ``business``, matching the requirements."New value: +"Who the registration is for, matching the requirements: the user (``person``) or their company (``business``). It has no default; without it, nothing is sent."
  3. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description adds substantial context beyond that: submission is irreversible, carriers retain documents, funds are reserved during review and returned after rejection, cancellation, or 30 days without purchase, and a 409 signals an existing registration while a timeout may leave a submission in progress. Error sematics (carrier field errors carry 'problems' and leave no saved submission) are also disclosed. Only the exact mechanics of the fund hold release timing remain slightly vague.

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?

Long but well structured, with the irreversible-submission warning front-loaded and purpose-specific behavior split into labeled paragraphs. A few sentences restate schema constraints (slot name character set and 64-character limit), which is wasted space given the schema already enforces them.

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 12-parameter, high-stakes filing tool with nested objects and an output schema, the description covers what gets filed, cost/reservation behavior, size and count limits, funding prerequisites, return fields, and the main failure modes (409, timeout, carrier field errors). An agent has enough to call it correctly and to anticipate outcomes.

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, but the description adds real meaning: the balance must cover setup fee plus first month or nothing is sent, the 29 MiB inline base64 cap versus the API's 30 MB total including uploads, the 100-field limit, and the requirement to supply quote_id for number purposes and number_id for toll-free. Slot naming rules largely restate the schema pattern, which is the main redundancy.

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 ('Submit authorized applicant details and documents for carrier registration') and explicitly separates itself from the sibling check_verification, which 'takes the same arguments and files nothing.' An agent can distinguish filing a real submission from a dry run without opening any 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?

Provides concrete routing logic: purpose='number' when registering so a number can be bought, purpose='sms' for US texting, and type 'toll_free' with registration_kind=toll_free for free toll-free verification. It also points to check_verification as the non-filing alternative. It does not cover use of cancel_verification or amend_sms_application, but the primary when-to-use decision is explicit.

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