ALT/FNDATA

List a table's column names and types so you can build a precise query. Call this before query_table (or before adding `filters` to market_stats / price_trend) to learn the exact field names a table exposes — e.g. whether prices are in `usd_price_decimal`, how the brand/designer field is named, or whether a `carats` column exists. Avoids guessing column names. Example: before querying Rolex sales, call get_table_schema("watches") to confirm the brand field is `designer` and the price field is `usd_price_decimal`. Args: table: Table alias (call list_tables for the full set). Note: "gems" = loose/unmounted stones; "jewelry" = finished/mounted pieces.

Show ALT/FNDATA price alerts (read-only) or explain how to set them up. Price alerts watch a saved item and fire when a matching lot sells at or below your target. They belong to a signed-in ALT/FNDATA account, not to an API key — so alerts are created and managed in the app (app.altfndata.com), and this MCP can only read/report them. If your key isn't tied to a signed-in session, this returns guidance on enabling alerts (allowance: free 0 · registered 1 · collector 10 · pro 100 · included with Membership) rather than a data feed. Args: limit: Max fired alerts to show if the alerts feed is reachable (default 25).

List every auction-data table ALT/FNDATA serves, with live descriptions and column counts. Start here whenever a question names a category and you need the right table alias to pass to get_table_schema, query_table, market_stats or price_trend. The set spans watches, jewelry (finished/mounted pieces), gems (loose stones), handbags, cars, motorcycles, wine & whisky, works of art, fine art, coins, and more. Always call this for the current set rather than assuming it, and note that loose gemstones live in `gems`, not `jewelry`. Example: for "what categories of data do you have?" or before "show me the most expensive coins sold at auction" (to confirm the `coins` alias exists).

Precomputed model-level price index (headline figures) for a model or brand. Reads the ALT/FNDATA Index's precomputed hot-stats — instant, no scan. Give a typed model `query` (e.g. "Hermès Birkin 25", "Rolex Daytona 116500") for a single model's realized-price band (low / 25th / median / 75th / high), sample size, and recent trend; or give a `brand` alone for that brand's whole set of model indices. Covered categories are handbags, watches, and cars. For other categories, use market_stats (whole-market read) or price_trend instead — this tool never invents a figure that isn't precomputed. Args: query: A specific model to look up (brand + model + optional size/material). brand: A brand to list all model indices for (alternative to query). category: One of "handbags", "watches", "cars". Inferred from the text when omitted.

Summarize the realized-price market for a table or a filtered segment. Returns count of sales, median, 25th/75th percentiles, average, min/max of `usd_price_decimal`, the sale-date span, and the top vendors by volume — all computed server-side over the full matching set (not a sample). Args: table: Table alias (call list_tables first). "gems" = LOOSE, unmounted stones (use for a gemstone-market read); "jewelry" = FINISHED, mounted pieces. A loose-stone question can span both. filters: Optional list of filter dicts, same shape as query_table (field/op/value). Narrow to a segment, e.g. [{"field": "designer", "op": "eq", "value": "Patek Philippe"}]. sold_only: When true (default), restricts to sold lots with a positive USD price so the stats reflect realized transactions.

Estimate a single item's fair-value range from comparable auction sales. Give either a free-text description (e.g. "Hermès Birkin 25 Togo, gold hardware") OR a lot URL from an auction house. Returns a realized-price range (low / median / high), a confidence read, and comparable sales with source links. Best for valuing ONE specific piece; for a whole-market read use market_stats. Live comp categories are handbags, watches, and cars. Loose gemstones and jewelry are intentionally held from comp-matching (under-specified colored stones give unreliable medians) — for those, use market_stats on `gems` (loose stones) or `jewelry` (mounted pieces) instead. Args: description: Free-text item description. lot_url: A lot URL from an auction house (alternative to description). category: One of "handbags", "watches", "cars". Inferred from the text if omitted.

Show how realized prices moved over time for a table or filtered segment. Buckets sold lots by sale period and reports, per period, the number of sales, the median, and the average `usd_price_decimal`. Args: table: Table alias (call list_tables first). Gems = loose stones; jewelry = mounted pieces. filters: Optional filter dicts (field/op/value), same shape as query_table. by: Time bucket — "year" (default), "quarter", or "month". sold_only: Restrict to sold lots with a positive USD price (default true).

Query one known table with precise filtering, sorting, and field selection. Use this when you already know the target table (from list_tables) and want exact control — e.g. "the 10 most expensive Rolex watches sold since 2020" becomes table="watches", filters on `designer`/`sale_date`, sort by `usd_price_decimal` desc, limit 10. If you don't know which table holds the item, use `search` (whole-market) instead; for aggregate figures (median, percentiles) use `market_stats`. Args: table: Table alias (call list_tables for the full set). "gems" = loose stones (use for gemstone valuations); "jewelry" = finished pieces. fields: List of column names to return (e.g., ["item_title", "vendor", "usd_price_decimal"]). If not specified, returns all columns. filters: List of filter conditions. Each filter is a dict with: - "field": column name - "op": operator — one of "eq", "neq", "gt", "gte", "lt", "lte", "like", "in", "not_in", "is_null", "is_not_null" - "value": the value to compare against Example: [{"field": "vendor", "op": "eq", "value": "Phillips"}, {"field": "usd_price_decimal", "op": "gte", "value": 50000}] sort_field: Column name to sort by (e.g., "usd_price_decimal" or "sale_date") sort_direction: "asc" or "desc" (default: "desc") limit: Maximum rows to return (default: 20, max: 500) offset: Number of rows to skip for pagination (default: 0)

Whole-market keyword search across every ALT/FNDATA category at once. Runs a server-side free-text search (the same engine behind the ALT/FNDATA Search app): your `query` is split into tokens, each matched across item_title, designer, vendor, gem_type, primary_gem, origin, color, model and sale_title with synonym expansion (e.g. ruby↔rubis, jade↔jadeite). With no `category` it fans out across the whole market and merges the top realized sales by USD price — so you don't have to guess which table holds an item. Args: query: Free-text keywords, e.g. "ruby ring", "Daytona 116500", "Birkin 25". category: Optional hint to narrow the search — a table alias (e.g. "watches") or a plain word ("cars", "gemstone"). A gemstone/stone hint searches BOTH gems (loose) and jewelry (mounted); omit it to search everything. filters: Optional extra filter dicts (same field/op/value shape as query_table), AND-ed with the keyword match — e.g. [{"field": "usd_price_decimal", "op": "gte", "value": 50000}]. limit: Max merged results to return (default 25, max 100).