Skip to main content
Glama

Hail Communication for AI

Check a verification

check_verification
Read-onlyIdempotent

Check a carrier registration form without filing anything.

    Takes the same arguments as ``submit_verification`` except ``attest_authorized``.
    Runs every check Hail can run before filing: purpose rules, credit (402),
    the carrier's current form, duplicates (409), field lengths, each file
    (type, size, and for ``upload_id`` that it is this workspace's verification
    document, uploaded within the last hour), and the form's required fields,
    documents and address (for ``purpose="sms"``, the US texting application).
    Nothing is filed, saved, held or charged, and uploads stay usable.
    Returns ``ok``, ``files`` (slot, upload_id, size_bytes, sha256 per file) and
    ``note``; problems come back as ``problems`` with the field named.
    The carrier runs its own checks at 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>"
    },
    "name": "check_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.

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.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description goes well beyond them: nothing is filed, saved, held or charged, uploads stay usable afterward, and specific failure semantics (402 credit, 409 duplicate) are named. It also discloses the upload_id validity window (this workspace's verification document, uploaded within the last hour), which no annotation conveys.

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?

Front-loads the core distinction (check, don't file) and then enumerates the checks in a compact run-on list, which is dense but each clause maps to a real validation rule. The return-value sentence is slightly redundant with the existing output schema but is short enough to earn its place.

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 11-parameter, nested-object tool, the description covers purpose, prerequisites (upload freshness, workspace ownership), what is and isn't mutated, error shapes and the limits of the guarantee. With an output schema present, it correctly avoids over-explaining return structure while still naming ok, files and problems.

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 baseline is 3, but the description adds real constraint meaning: files are re-validated for type and size, upload_id must belong to this workspace and be under an hour old, and address is checked against the US texting application when purpose="sms". It also flags the one parameter that is deliberately absent relative to submit_verification (attest_authorized).

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?

Opens with a specific verb and resource, "Check a carrier registration form without filing anything," which both names the operation and distinguishes it from the sibling submit_verification. An agent knows immediately this is a dry-run validator rather than a filing call.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly positions the tool against submit_verification ("Takes the same arguments as submit_verification except attest_authorized") and frames the check set as "every check Hail can run before filing," which tells the agent when to reach for it versus actually filing. The closing note that "The carrier runs its own checks at submission" sets the expectation boundary of what passing here means.

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