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 for the complete tools/list descriptions, JSON Schemas, runtime input-shape rules, and release provenance. The scenario fixtures 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 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

{
  "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

{
  "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 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.

​Tool reference

​check_availability

​Accepted input shapes

​Availability result

​Provider, plan, and offer fields

​validate_order

​Accepted input shapes

​Validation result

​Review shapes

​create_order

​Accepted input shape

​get_order

​Accepted input shape

​Order result

​Errors

​Expiry and processing limits

Tool reference

`check_availability`

Accepted input shapes

Availability result

Provider, plan, and offer fields

`validate_order`

Accepted input shapes

Validation result

Review shapes

`create_order`

Accepted input shape

`get_order`

Accepted input shape

Order result

Errors

Expiry and processing limits