Skip to main content
Glama
hail

hail

Official

Read verification documents

check_verification_documents

Reads verification files before form submission, extracts fields and document types, and warns about unreadable, expired, mismatched, or wrong-type documents so users can correct them.

Instructions

Read the files of a number verification form, before the form is filled or submitted.

    Takes the arguments of ``check_verification``. ``fields`` and ``address``
    may be empty or partial. An AI model reads each file.
    Returns ``fields``, ``address`` and ``documents.<slot>.fields``: the values the
    files show, by the form's own keys, to fill the form after the user confirms
    them. ``documents.<slot>.option`` is the document type the file looks like.
    ``warnings`` (``field``, ``kind``, ``message``) lists what the carrier may
    refuse: an unreadable, upside-down or expired document, a file of another
    type than the chosen one, or a typed name that differs from the printed one.
    Each message names the fix. A submission with warnings is still accepted.
    A file nothing was read from has ``read`` false; an unclear file also has an
    ``unreadable`` warning, and a file past the daily reads has ``skipped``
    ``daily_limit``. Only the first 3 pages of a PDF are read; a PDF of more
    than 5 pages is not read.
    Each file read uses one of the workspace's daily document reads (30 per day);
    a file given for several slots uses one. Nothing is filed, saved, held or
    charged, and uploads stay usable.

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_documents"
  }
}

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.
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 document slot to ``{option, fields, covers}``. ``option`` may be empty while the type is not chosen. ``covers`` lists the other slots the same file stands for: the file is sent once, for this slot, and one read fills all of them.
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.6/5.0
Behavior5/5

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

The description discloses substantial behavior beyond the annotations: daily read limits (30/day), PDF page handling (first 3 pages read, >5 pages not read), per-file quota consumption across multiple slots, warning semantics, and that nothing is filed, saved, held, or charged. This is rich operational context that an agent could not infer from the annotations.

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 description is front-loaded with purpose and usage, then proceeds into return values, warnings, quota behavior, and PDF handling. It is somewhat long but nearly every sentence contributes operational guidance; minor repetition around daily reads is acceptable.

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?

Despite having 8 parameters and nested objects, the description covers the important operational constraints: quota consumption, page limits, warning interpretation, empty/partial inputs, and side-effect guarantees. An output schema exists, so the description does not need to fully enumerate returns, and what it does say about outputs is supplementary rather than required.

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 schema already documents parameters thoroughly. The description still adds meaning: 'fields' and 'address' may be empty or partial, 'documents.<slot>.option' may be empty while the type is unchosen, and 'covers' lets one file stand for multiple slots. These clarifications go beyond the schema text.

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: 'Read the files of a number verification form, before the form is filled or submitted.' It clearly distinguishes the tool from the broader verification flow by focusing on reading files and returning extracted values for form prefill.

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 gives clear timing ('before the form is filled or submitted') and states it 'Takes the arguments of check_verification,' establishing its place relative to that sibling. It does not explicitly name when-not-to-use or contrast every alternative, but the context is clear enough for correct selection.

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