aristocles-api

Use this to help users understand their total subscription spending.
Accepts service names or slugs and returns per-service breakdown plus totals.

Args:
    service_names: List of service names or slugs (e.g. ["Netflix", "spotify", "Xbox Game Pass"]).
                   Fuzzy matching is supported.
    country: ISO country code (default "AU").

Returns:
    JSON with total monthly spend, annual projection, and per-service breakdown
    including plan name, price, and billing period for each.

Example: calculate_subscription_total_tool(["Netflix", "Spotify", "Disney+"], "AU")

Use this to show users how much they can save by switching from monthly
to annual billing. Returns savings amount and percentage for each tier.

Args:
    service_name: Name of the service (e.g. "Calm", "Headspace").
                  Fuzzy matching is supported.
    country: ISO country code (default "AU").

Returns:
    JSON with each plan tier showing monthly and yearly pricing options,
    plus calculated annual savings amount and percentage.

Example: compare_billing_periods_tool("Calm", "AU")

Use this to show how much a service costs in different countries.
Helps users see price differences across markets (e.g. Netflix is cheaper in AU than US).

Args:
    service_name: Name of the service (e.g. "Netflix", "Spotify").
    countries: List of ISO country codes to compare (e.g. ["AU", "US", "GB"]).
               If not specified, returns all available countries.

Returns:
    JSON with the service's pricing in each country, including all plan tiers
    and monthly equivalents in local currency.

Example: compare_prices_across_countries("Netflix", ["AU", "US", "GB"])

Use this to compare pricing across 2-10 services. Returns all tiers
and monthly prices for each service so users can make informed decisions.

Args:
    service_names: List of 2-10 service names to compare
                   (e.g. ["Netflix", "Stan", "Disney+"]).
    country: ISO country code (default "AU").

Returns:
    JSON comparison table with each service's available plans and prices.

Example: compare_services(["Netflix", "Stan", "Disney+"], "AU")

Use this to help users understand price differences between states
(e.g. is a plumber cheaper in California vs New York?).

Args:
    trade: Trade slug (e.g. "plumber", "electrician").
    service: Service slug (e.g. "fix-leaking-tap", "install-power-point").
    locations: List of state/region codes to compare (e.g. ["NSW", "VIC"] or ["CA", "NY", "TX"]).
    country: Country code — AU, US, UK, CA, NZ (default "AU").

Returns:
    JSON with prices for each location side by side.

Example: compare_trade_prices_tool("plumber", "fix-leaking-tap", ["CA", "NY", "TX"], "US")

Use this to calculate an estimated cost for a job based on the trade service's
pricing and a quantity (e.g. 3 hours of labour, 50 sqm of painting).

Args:
    trade: Trade slug (e.g. "painter", "cleaner").
    service: Service slug (e.g. "interior-painting", "end-of-lease-clean").
    quantity: How many units (hours, jobs, sqm). Default 1.0.
    postcode: Postcode for the location.
    suburb: Suburb or city name.
    state: State/region code (e.g. "NSW", "CA", "England").
    region: Region name.
    country: Country code — AU, US, UK, CA, NZ (default "AU").

Returns:
    JSON with estimated low/high/avg cost, unit, and location context.

Example: estimate_job_cost_tool("painter", "interior-painting", quantity=50, state="CA", country="US")

Use this to help users save money by switching to a similar but cheaper service.
Returns alternatives sorted by price (cheapest first) with savings estimates.

Args:
    service_name: Name of the service to find alternatives for (e.g. "Netflix").
    country: ISO country code (default "AU").
    max_results: Maximum number of alternatives to return (default 5).

Returns:
    JSON list of alternatives with: name, cheapest price, monthly savings,
    feature overlap score (0-1, how similar the alternative is), and notes
    about what features differ.

Example: find_cheaper_alternatives("Netflix", "AU", 3)

Use this when a user wants to know where they can get the best price
for a particular trade job.

Args:
    trade: Trade slug (e.g. "roofer", "landscaper").
    service: Service slug (e.g. "roof-replacement", "lawn-mowing").
    states: List of state/region codes to check. Defaults to all states in the country.
    country: Country code — AU, US, UK, CA, NZ (default "AU").

Returns:
    JSON with all states ranked by average price, cheapest first.

Example: find_cheapest_trade_location("roofer", "roof-replacement", country="US")

Use this to understand an entire category: how many services are tracked,
what the price range is, average cost, and a list of all services ranked
by cheapest price.

Args:
    category: Category name or slug (e.g. "streaming-video" or "Music Streaming").
    country: ISO country code (default "AU").

Returns:
    JSON with: service count, price range (min/max), average monthly cost,
    and all services with their cheapest plan price.

Example: get_category_overview("streaming-video", "AU")

Use this to get a comprehensive pricing dataset suitable for analysis,
chart generation, or feeding into LLM context windows. Returns all
services with all plans and current prices.

Args:
    category: Optional category slug to filter (e.g. "streaming-video").
              If not specified, returns all categories.
    country: Optional ISO country code to filter (e.g. "AU").
             If not specified, returns all countries.
    format: "summary" for compact output, "detailed" for full data including
            effective dates and source URLs.

Returns:
    JSON array of all matching price records, sorted by category and service.

Example: get_price_feed("streaming-video", "AU", "summary")

Use this to see price increases or decreases for a service. Returns
historical price points with percentage change between each.

Args:
    service_name: Name of the service (e.g. "Spotify").
    country: ISO country code (default "AU").
    months: Number of months of history to return (default 12).

Returns:
    JSON with chronological price history, including effective date,
    price amount, and percentage change from previous price.

Example: get_price_history_tool("Spotify", "AU", 24)

Use this tool to look up how much a subscription service costs right now.
Supports 50+ services including Netflix, Spotify, Disney+, Adobe, NordVPN, etc.

Args:
    service_name: Name of the service (e.g. "Netflix", "spotify", "YouTube Premium").
                  Fuzzy matching is supported — you don't need the exact name.
    country: ISO 3166-1 alpha-2 country code (default "AU" for Australia).
    plan_tier: Optional filter for plan tier: "basic", "standard", "premium", "free".
               If not specified, returns all available tiers.

Returns:
    JSON with service name, all matching plans with price, currency,
    billing period, monthly equivalent, and when the price was last verified.

Example: get_subscription_price("Netflix", "AU", "standard")

Use this to look up how much a tradesperson costs. Returns price
ranges (low/high/average) per unit (hour, job, sqm, etc).

Args:
    trade: Trade slug or name (e.g. "plumber", "electrician", "painter").
    service: Optional specific service slug (e.g. "fix-leaking-tap").
             If not provided, returns prices for all services in the trade.
    postcode: Postcode (e.g. "2000" for Sydney, "90210" for Beverly Hills).
    suburb: Suburb or city name.
    state: State/region code (e.g. "NSW", "CA", "England", "ON", "Auckland").
    region: Region name (e.g. "Sydney Metro", "Greater London").
    country: Country code — AU, US, UK, CA, NZ (default "AU").

Returns:
    JSON with price ranges (low/high/avg), unit, source, and location data.

Example: get_trade_price("plumber", "fix-leaking-tap", state="CA", country="US")

Use this to discover what subscriptions are available in a given market,
grouped by category with the cheapest price shown for each service.

Args:
    country: ISO 3166-1 alpha-2 country code (e.g. "AU", "US", "IN", "GB").
    category: Optional category slug to filter by (e.g. "streaming-video", "ai-tools").

Returns:
    JSON with all services grouped by category, each showing the cheapest
    available price in that country.

Example: list_services_by_country_tool("IN", "ai-tools")

Use this to discover what trades are tracked (plumber, electrician, etc.)
and what specific services are available under each trade.

Args:
    search: Optional search term to filter trades by name.

Returns:
    JSON list of trades with name, slug, icon, and service count.

Example: list_trades("plumb")