FindBroadband

Use when you have a UK postcode and need the exact property (broadband availability differs per property). Ask for the postcode and house number or name in ONE question up front. If the user's message already identifies the property (e.g. '1 Fyfields, SS13 1HJ'), match it against the returned list yourself and proceed straight to the next tool, briefly saying which address you're checking. Only show the numbered list and ask them to pick when the match is ambiguous or they gave postcode only and want precision. Then pass the entry's uprn (never shown to the user) plus its display_address as address_label to the other tools.

{
  "type": "object",
  "properties": {
    "postcode": {
      "type": "string",
      "minLength": 5,
      "maxLength": 10,
      "description": "UK postcode, e.g. 'SS13 1HJ'. When asking, request the postcode and house number or name together in one question rather than two rounds."
    }
  },
  "required": [
    "postcode"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "postcode": {
      "type": "string"
    },
    "addresses": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uprn": {
            "type": "string"
          },
          "display_address": {
            "type": "string"
          }
        },
        "required": [
          "uprn",
          "display_address"
        ],
        "additionalProperties": false
      }
    },
    "count": {
      "type": "number"
    },
    "note": {
      "type": "string"
    },
    "checked_at": {
      "type": "string"
    }
  },
  "required": [
    "postcode",
    "addresses",
    "count",
    "checked_at"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use when the user wants broadband deals, offers or packages available where they live. If the user has not picked an address yet, call search_addresses first and offer the list; fall back to postcode-only search when they decline or no addresses are found (the precision field says which you got). Pass address_label alongside uprn once an address is picked. Translate the user's needs into the filter inputs. Present the returned picks and computed costs verbatim: never re-rank, re-filter or recalculate totals yourself. total_contract_cost and effective_monthly_cost already account for intro pricing, post-intro rises and setup fees. After presenting, ask one short follow-up about what matters to them (budget, speed needs, contract length, avoiding price rises) and refine with the filter inputs.

{
  "type": "object",
  "properties": {
    "postcode": {
      "type": "string",
      "minLength": 5,
      "maxLength": 10,
      "description": "UK postcode, e.g. 'SS13 1HJ'. When asking, request the postcode and house number or name together in one question rather than two rounds."
    },
    "uprn": {
      "type": "string",
      "pattern": "^\\d{6,14}$",
      "description": "Property identifier from search_addresses. Pass it whenever the user has picked an address so results become address-precise instead of postcode-wide. Never show this number to the user."
    },
    "address_label": {
      "type": "string",
      "maxLength": 160,
      "description": "The display_address the user picked from search_addresses, passed back verbatim. Carried into the switch link so the FindBroadband site greets the user with their address instead of asking again."
    },
    "max_monthly_price": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 500,
      "description": "Budget cap in GBP per month, from phrases like 'under £30'."
    },
    "min_speed_mbps": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000,
      "description": "Minimum download speed in Mbps. Translate needs rather than inventing numbers: two people working from home plus gaming needs about 150, a heavy 4K household about 300, email and browsing about 35."
    },
    "provider": {
      "type": "string",
      "maxLength": 60,
      "description": "Only show deals from this provider, when the user names one."
    },
    "max_contract_months": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 36,
      "description": "Longest contract the user will accept, e.g. 12 for 'no long contracts'."
    },
    "exclude_mid_contract_rises": {
      "type": "boolean",
      "description": "true when the user says they want no mid-contract price rises."
    },
    "include_mobile_broadband": {
      "type": "boolean",
      "description": "Include 4G/5G home broadband. Default false (fixed-line only). Set true only if the user asks for mobile or wireless broadband."
    }
  },
  "required": [
    "postcode"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "postcode": {
      "type": "string"
    },
    "uprn": {
      "type": "string"
    },
    "precision": {
      "type": "string",
      "enum": [
        "address",
        "postcode"
      ]
    },
    "total_matching_filters": {
      "type": "number"
    },
    "total_available_at_location": {
      "type": "number"
    },
    "filters_relaxed": {
      "type": "boolean"
    },
    "provider_filter_note": {
      "type": "string"
    },
    "picks": {
      "type": "object",
      "properties": {
        "cheapest": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "deal_id": {
                  "type": "string"
                },
                "provider": {
                  "type": "string"
                },
                "package_name": {
                  "type": "string"
                },
                "download_mbps": {
                  "type": "number"
                },
                "upload_mbps": {
                  "type": "number"
                },
                "monthly_price": {
                  "type": "number"
                },
                "price_after_intro": {
                  "type": "number"
                },
                "intro_months": {
                  "type": "number"
                },
                "setup_fee": {
                  "type": "number"
                },
                "contract_months": {
                  "type": "number"
                },
                "total_contract_cost": {
                  "type": "number"
                },
                "effective_monthly_cost": {
                  "type": "number"
                },
                "mid_contract_rise": {
                  "type": "object",
                  "properties": {
                    "has_rise": {
                      "type": "boolean"
                    },
                    "note": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "has_rise"
                  ],
                  "additionalProperties": false
                },
                "connection_type": {
                  "type": "string"
                },
                "gift": {
                  "type": "string",
                  "description": "Provider incentive shown on the deal card: a gift card / reward, or a switching credit. NOT included in any cost figure. A switching credit (e.g. 'up to £300') only offsets early-termination fees the user owes their CURRENT provider — worth £0 to someone out of contract, so explain it as conditional, never as a discount. Gift cards are real value but not bill money."
                },
                "continue_url": {
                  "type": "string"
                }
              },
              "required": [
                "deal_id",
                "provider",
                "package_name",
                "download_mbps",
                "upload_mbps",
                "monthly_price",
                "setup_fee",
                "contract_months",
                "total_contract_cost",
                "effective_monthly_cost",
                "mid_contract_rise",
                "continue_url"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "best_value": {
          "anyOf": [
            {
              "$ref": "#/properties/picks/properties/cheapest/anyOf/0"
            },
            {
              "type": "null"
            }
          ]
        },
        "fastest": {
          "anyOf": [
            {
              "$ref": "#/properties/picks/properties/cheapest/anyOf/0"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "cheapest",
        "best_value",
        "fastest"
      ],
      "additionalProperties": false
    },
    "deals": {
      "type": "array",
      "items": {
        "$ref": "#/properties/picks/properties/cheapest/anyOf/0"
      }
    },
    "checked_at": {
      "type": "string"
    }
  },
  "required": [
    "postcode",
    "precision",
    "total_matching_filters",
    "total_available_at_location",
    "picks",
    "deals",
    "checked_at"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use when the user asks whether their CURRENT broadband bill or plan, or a RENEWAL or retention offer their provider quoted, is expensive, competitive or worth switching from. Compares what they pay against comparable deals actually available at their address and returns a computed verdict with true 24-month savings. Present the verdict and figures verbatim rather than deriving your own. Each alternative's cost_24_months is its true cost over the 24-month comparison window; ask get_deal_details for a specific deal's whole-contract total. Set quote_type to 'renewal_offer' when evaluating a renewal quote.

{
  "type": "object",
  "properties": {
    "postcode": {
      "type": "string",
      "minLength": 5,
      "maxLength": 10,
      "description": "UK postcode, e.g. 'SS13 1HJ'. When asking, request the postcode and house number or name together in one question rather than two rounds."
    },
    "uprn": {
      "type": "string",
      "pattern": "^\\d{6,14}$",
      "description": "Property identifier from search_addresses. Pass it whenever the user has picked an address so results become address-precise instead of postcode-wide. Never show this number to the user."
    },
    "address_label": {
      "type": "string",
      "maxLength": 160,
      "description": "The display_address the user picked from search_addresses, passed back verbatim. Carried into the switch link so the FindBroadband site greets the user with their address instead of asking again."
    },
    "monthly_bill": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 500,
      "description": "What the user currently pays per month in GBP (or the renewal price quoted to them)."
    },
    "current_speed_mbps": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000,
      "description": "The user's current download speed in Mbps. If they only know their package name, ask or estimate from the provider's naming (e.g. 'M125' is about 132)."
    },
    "current_provider": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60,
      "description": "The user's current broadband provider, as they said it, e.g. 'Sky' or 'Virgin Media'."
    },
    "quote_type": {
      "type": "string",
      "enum": [
        "current_bill",
        "renewal_offer"
      ],
      "description": "'renewal_offer' when the user is evaluating a renewal or retention price their provider quoted; 'current_bill' (default) when it is what they pay today."
    }
  },
  "required": [
    "postcode",
    "monthly_bill",
    "current_speed_mbps",
    "current_provider"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "quote_type": {
      "type": "string",
      "enum": [
        "current_bill",
        "renewal_offer"
      ]
    },
    "verdict": {
      "type": "string",
      "enum": [
        "overpaying",
        "competitive",
        "no_better_deal_found"
      ]
    },
    "current": {
      "type": "object",
      "properties": {
        "provider": {
          "type": "string"
        },
        "provider_resolved": {
          "type": [
            "string",
            "null"
          ]
        },
        "monthly_bill": {
          "type": "number"
        },
        "speed_mbps": {
          "type": "number"
        }
      },
      "required": [
        "provider",
        "provider_resolved",
        "monthly_bill",
        "speed_mbps"
      ],
      "additionalProperties": false
    },
    "best_alternative": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "deal_id": {
              "type": "string"
            },
            "provider": {
              "type": "string"
            },
            "package_name": {
              "type": "string"
            },
            "download_mbps": {
              "type": "number"
            },
            "monthly_price": {
              "type": "number"
            },
            "price_after_intro": {
              "type": "number"
            },
            "intro_months": {
              "type": "number"
            },
            "contract_months": {
              "type": "number"
            },
            "effective_monthly_cost": {
              "type": "number"
            },
            "connection_type": {
              "type": "string"
            },
            "continue_url": {
              "type": "string"
            },
            "cost_24_months": {
              "type": "number"
            },
            "mid_contract_rise": {
              "type": "object",
              "properties": {
                "has_rise": {
                  "type": "boolean",
                  "const": true
                },
                "note": {
                  "type": "string"
                }
              },
              "required": [
                "has_rise",
                "note"
              ],
              "additionalProperties": false
            },
            "saved_per_month": {
              "type": "number"
            },
            "saved_24_months": {
              "type": "number"
            },
            "pct_over": {
              "type": "number"
            },
            "gift": {
              "type": "string",
              "description": "Provider incentive shown on the deal card: a gift card / reward, or a switching credit. NOT included in any cost figure. A switching credit (e.g. 'up to £300') only offsets early-termination fees the user owes their CURRENT provider — worth £0 to someone out of contract, so explain it as conditional, never as a discount. Gift cards are real value but not bill money."
            }
          },
          "required": [
            "deal_id",
            "provider",
            "package_name",
            "download_mbps",
            "monthly_price",
            "contract_months",
            "effective_monthly_cost",
            "continue_url",
            "cost_24_months",
            "saved_per_month",
            "saved_24_months",
            "pct_over"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "runners_up": {
      "type": "array",
      "items": {
        "$ref": "#/properties/best_alternative/anyOf/0"
      }
    },
    "alternatives": {
      "type": "array",
      "items": {
        "$ref": "#/properties/best_alternative/anyOf/0"
      }
    },
    "speed_floor_used": {
      "type": "number"
    },
    "total_deals_at_address": {
      "type": "number"
    },
    "precision": {
      "type": "string",
      "enum": [
        "address",
        "postcode"
      ]
    },
    "provider_note": {
      "type": "string"
    },
    "checked_at": {
      "type": "string"
    }
  },
  "required": [
    "quote_type",
    "verdict",
    "current",
    "best_alternative",
    "runners_up",
    "alternatives",
    "speed_floor_used",
    "total_deals_at_address",
    "precision",
    "checked_at"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Use when the user asks for more detail about ONE specific deal already returned by another tool: setup costs, price-rise terms, what happens after the intro period and availability at their address. Pass the deal_id from the earlier result, plus the user's postcode, uprn and address_label when known so availability is confirmed at their address. total_contract_cost here is the whole-contract figure over contract_months.

{
  "type": "object",
  "properties": {
    "deal_id": {
      "type": "string",
      "pattern": "^\\d{1,12}$",
      "description": "The deal_id from a previous find_broadband_deals or check_if_overpaying result."
    },
    "postcode": {
      "type": "string",
      "minLength": 5,
      "maxLength": 10,
      "description": "Pass the user's postcode when known so availability is checked at their address."
    },
    "uprn": {
      "type": "string",
      "pattern": "^\\d{6,14}$",
      "description": "Property identifier from search_addresses. Pass it whenever the user has picked an address so results become address-precise instead of postcode-wide. Never show this number to the user."
    },
    "address_label": {
      "type": "string",
      "maxLength": 160,
      "description": "The display_address the user picked from search_addresses, passed back verbatim. Carried into the switch link so the FindBroadband site greets the user with their address instead of asking again."
    }
  },
  "required": [
    "deal_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "deal_id": {
      "type": "string"
    },
    "provider": {
      "type": "string"
    },
    "package_name": {
      "type": "string"
    },
    "download_mbps": {
      "type": "number"
    },
    "upload_mbps": {
      "type": "number"
    },
    "monthly_price": {
      "type": "number"
    },
    "price_after_intro": {
      "type": "number"
    },
    "intro_months": {
      "type": "number"
    },
    "setup_fee": {
      "type": "number"
    },
    "contract_months": {
      "type": "number"
    },
    "total_contract_cost": {
      "type": "number"
    },
    "effective_monthly_cost": {
      "type": "number"
    },
    "mid_contract_rise": {
      "type": "object",
      "properties": {
        "has_rise": {
          "type": "boolean"
        },
        "note": {
          "type": "string"
        }
      },
      "required": [
        "has_rise"
      ],
      "additionalProperties": false
    },
    "connection_type": {
      "type": "string"
    },
    "gift": {
      "type": "string",
      "description": "Provider incentive shown on the deal card: a gift card / reward, or a switching credit. NOT included in any cost figure. A switching credit (e.g. 'up to £300') only offsets early-termination fees the user owes their CURRENT provider — worth £0 to someone out of contract, so explain it as conditional, never as a discount. Gift cards are real value but not bill money."
    },
    "continue_url": {
      "type": "string"
    },
    "availability": {
      "type": "string",
      "enum": [
        "available_at_address",
        "not_checked",
        "unavailable_at_address"
      ]
    },
    "price_rise_terms": {
      "type": "string"
    },
    "estimated_speed_at_address_mbps": {
      "type": "object",
      "properties": {
        "min": {
          "type": "number"
        },
        "max": {
          "type": "number"
        }
      },
      "additionalProperties": false
    },
    "switch_time": {
      "type": "string"
    },
    "switching_downtime": {
      "type": "string"
    },
    "checked_at": {
      "type": "string"
    }
  },
  "required": [
    "deal_id",
    "provider",
    "package_name",
    "download_mbps",
    "upload_mbps",
    "monthly_price",
    "setup_fee",
    "contract_months",
    "total_contract_cost",
    "effective_monthly_cost",
    "mid_contract_rise",
    "continue_url",
    "availability",
    "checked_at"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}