hail

Official

by hail-hq

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Get verification requirements

get_verification_requirements

Read-onlyIdempotent

Read the carrier’s verification requirements before buying a phone number or filing US SMS registration, including required fields and documents. Use it when quote readiness shows verification_required.

Instructions

Read what the carrier needs to verify the organization before it can buy a number. Call this when quote_numbers shows an offer with readiness == "verification_required". Read-only.

    ``country_code`` is ISO alpha-2 (for example ``"GB"``). ``number_type``
    is ``local``, ``mobile``, ``national`` or ``toll_free``.
    ``subject_type`` is required: ``person`` (the user) or ``business``
    (the user's company). Never guess it: ask the user "you or your
    company?". The result's ``subject_types`` lists what the carrier
    accepts. The organization may hold one verification of each. ``quote_id`` is the
    offer's ``quote_id`` from quote_numbers. It is required for
    ``purpose='number'``: the form is the one for that offer.

    ``purpose`` is ``number`` (default, to buy a number) 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. If the error says to pass
    ``number_id``, pass the ``id`` of one of the organization's US numbers
    from list_numbers.

    Returns ``required`` (false means no verification is needed and
    submit_verification would fail), ``fields`` (values to collect),
    ``documents`` (slots, each with ``options``), ``address_required``.
    Skip any document slot whose ``needs_input`` is false: do not send it.

    Ask the USER for every value and every file. Never invent, guess or
    infer personal or company data. Never reuse data from another task.

    Errors come back as ``{"error": "<message>"}``.

Input Schema

Name	Required	Default
`purpose`	No	number
`quote_id`	No
`number_id`	No
`number_type`	Yes
`country_code`	Yes
`subject_type`	Yes

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 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"
+}

removedInput schema / properties / subject_type / default
```
Removed value: -"person"
```

changedInput schema / required

Previous value: -[
-  "country_code",
-  "number_type"
-]New value: +[
+  "country_code",
+  "number_type",
+  "subject_type"
+]

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?

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds substantial context: the carrier fee is debited at filing for `sms`, `required=false` means `submit_verification` would fail, document slots with `needs_input=false` must be skipped, and errors return as `{"error": "<message>"}`. It also emphasizes never guessing or reusing personal or company data.

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 definition is front-loaded with the core purpose and trigger, then moves through parameters, return semantics, and safety rules in a logical order. It is lengthy, but most of the length is justified by the tool's complexity; there is minor repetition around asking the user for values and never guessing data.

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 six parameters, only three required, 0% schema description coverage, and an output schema, the description is complete enough for correct invocation. It covers every parameter, explains key return fields despite the output schema, and gives error-handling and safety guidance that an agent would otherwise have to infer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: `country_code` is ISO alpha-2 with an example, `number_type` lists the allowed values, `subject_type` is required and must be asked from the user, `quote_id` comes from `quote_numbers` and is required for `purpose='number'`, and `number_id` is the organization's US number ID from `list_numbers` when instructed by an error.

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 states a specific verb and resource: read what a carrier requires to verify an organization before buying a number. It also names the exact triggering condition (`quote_numbers` shows `readiness == "verification_required"`), which clearly distinguishes it from sibling tools like `submit_verification` and `quote_numbers`.

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 explicitly says when to call this tool, including the `quote_numbers` readiness condition and the difference between `purpose='number'` and `purpose='sms'`. It also names alternatives and dependencies such as `quote_numbers`, `list_numbers`, and `submit_verification`, and explains the `number_id` fallback when an error instructs the caller to pass it.

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