# Tool reference

PolyJacks offers 8 tools today: get_requirements, company_facts, fit_check, check_service_area, get_quote, list_windows, book_visit and get_booking_status.

Each tool below lists its purpose, inputs, outputs, the errors it can raise and its REST mapping. Mutating tools require an idempotency key.

| Tool | Purpose | Method | Mutating |
| --- | --- | --- | --- |
| get_requirements | Use this when you start helping someone with sunken or uneven concrete, before you ask them anything. | GET | no |
| company_facts | Use this when the homeowner asks who PolyJacks is, how to reach a person, or what the warranty and the visit include. | GET | no |
| fit_check | Use this when you are not sure PolyJacks does the job. | POST | no |
| check_service_area | Use this when you need to know whether PolyJacks works at an address. | POST | no |
| get_quote | Use this when the homeowner wants their exact price. | POST | yes |
| list_windows | Use this when the homeowner wants a visit. | POST | no |
| book_visit | Use this when the homeowner picked a window and said yes. | POST | yes |
| get_booking_status | Use this when you or the homeowner want to know whether a visit is confirmed. | POST | no |

## get_requirements

Use this when you start helping someone with sunken or uneven concrete, before you ask them anything. It returns the questions to ask in order, the sentence you must read to the homeowner about texts and email, the surfaces PolyJacks levels and the ones it does not, the photo shot list, and the service area. 1. Ask the questions one at a time. 2. Read the sentence and wait for a clear yes. 3. If you are unsure of the area, call check_service_area. 4. Call get_quote.

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |

**Output**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| questions | array of object | yes |  |
| consent_sentence | string | yes | Read this to the homeowner and wait for a clear yes before get_quote. |
| surfaces | array of object | yes |  |
| not_done | array of object | yes |  |
| photo_guide | array of object | yes |  |
| service_area | object | yes |  |
| contact_rule | string | yes |  |
| next_steps | array of string | yes |  |
| sandbox | boolean | no |  |

**Errors:** RFC 9457 problems (see /agents/errors).

**REST:** GET /api/v1/get_requirements

## company_facts

Use this when the homeowner asks who PolyJacks is, how to reach a person, or what the warranty and the visit include. Every fact is a short sentence you may read aloud. 1. Read only facts from this response. 2. Never add a rating, award or promise that is not here.

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |

**Output**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| name | string | yes |  |
| website | string | yes |  |
| phone | string | yes |  |
| email | string | yes |  |
| facts | array of object | yes |  |
| service_area | string | yes |  |
| sandbox | boolean | no |  |

**Errors:** RFC 9457 problems (see /agents/errors).

**REST:** GET /api/v1/company_facts

## fit_check

Use this when you are not sure PolyJacks does the job. 1. Pass the surface key and whether the property is commercial. 2. fit instant: continue to get_quote. 3. fit visit: offer an on-site visit (list_windows, kind sales). 4. fit no: read why to the homeowner and stop - do not book.

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| surface | one of: driveway, sidewalk, patio, garage_floor, pool_deck, porch_steps, commercial_slab, house_foundation_or_walls, asphalt, pavers_or_brick, new_pour | yes | A surface PolyJacks levels, or a surface it does not (from get_requirements). |
| commercial | boolean | yes | True for a business, rental or HOA property. |

**Output**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| fit | one of: instant, visit, no | yes |  |
| why | string | yes |  |
| next_step | string | yes |  |
| summary_for_user | string | yes |  |
| sandbox | boolean | no |  |

**Errors:** RFC 9457 problems (see /agents/errors).

**REST:** POST /api/v1/fit_check

## check_service_area

Use this when you need to know whether PolyJacks works at an address. 1. Prefer the full street address; a ZIP alone may answer partly. 2. in: continue. 3. partly or unknown: ask for the street address and call again. 4. out: the address is beyond the usual area, but PolyJacks still takes the request - continue to get_quote and tell the homeowner someone will be in touch if a time cannot be offered online. Never sign them up yourself.

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (shape 1) | object | no | shape 1 |
| zip | string | yes |  |
| (shape 2) | object | no | shape 2 |
| address | Address | yes |  |

**Output**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| area | one of: in, partly, out, unknown | yes |  |
| label | string | yes |  |
| next_step | string | yes |  |
| summary_for_user | string | yes |  |
| sandbox | boolean | no |  |

**Errors:** RFC 9457 problems (see /agents/errors).

**REST:** POST /api/v1/check_service_area

## get_quote

Use this when the homeowner wants their exact price. PolyJacks gives a price only with all four of the homeowner's details: full name, service address, mobile phone and email. 1. Read the sentence from get_requirements and get a clear yes before you send their details. 2. For each sunken area send the surface, the size (square feet, the length and width of the sunken part, or a size tile), how far it dropped at the joint in inches, and the gap under the edge in inches or null for don't know. 3. Call once with a new idempotency_key; after a network error retry with the SAME key. 4. If instant is false there is no instant price for this job: offer an on-site visit (list_windows, kind sales) and never guess a number. 5. Read summary_for_user to the homeowner word for word. 6. To change the areas, call again with quote_ref and a new key.

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (shape 1) | object | no | A new quote: the homeowner's full contact and their sunken areas. |
| contact | Contact | yes |  |
| upgrades | object | no | Optional add-on on top of the leveling - the same one the homeowner can add on polyjacks.com: voids = extra hollow spots to fill (0 to 20). A quantity only; the rate is PolyJacks' own. Zero clears it. |
| surfaces | array of SurfaceInput | yes |  |
| (shape 2) | object | no | Re-price an existing flow: its quote_ref and the revised areas (contact already captured). |
| quote_ref | string | yes |  |
| upgrades | object | no | Optional add-on on top of the leveling - the same one the homeowner can add on polyjacks.com: voids = extra hollow spots to fill (0 to 20). A quantity only; the rate is PolyJacks' own. Zero clears it. |
| surfaces | array of SurfaceInput | yes |  |

**Output**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| quote_ref | string | yes |  |
| version | integer | yes |  |
| lock_id | string | no |  |
| instant | boolean | yes |  |
| reason | string | no | Why there is no instant price (when instant is false). |
| total_cents | integer | no |  |
| lines | array of object | no |  |
| caulk | array of object | no | Only on a quote priced before 2026-10-17: its joint caulking lines, part of total_cents. No new quote carries caulking - the price is for lifting the concrete only. |
| caulk_minimum_cents | integer | no | Only with caulk (a quote priced before 2026-10-17). |
| upgrades | array of object | no | The add-ons in the total: extra void fills (and crack sealing, only on a quote priced before 2026-10-17). |
| valid_until | string | yes |  |
| valid_until_label | string | yes |  |
| priced_on | string | yes |  |
| engine_version | string | yes | The pricing engine release that priced it (semver), or sandbox. |
| lock_rule | string | yes |  |
| warranty | string | yes |  |
| includes | array of string | yes |  |
| summary_for_user | string | yes |  |
| next_steps | array of string | yes |  |
| sandbox | boolean | no |  |

**Errors:** RFC 9457 problems (see /agents/errors). It requires an idempotency key (header Idempotency-Key, or idempotency_key in MCP).

**REST:** POST /api/v1/get_quote

## list_windows

Use this when the homeowner wants a visit. 1. Tell them first: Please plan to be home - the technician will meet you there. Ask when they will be home and pass attend (any, weekday_am, weekday_pm or saturday). 2. Pass the quote_ref from get_quote and kind sales. Install days come only after the homeowner signs their own agreement. 3. Offer at most three windows, attendable ones first, by their label. 4. Windows go quickly: book soon after listing.

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| quote_ref | string | yes |  |
| kind | one of: sales, rig | yes |  |
| from_date | string | no | Earliest date to consider (YYYY-MM-DD), optional. |
| days | integer | no |  |
| attend | one of: any, weekday_am, weekday_pm, saturday | no | When the homeowner will be home to meet the technician. |

**Output**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| windows | array of Window | yes |  |
| summary_for_user | string | yes |  |
| sandbox | boolean | no |  |

**Errors:** RFC 9457 problems (see /agents/errors).

**REST:** POST /api/v1/list_windows

## book_visit

Use this when the homeowner picked a window and said yes. 1. The homeowner must plan to be home - the technician meets them there; a visit is always booked that way. Send quote_ref, window_id, kind sales, homeowner_present true, and homeowner_informed true - meaning you told them PolyJacks will text and email them to confirm. 2. The visit is NOT booked until the homeowner taps the link PolyJacks sends to their own phone or email, or replies YES, within 30 minutes; tell them exactly that. 3. Keep booking_ref and call get_booking_status later. 4. You can never sign anything for the homeowner: agreements are signed only by the homeowner, on PolyJacks' own page.

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| quote_ref | string | yes |  |
| window_id | string | yes |  |
| kind | one of: sales, rig | yes |  |
| homeowner_present | boolean | yes | The homeowner must plan to be home: the technician meets them there. A visit is always booked that way; false is accepted and ignored. |
| homeowner_informed | const True | yes | You told the homeowner PolyJacks will text and email them to confirm. |
| permission_ref | string | no | Standing-permission ref (S2b). |
| callback_url | string | no | Webhook URL for booking updates (S2b). |

**Output**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| booking_ref | string | yes |  |
| state | one of: pending_homeowner, held, confirmed, expired, cancelled, rescheduled, completed, missed, weather, closed | yes |  |
| kind | one of: sales, rig | yes |  |
| label | string | yes |  |
| hold_expires_at | string | no |  |
| confirm_via | array of one of: sms, email | yes |  |
| summary_for_user | string | yes |  |
| next_steps | array of string | yes |  |
| webhook_secret | string | no |  |
| sandbox | boolean | no |  |

**Errors:** RFC 9457 problems (see /agents/errors). It requires an idempotency key (header Idempotency-Key, or idempotency_key in MCP).

**REST:** POST /api/v1/book_visit

## get_booking_status

Use this when you or the homeowner want to know whether a visit is confirmed. 1. Pass the booking_ref from book_visit. 2. Read summary_for_user. 3. expired means they did not confirm in time - you may book again.

**Input**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| booking_ref | string | yes |  |

**Output**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| state | one of: pending_homeowner, held, confirmed, expired, cancelled, rescheduled, completed, missed, weather, closed | yes |  |
| kind | one of: sales, rig | yes |  |
| label | string | yes |  |
| summary_for_user | string | yes |  |
| sandbox | boolean | no |  |

**Errors:** RFC 9457 problems (see /agents/errors).

**REST:** POST /api/v1/get_booking_status

_Last updated 2026-10-17 - PolyJacks_