> ## Documentation Index > Fetch the complete documentation index at: https://docs.letshum.com/llms.txt > Use this file to discover all available pages before exploring further. # Tool reference > Inputs, outputs, statuses, errors, side effects, and recovery rules for Hum's four MCP tools # Tool reference Hum Broadband MCP version `2.0.1` returns schema-version 4 objects with snake\_case field names. All tool inputs are closed: unknown fields and unsupported field combinations are rejected. Download the [released contract export](/mcp/contracts/released-contract.json) for the complete `tools/list` descriptions, JSON Schemas, runtime input-shape rules, and release provenance. The [scenario fixtures](/mcp/examples/scenarios.json) contain the synthetic examples used by these pages. This reference is frozen to `letshum/hum-mcp` commit `96eaeeaa6714010338822bf06b1d0f35b8a332f8`. JSON Schema describes each field, while the runtime shape rules below describe which fields may be sent together. A field being optional in a generated schema does not make every combination valid. ## `check_availability` Resolves an address and combines FCC area evidence with live provider qualification. It is read-only and idempotent for the same continuation. ### Accepted input shapes | Purpose | Exact fields | | ------------------------------------------------ | --------------------------------------- | | Start | `{address}` | | Select a candidate | `{candidate_id}` | | Select a candidate and supply its requested unit | `{candidate_id, unit}` | | Poll a lookup | `{lookup_id}` | | Answer the current question set | `{lookup_id, question_set_id, answers}` | | Field | Type | Meaning | | ----------------- | -------------------------- | --------------------------------------------------------------------------------------- | | `address` | string, 1–300 characters | Complete U.S. service address in natural language. | | `candidate_id` | string, 1–2,048 characters | Opaque candidate returned by Hum. Do not parse or edit it. | | `unit` | string, 1–100 characters | Unit requested for the chosen candidate. It is invalid without `candidate_id`. | | `lookup_id` | string, 1–256 characters | Opaque lookup used for polling or the current question set. | | `question_set_id` | string, 1–256 characters | Exact current question set returned for this lookup. | | `answers` | object | Keys and value types must match the returned questions. Send the required set together. | ### Availability result | Field | Type | Meaning | | --------------------- | ----------------- | ------------------------------------------------------------------------------------ | | `schema_version` | integer | `4`. | | `status` | enum | `checking`, `needs_information`, `complete`, `failed`, or `error`. | | `lookup_id` | string or null | Capability for polling, answering questions, and selecting an offer. | | `revision` | integer or null | Current lookup revision. A non-error result with a lookup ID includes a revision. | | `expires_at` | timestamp or null | When the lookup or its returned capabilities expire. | | `normalized_address` | object or null | Display address plus street, unit, city, state, and postal code. | | `sources` | object or null | Separate `fcc` and `live_provider_check` state. | | `providers` | array or null | Provider evidence, informational plans, and executable offers. | | `candidates` | array or null | Up to five address choices. Each has `candidate_id`, `display`, and `requires_unit`. | | `clarification_type` | enum or null | `candidate_selection` or `unit_required`. | | `required_field` | enum or null | Currently `unit` when a unit is required. | | `message` | string or null | Safe explanation for the current state. | | `question_set_id` | string or null | Current question-set identity. | | `questions` | array | Typed qualification questions. | | `retry_after_seconds` | integer or null | Minimum wait before polling. | | `warnings` | string array | Limits or partial-result warnings that must remain visible. | | `next_action` | string or null | Safe next step for this result. | | `error` | object or null | Structured tool-result error when `status` is `error`. | Each source has `status`, `checked_at`, `data_as_of`, and an optional structured `error`. Source status is `checking`, `needs_information`, `complete`, `failed`, or `timed_out`. Each question has a `question_id`, `prompt`, `type`, optional `choices`, `required`, and `sensitivity`. Question types are `string`, `boolean`, `single_choice`, and `date`. ### Provider, plan, and offer fields | Object | Fields and rules | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | Provider | `provider_id`, `name`, `provenance`, optional `fcc_match`, `qualification_status`, `orderable_through_hum`, `offers`, and `catalog_plans`. | | FCC match | `granularity` is `census_block` or `census_tract`; `data_as_of` can be null. | | Plan facts | Name, technology, download/upload Mbps, pricing, fees, contract terms, data limit, and conditions. Unknown commercial facts remain null. | | Catalog plan | Informational plan facts with no executable offer capability. | | Offer | Plan facts plus `offer_id`, `provider_id`, `qualification_revision`, `qualified_at`, `expires_at`, and `orderable_through_hum: true`. | Hum serializes these public commercial facts through a closed allowlist. Internal provider data, private rate identifiers, upstream transaction identifiers, and customer or contact values are not included in plan or offer objects, validation reviews or change comparisons, or order receipts. Money and fee amounts are integer cents with a three-letter currency code. Do not infer a regular price, promotion length, installation fee, equipment fee, contract, speed, or data limit when its field is null. See [Availability and offers](/mcp/availability-and-offers) for presentation rules. ## `validate_order` Creates or resumes a draft for one executable offer, collects the fields required by that offer, refreshes its facts, and returns an exact review. It is non-destructive and idempotent for the same draft state. It creates no order and sends no fulfillment request. ### Accepted input shapes | Purpose | Exact fields | | -------------------------- | ------------------------------------------- | | Start validation | `{lookup_id, offer_id}` | | Poll or refresh a checkout | `{checkout_id}` | | Supply requested details | `{checkout_id, expected_revision, details}` | | Field | Type | Meaning | | ------------------- | ------- | --------------------------------------------------------------------------------------- | | `lookup_id` | string | Lookup that returned the executable offer. | | `offer_id` | string | Exact current server-returned offer ID. | | `checkout_id` | string | Opaque checkout capability returned by validation. | | `expected_revision` | integer | Revision returned with the current missing-field request. Prevents stale updates. | | `details` | object | Only the customer, installation, preference, mailing, and consent fields Hum requested. | `details.customer` can contain first name, last name, email, phone number, a four-digit service PIN, date of birth, billing preferences, and a mailing address. `details.installation` can contain an installation type, desired service start date, and first and second preferred date/time windows. `details.consents` maps returned consent keys to booleans. When Hum requests a mailing-address choice, send `details.customer.mailing_address.same_as_service`. If it is `false`, also send `line1`, `city`, `state`, and `postal_code` together; `line2` remains optional. The selected provider determines which fields are required. Do not assume that a PIN, birth date, installation choice, preference, mailing address, or consent is universal. Hum never requests card data, Social Security numbers, existing-account passwords, or payment authorization through this tool. ### Validation result | Field | Type | Meaning | | --------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- | | `schema_version` | integer | `4`. | | `checkout_id` | string or null | Capability for all later validation, submission, and retrieval calls. | | `revision` | integer or null | Current draft revision. | | `status` | enum | `checking`, `needs_information`, `ready`, `offer_changed`, `unavailable`, `expired`, `failed`, or `error`. | | `required_fields` | string array | Exact detail paths that remain required. | | `field_errors` | object | Field paths mapped to safe correction messages. | | `review` | object or null | Exact offer and customer-facing terms to present before authorization. | | `terms_hash` | string or null | Digest that binds authorization to the returned review. | | `validation_token` | string or null | Opaque token authorizing submission of the validated review. | | `expires_at` | timestamp or null | Expiry for the ready validation. Revalidate after expiry. | | `retry_after_seconds` | integer or null | Minimum wait before polling a checking draft. | | `next_action` | string or null | Required next step. | | `error` | object or null | Structured tool-result error when `status` is `error`. | ### Review shapes A ready validation returns a closed `review` object: | Field | Meaning | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `provider_name` | Public provider name. | | `selected_offer` | Current plan facts, including pricing, fees, contract terms, data limit, and conditions. | | `service_address` | Display address and unit. | | `installation` | Returned installation type, desired start date, and preferred windows, or null. | | `billing_preferences` | Returned paperless-billing and automatic-payment preferences, or null. These are preferences, not payment authorization. | | `consents` | Provider consent keys and the reviewed boolean values. | | `unknown_charges_remain_unknown` | Always `true`; the review does not convert unknown charges to zero. | An `offer_changed` validation returns `previous_offer`, `current_offer`, and a non-empty `changed_fields` list instead. Present that comparison and obtain a fresh decision before continuing. Reviews do not contain the customer's name, contact details, mailing address, service PIN, or date of birth. Present the review returned by the current revision; do not reconstruct it from earlier availability data. ## `create_order` Commits a ready validation after the host has presented the exact review and obtained the user's authorization. This tool has a side effect and is marked destructive. Its idempotency key makes an identical replay refer to the same intended submission; it is not permission to retry an uncertain network outcome blindly. ### Accepted input shape ```json theme={null} { "checkout_id": "checkout_example_01", "validation_token": "validation_example_01", "idempotency_key": "order-attempt-example-01", "confirmation": { "terms_hash": "terms_example_01", "confirmed": true } } ``` | Field | Type | Meaning | | ------------------------- | ------------------------ | ----------------------------------------------- | | `checkout_id` | string | Ready checkout capability. | | `validation_token` | string | Token from the same ready revision and review. | | `idempotency_key` | string, 1–128 characters | Stable identity for this exact intended order. | | `confirmation.terms_hash` | string | Exact hash from the review the user authorized. | | `confirmation.confirmed` | boolean literal | Must be `true` after authorization. | The checkout, validation token, terms hash, and idempotency key must agree. A new key does not make a second order safe. After a timeout, disconnect, or lost response, call `get_order` first. ## `get_order` Reads the latest persisted order and fulfillment evidence. It is read-only and idempotent. ### Accepted input shape ```json theme={null} { "checkout_id": "checkout_example_01" } ``` `get_order` uses the opaque checkout ID, not the displayable order number. ## Order result `create_order` and `get_order` return the same order-envelope type. | Field | Type | Meaning | | ------------------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `schema_version` | integer | `4`. | | `order_id` | string or null | Displayable Hum order reference. It does not authorize retrieval. | | `status` | enum | `queued`, `submitting`, `accepted_by_fulfillment`, `rejected_by_fulfillment`, `submission_unknown`, `not_submitted`, or `error`. | | `submitted_at` | timestamp or null | Recorded submission time when known. | | `last_checked_at` | timestamp or null | When Hum last checked the fulfillment evidence. | | `provider_name` | string or null | Public provider name. | | `selected_offer_summary` | object or null | Non-sensitive plan facts for the selected offer. | | `evidence` | object or null | Evidence `kind` and `recorded_at` timestamp. | | `next_action` | string or null | Required follow-up or reconciliation step. | | `error` | object or null | Structured tool-result error when `status` is `error`. | See [fulfillment states](/mcp/ordering-and-recovery#fulfillment-states) before displaying a status. ## Errors Hum can reject a malformed MCP request before a tool runs. An MCP invalid-parameters error means the arguments did not match a closed schema or one of the accepted runtime shapes. It has no tool result and no side effect. A tool-result error uses `status: "error"` and this structure: | Field | Meaning | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `code` | Stable safe category: `invalid_request`, `invalid_address`, `invalid_answer`, `not_found`, `expired`, `offer_changed`, `offer_unavailable`, `validation_required`, `confirmation_required`, `idempotency_conflict`, `duplicate_order`, `rate_limited`, or `temporarily_unavailable`. | | `message` | Safe human-readable explanation. | | `retryable` | Whether the operation class can be retried under the returned guidance. | | `retry_after_seconds` | Minimum delay when a retry is permitted. | | `field_errors` | Optional field-specific correction messages. | | `next_action` | Required next step. | | `correlation_id` | Safe identifier to include in a support request. | `retryable: true` does not override create-order recovery. If a create response is uncertain, call `get_order` first and follow its persisted `status` and `next_action`. ## Expiry and processing limits | Resource or operation | Released limit | | ------------------------------------------- | ----------------------------------------------------------- | | Address candidate | 10 minutes | | Lookup | 10 minutes; accepted answers and revision advances renew it | | Executable offer | 15 minutes | | Ready validation | 5 minutes | | Draft | 24 hours | | Checkout read capability | 90 days | | Availability or validation work | 90 seconds per attempt | | Returned poll guidance | 3 seconds when supplied; follow the current response | | Accepted duplicate screening | 24 hours; unresolved matching submissions remain blocked | | Sensitive fields after `submission_unknown` | At most 30 days; definitive outcomes purge them earlier | These limits do not reserve provider inventory or guarantee that an offer, price, or serviceability result will remain unchanged. Revalidate after an expiry and follow the returned next action.