InstaMaps
← All tools

Ask a table

Ask a question about a table

ask_table

Answer a plain-English question about a whole table (filters, counts, distances to a named place or a second list), showing how it read the question.

Read-onlySheets, files and runs by reference

Use it when

  • ✓ "Overdue or fault jobs within 5 miles of the Enfield depot"
  • ✓ Counts and breakdowns over thousands of rows without writing formulas
  • ✓ A question mixing column filters with places

Not for

Coverage: Any table; place questions use our UK and US geography.

Measured

  • A question that matches nothing says which condition emptied it and what the table holds instead (for example "Status holds: Fault (7), OK (7), Overdue (6)").

Sources

  • the rows you sent (as sent)
  • InstaMaps address index (OpenStreetMap, OpenAddresses) and postcodes.io (2026-10-08)

Basis: as the reading says

Inputs

question

string · required

The question, as a person would ask it.

records

array · up to 5000

The table as row objects (keys are the column names).

headers

array

Or the column names…

rows

array · up to 5000

…and the rows as arrays in the same order.

mode

string

— One of: rows · match · whyDefault: "rows"

reference_records

array

Optional second list for two-list questions (depots, competitors, stores).

source

object

Instead of typing rows: { sheet: "<Google Sheets link>", tab?: "Sites" } (shared with the InstaMaps service account, or viewable by anyone with the link), { file: "<Drive link to a CSV or Excel file>" }, or { run: "<run_id from an earlier answer>" }. Columns are found by their headers (id, name, address or its parts, lat/lng); name them if they aren't obvious (id_column, address_column, lat_column, lng_column; from_column and to_column for road distances). Rows with coordinates are used as they are.
The full description, as the server gives it to an agent

Answer a plain-English question about a table of rows (up to 5,000): filters ("open jobs in Leeds due this week", "accounts with no rep"), place questions ("customers within 5 miles of Manchester", "sites with 3+ pharmacies within 1 km", "in a flood zone", "high crime areas"), ranking, counts and group-bys ("homes by agent", "average price by area"), and two-list questions with reference_records ("customers within 10 km of any depot in the reference list"). Deterministic: the question is read into rules and tools, never answered by a model making up values, and `reading` says exactly how it was read. The first 200 matching rows come back in mode rows; past that use mode match. A zero result comes with a diagnosis (which part emptied it and the nearest non-empty reading). mode rows (default) returns the matching rows; match returns one TRUE/FALSE per input row in order (best for big tables: join it back in your own code); why returns the reading. Rows without lat/lng are placed from an address column when the question needs places. Place tools (nearby, crime, busy) cover the UK; flood covers England and the US.

A real answer

Captured from the live server on 2026-10-13, trimmed to the first rows.

Request

{
  "question": "Which accounts have annual revenue over 50k?",
  "records": [
    {
      "Account": "Rice University",
      "Address": "6100 Main St Houston TX 77005",
      "Annual revenue": 82000
    },
    {
      "Account": "Museum of Fine Arts",
      "Address": "1001 Bissonnet St Houston TX 77005",
      "Annual revenue": 23000
    },
    {
      "Account": "Toyota Center",
      "Address": "1510 Polk St Houston TX 77002",
      "Annual revenue": 61000
    }
  ]
}

The answer's first line

Read as: Annual revenue > 50,000. 2 of 3 rows match

The answer (trimmed)

{
  "confidence": {
    "summary": "All 1 high confidence.",
    "levels": {
      "high": 1,
      "medium": 0,
      "low": 0
    }
  },
  "question": "Which accounts have annual revenue over 50k?",
  "reading": "Annual revenue > 50,000",
  "matched": 2,
  "total": 3,
  "values": [
    [
      "Account",
      "Address",
      "Annual revenue"
    ],
    [
      "Rice University",
      "6100 Main St Houston TX 77005",
      82000
    ],
    [
      "Toyota Center",
      "1510 Polk St Houston TX 77002",
      61000
    ]
  ],
  "diagnosis": [],
  "tools": [],
  "reading_confidence": {
    "level": "high",
    "score": 0.9,
    "basis": "reading_sure"
  },
  "best_guess": false,
  "trace_id": "ye0prG6E8a4u5MgB2v7N",
  "ms": 729,
  "run": {
    "tool": "ask_table",
    "at": "2026-10-13T15:59:13.629Z",
    "question": "Which accounts have annual revenue over 50k?",
    "rows": 3,
    "matched": 2,
    "sources": [
      {
        "name": "the rows you sent",
        "as_of": "as sent"
      },
      {
        "name": "InstaMaps address index (OpenStreetMap, OpenAddresses) and postcodes.io",
        "as_of": "2026-10-08"
      }
    ],
    "basis": "as the reading says",
    "confidence": {
      "high": 1,
      "medium": 0,
      "low": 0
    }
  }
}

Use it in Claude

Add the connector https://get-instamaps.com/mcp and ask in plain words. 5,000 tool calls a day per person, reset at midnight UTC; a call counts once however many rows it carries; a sheet by reference is one call; checking a job is free.

How to add it →