hail

Official

by hail-hq

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Submit a verification

submit_verification

Destructive

Submit personal or company details and identity documents to the carrier for verification. Irreversible — once sent it cannot be cancelled, so confirm authorization first.

Instructions

Send the user's personal or company details and identity documents to the carrier for verification. IRREVERSIBLE: once submitted it cannot be cancelled, and the carrier keeps the documents.

    ``attest_authorized``: pass true only if the person or company named
    in these details and documents asked for this submission and gave you
    the details and files in this conversation. Never invent, guess, infer
    or reuse personal data or documents. Anything else: pass false (the
    call then sends nothing).

    ``purpose`` is ``number`` (default) or ``sms``. ``purpose='sms'``
    registers the organization to text US numbers from a US number
    (country_code US, number_type local). The carrier fee is debited from
    credit at filing. Pass the same ``purpose`` to
    get_verification_requirements. For ``purpose='number'``, pass the
    same ``quote_id`` you passed to get_verification_requirements. For
    ``purpose='sms'``, pass the same ``number_id`` if you passed one.

    ``subject_type`` is required: ``person`` (the user) or ``business``
    (the user's company), the same one passed to
    get_verification_requirements. Never guess it: ask the user "you or
    your company?".

    The verification is named after the person or company in the form
    (for example the business name, or the first and last name); it
    comes back as ``subject_name``. The organization may hold several
    verifications of one subject type (several people or companies).

    Steps: 1) call get_verification_requirements. 2) Ask the user for each
    field and file. 3) Call this once. Do not submit twice: a 409 means
    one with the same subject type and name already exists (see
    list_verifications).

    Arguments, as listed by get_verification_requirements:
    ``fields`` is ``{field name: value}``. ``address`` is
    ``{"customer_name", "street", "city", "region", "postal_code",
    "country_code"}`` (all required when ``address_required``).
    ``documents`` is ``{slot: {"option": <option key>, "fields": {...}}}``
    for each slot with ``needs_input``. ``files`` is a list of
    ``{"slot", "content_type", "content_base64"}``, one per slot that
    needs a file; ``slot`` must be a key in ``documents``
    and match letters, digits, - and _ (at most 64).
    ``content_type`` is ``image/jpeg``, ``image/png`` or
    ``application/pdf``. Limits: 10 MiB per file, 29 MiB in total, at
    most 20 files and 20 fields. Compress images to JPG or PNG under about
    7 MiB so the call stays small.

    Returns the verification: ``id``, ``state`` and ``subject_name``.
    Review takes business days and nothing notifies you: poll
    get_verification. If the carrier finds a problem you get
    ``{"error", "problems": [{"loc", "msg"}]}`` and nothing is stored:
    ask the user to fix it, then submit again. After a timeout call
    list_verifications before trying again.

Input Schema

Name	Required	Default
`files`	Yes
`fields`	Yes
`address`	No
`purpose`	No	number
`quote_id`	No
`documents`	Yes
`number_id`	No
`number_type`	Yes
`country_code`	Yes
`subject_type`	No
`attest_authorized`	Yes

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.30.0Oct 23, 2026

addedInput schema / properties / number_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Number Id"
+}

removedInput schema / properties / provider

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Provider"
-}

addedInput schema / properties / quote_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Quote Id"
+}

addedInput schema / properties / subject_type / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / subject_type / default
```
Previous value: -"person"New value: +null
```
removedInput schema / properties / subject_type / type
```
Removed value: -"string"
```

First observedv0.29.0Oct 21, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations, it discloses irreversibility, that the carrier keeps the documents, what attest_authorized=false does, carrier-fee timing, review timing with no notification, 409 duplicate behavior, and the error format when nothing is stored. These specifics are consistent with the destructive, non-idempotent, open-world annotations.

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

Conciseness5/5

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

The description is long but appropriately sized for an irreversible 11-parameter submission workflow. Purpose and irreversibility are front-loaded, followed by attestation rules, purpose variants, steps, argument shapes, and error handling, with no obvious filler.

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?

Given the complexity, nested objects, and zero schema description coverage, it covers the prerequisite call, user interaction, authorization attestation, payload limits, returned fields, errors, retries, and duplicate handling. The minor gap around country_code and number_type is mitigated by the required get_verification_requirements workflow.

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?

With 0% schema description coverage, the description compensates well for most of the 11 parameters: attest_authorized, purpose variants, subject_type, fields, address keys, documents slots, files structure/content types/limits, and quote_id/number_id linkage. It does not fully explain the general semantics or accepted values for country_code and number_type beyond the SMS example.

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 names the exact verb and resource: sending the user's personal or company details and identity documents to the carrier for verification. Later references to get_verification_requirements, get_verification, and list_verifications make clear how this action differs from its siblings.

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?

It gives an explicit ordered workflow: call get_verification_requirements, ask the user for each field and file, then call this tool once. It also states when not to resubmit and routes a 409 to list_verifications, while naming get_verification for polling.

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