Skip to main content
Glama
hail

hail

Official

Check a verification

check_verification
Read-onlyIdempotent

Validate a carrier registration form before filing by running every Hail check for purpose rules, credits, duplicates, files, and required fields without submitting, saving, or charging.

Instructions

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.
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. Addedv0.32.0

TDQS

A4.3/5.0
Behavior5/5

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

Well beyond the readOnly/idempotent annotations, the description discloses the concrete side-effect guarantee ("Nothing is filed, saved, held or charged, and uploads stay usable") and enumerates what is actually verified, including failure codes 402 and 409 and the one-hour freshness rule on uploads. It also states the return payload (ok, files with sha256, note, problems with the offending field) and the honest caveat that carrier-side checks are separate.

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 what and the side-effect guarantee before the detail list, and every clause carries information. The middle sentence is a long run-on enumerating eight checks with nested parentheticals, which slightly hurts scannability, but nothing is filler.

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 ten-parameter nested-object tool with an output schema, this covers the essentials: purpose, dry-run semantics, what is validated, and what comes back. The one meaningful omission is differentiation from check_verification_documents, and there is no mention of rate limits or of whether repeated calls are cheap.

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 the schema already documents all ten parameters, including the purpose/quote_id/number_id conditionals and the upload_id slot mapping. The description adds only the useful cross-reference that the argument set equals submit_verification minus attest_authorized; it does not explain the purpose-dependent address or documents constraints beyond what the schema already says.

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 opening sentence gives a specific verb and resource ("Check a carrier registration form") with an explicit scope limit ("without filing anything"). It then names the sibling it mirrors ("Takes the same arguments as submit_verification except attest_authorized"), so an agent can tell it apart from the submit path without opening either 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?

Usage context is clear: this is the pre-flight validation pass that "runs every check Hail can run before filing," and the closing line warns that "the carrier runs its own checks at submission," which tells the agent a pass here is not a guarantee. The gap is that the sibling check_verification_documents is never mentioned, so the agent gets no rule for choosing between the two check tools.

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