LatLong Maps is an MCP server published by ai.latlong, hosted at geocp.latlong.ai. When last checked on 2026-11-22 it was working: it answers and lists its tools. It declares 8 tools, including compute_column, geocode, get_capabilities, pincode_lookup, question_to_map.
Turn CSV or Excel data into styled choropleth and categorical maps of India from plain language.
Nothing else in the archive shares these values.
Squares are this server's values; dots are other servers sharing them. A shared address or publisher is a lead, not proof of a common operator.
Inferred from the host name and headers: what a server runs on, not who runs it.
Add a column computed from arithmetic over an uploaded file's numeric columns, then map it. Pass file_key, expression and result_column, e.g. {"file_key": "...", "expression": "(revenue - cost) / population", "result_column": "profit_per_capita"}. Operators: + - * / % and parentheses, or a single comparison (> < >= <= ==) between two operands. Column names are matched case-insensitively and may contain spaces; quote a name that looks like a number with backticks, e.g. `2023` - `2020`. A row whose referenced cells are blank or a missing-data marker (-, NA, N/A), or that divides by zero, gets an empty value. The uploaded file is never changed: the reply carries a NEW file_key holding a copy with the column added. To map it, call question_to_map with that file_key and value_column = result_column. Use this instead of calculating values yourself. If it is refused, tell the user the error; do not calculate the values yourself or upload a rewritten file.
| Parameter | Type | Description |
|---|---|---|
| sheet | string | |
| file_key * | string | |
| expression * | string | arithmetic over column names, e.g. (revenue - cost) / population; operators + - * / % and parentheses, or one comparison > < >= <= == |
| result_column | string |
{
"name": "compute_column",
"description": "Add a column computed from arithmetic over an uploaded file's numeric columns, then map it. Pass file_key, expression and result_column, e.g. {\"file_key\": \"...\", \"expression\": \"(revenue - cost) / population\", \"result_column\": \"profit_per_capita\"}.\n\nOperators: + - * / % and parentheses, or a single comparison (> < >= <= ==) between two operands. Column names are matched case-insensitively and may contain spaces; quote a name that looks like a number with backticks, e.g. `2023` - `2020`. A row whose referenced cells are blank or a missing-data marker (-, NA, N/A), or that divides by zero, gets an empty value.\n\nThe uploaded file is never changed: the reply carries a NEW file_key holding a copy with the column added. To map it, call question_to_map with that file_key and value_column = result_column. Use this instead of calculating values yourself. If it is refused, tell the user the error; do not calculate the values yourself or upload a rewritten file.",
"inputSchema": {
"type": "object",
"required": [
"file_key",
"expression"
],
"properties": {
"sheet": {
"type": "string"
},
"file_key": {
"type": "string"
},
"expression": {
"type": "string",
"description": "arithmetic over column names, e.g. (revenue - cost) / population; operators + - * / % and parentheses, or one comparison > < >= <= =="
},
"result_column": {
"type": "string"
}
},
"additionalProperties": false
}
}Geocode addresses from an uploaded CSV or XLSX file into latitude/longitude. Pass a file_key from upload_file. Single place, no file: pass only address (e.g. {"address": "India Gate, New Delhi"}). The reply carries latitude, longitude, address, pincode, city, district, state and landmark. status=not_found means no match; tell the user rather than answering yourself. Column selection: if you know it, pass address_column (or address_columns for several). Otherwise the server asks the geo-match service to detect it. When the answer is not unambiguous — several address columns, a weak match, or only structured columns like District/State/PIN that must be combined — the response is status=clarification_required with candidates and ready-to-fire guidance actions. Present the choice to the user and re-call with their answer; never invent a column name. The result overwrites the same file_key as a new version, plus a small preview, not the full rows. Pass that file_key to question_to_map to map the coordinates, or hand the user file_url (a signed download link, when present) to fetch the file directly.
| Parameter | Type | Description |
|---|---|---|
| sheet | string | |
| job_id | string | |
| address | string | |
| file_key | string | |
| force_new | boolean | |
| address_column | string | |
| address_columns | ["null","array"] | |
| compose_columns | ["null","array"] |
Return the server's capability matrix: supported map types, geo types, output formats, classification methods, and the list of tools available in this process (which varies by configuration). Call this first to discover what the server can do.
No parameters.
{
"name": "get_capabilities",
"description": "Return the server's capability matrix: supported map types, geo types, output formats, classification methods, and the list of tools available in this process (which varies by configuration). Call this first to discover what the server can do.",
"inputSchema": {
"type": "object",
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"map_types",
"geo_levels",
"output_formats",
"default_output",
"classification_methods",
"available_indices",
"index_modes",
"geo_detection",
"auto_level_detection",
"svg_default",
"png_supported",
"stateless_only",
"available_tools",
"map_features"
],
"properties": {
"guidance": {
"type": [
"null",
"object"
],
"required": [
"next_actions",
"allow_freeform",
"next_steps_text"
],
"properties": {
"next_actions": {
"type": [
"null",
"array"
],
"items": {
"type": "object",
"required": [
"id",
"label",
"tool"
],
"properties": {
"id": {
"type": "string"
},
"tool": {
"type": "string"
},
"label": {
"type": "string"
},
"reason": {
"type": "string"
},
"arguments": {
"type": "object",
"additionalProperties": true
},
"arguments_from": {
"type": "string"
}
},
"additionalProperties": false
}
},
"allow_freeform": {
"type": "boolean"
},
"next_steps_text": {
"type": "string"
}
},
"additionalProperties": false
},
"map_types": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"geo_levels": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"index_modes": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"svg_default": {
"type": "boolean"
},
"map_features": {
"type": [
"null",
"array"
],
"items": {
"type": "object",
"required": [
"feature",
"how"
],
"properties": {
"how": {
"type": "string"
},
"feature": {
"type": "string"
}
},
"additionalProperties": false
}
},
"geo_detection": {
"type": "boolean"
},
"png_supported": {
"type": "boolean"
},
"default_output": {
"type": "string"
},
"output_formats": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"stateless_only": {
"type": "boolean"
},
"available_tools": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"available_indices": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"auto_level_detection": {
"type": "boolean"
},
"classification_methods": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
}Look up Indian pincodes: city, district and state. One pincode, no file: {"pincode": "560019"} also returns the post offices it covers with their coordinates. status=not_found means the pincode does not exist; tell the user rather than answering yourself. A file (including a local CSV the user names): upload it with upload_file first, then pass file_key (and pincode_column if you know it). Do not look the rows up one by one or write the result file yourself — this tool writes it. Every row gains city, district, state and pincode_status columns; the file is written back over file_key as a new version and file_url is a download link. Show the user the preview and offer the link. Each unique pincode costs one lookup. A clarification_required reply asks which column holds the pincodes. Large files return status=accepted with a job_id: poll {"job_id": "..."} until completed.
| Parameter | Type | Description |
|---|---|---|
| sheet | string | |
| job_id | string | |
| pincode | any | one 6-digit Indian pincode, e.g. "560019" (a number is accepted too) |
| file_key | string | |
| force_new | boolean | |
| pincode_column | string |
{
"name": "pincode_lookup",
"description": "Look up Indian pincodes: city, district and state.\n\nOne pincode, no file: {\"pincode\": \"560019\"} also returns the post offices it covers with their coordinates. status=not_found means the pincode does not exist; tell the user rather than answering yourself.\n\nA file (including a local CSV the user names): upload it with upload_file first, then pass file_key (and pincode_column if you know it). Do not look the rows up one by one or write the result file yourself — this tool writes it. Every row gains city, district, state and pincode_status columns; the file is written back over file_key as a new version and file_url is a download link. Show the user the preview and offer the link. Each unique pincode costs one lookup. A clarification_required reply asks which column holds the pincodes. Large files return status=accepted with a job_id: poll {\"job_id\": \"...\"} until completed.",
"inputSchema": {
"type": "object",
"properties": {
"sheet": {
"type": "string"
},
"job_id": {
"type": "string"
},
"pincode": {
"description": "one 6-digit Indian pincode, e.g. \"560019\" (a number is accepted too)"
},
"file_key": {
"type": "string"
},
"force_new": {
"type": "boolean"
},
"pincode_column": {
"type": "string"
}
},
"additionalProperties": false
}
}Render a geographic map from your data. Call upload_file first to ingest a CSV/XLSX file, then pass the returned file_key: {"question": "show total by pincode", "file_key": "mcp-uploads/<user-id>/2026/01/15/<uuid>.csv"}. The file_key is reusable — for additional questions on the same file, pass the same file_key again without re-uploading. Alternatively, pass rows directly as 'data' (e.g. from the upload_file preview): {"question": "show total by pincode", "data": [<rows>]} geo_column and value_column are preferred if easily identifiable from the column names, but not required — the server auto-detects them using a geo-match service that matches your data against known Indian geographies (states, districts, ACs, PCs, pincodes, RTOs, cities). Hints: geo_column usually contains place names (state, district, city, pincode, constituency) or numeric codes (pincode=560049); value_column usually contains the metric to plot (sales, count, total, percentage) or a category (party affiliation, status, type). If value_column is 'total' and doesn't exist in data, all numeric columns are summed automatically. String value columns render as categorical maps (each distinct value gets its own color, e.g. party affiliation). If the server cannot determine which columns to use, it returns a 'clarification_required' response with suggested columns and guidance — pick a geo_column and value_column from the suggestions and re-call. Supported geo types: state, district, pincode, rto, city, ac, pc. Points mode: if your file has latitude/longitude columns (e.g. from a prior geocoding step, or coordinates you already had) and your question asks to plot/pin/mark locations ("plot my stores", "show me the outlet locations", "mark these points"), the server detects the coordinate columns automatically and renders markers instead of shaded regions — no geo_column/value_column needed. The boundary lines drawn beneath the markers and how far the map zooms are chosen automatically from where the points actually fall (tightens to a state or district for a local cluster, falls back to all-India for a nationwide spread); you can also name a level explicitly ("plot by assembly constituency", "rto wise") to force it. A response may report points that fall outside every boundary (e.g. offshore or swapped lat/lon) — check for that in the warnings.
| Parameter | Type | Description |
|---|---|---|
| data | ["null","array"] | |
| sheet | string |
Turn latitude/longitude coordinates in an uploaded CSV or XLSX into addresses. Pass a file_key from upload_file. Single point, no file: pass only latitude and longitude in decimal degrees (e.g. {"latitude": 28.6129, "longitude": 77.2295}). The reply carries address, pincode, city, district, state and landmark. status=not_found means no match; tell the user rather than answering yourself. Column selection: pass latitude_column and longitude_column, or latlong_column for a single combined column, or coordinate_pairs for several sets. Otherwise the server detects them. When the answer is not unambiguous — several coordinate columns, a weak match, coordinates outside the supported region, or coarse whole-number values — the response is status=clarification_required. Present the choice to the user and re-call with their answer. Results are written back into the uploaded file: the response carries file_key, a signed file_url, and a small preview. Each pair adds address, pincode, landmark and status columns.
| Parameter | Type | Description |
|---|---|---|
| sheet | string | |
| job_id | string | |
| file_key | string | |
| latitude | any | one point's latitude in decimal degrees, e.g. 28.6129 (a string is accepted too) |
| force_new | boolean | |
| longitude | any | one point's longitude in decimal degrees, e.g. 77.2295 (a string is accepted too) |
| latlong_column | string | |
| latitude_column | string |
Run the territory-management pipeline on a branch file uploaded via upload_file. Hybrid async with three modes: pass file_key to START a job (returns a job_id immediately); pass only job_id on subsequent calls to POLL progress; pass job_id AND catchment_type together to RESUME a job that paused for clarification. The pipeline validates that all branches are in one state, computes each branch's isochrone at catchment_distance_km, finds villages (catchment_type='village') or pincodes (catchment_type='pincode') that overlap the isochrone by ≥50%. A village/pincode inside several catchments is kept under EVERY branch (never deduplicated), and the last column closest_branch names the nearest branch by driving distance for those shared units (blank otherwise). Each catchment is split into 5 wedges of 72° (group_number 1-5); each wedge is split into bunches of 1-5 neighbouring units (bunch_number 1..N); each bunch is sequenced via the Trips API (trip_number 1-5); s_no numbers each branch's rows 1..N in that order. Returns a signed URL to an XLSX (download_url) with a Territory sheet of rows and a Maps sheet, and maps: one SVG per branch (map_url) with the branch at the centre, its units shaded by group_number and labelled by s_no, overlaps hatched green (this branch is closest) or red (another branch is closer); render_map=false skips the maps. Optional at start: style_request (the user's words for the map colours, e.g. 'groups in pink shades'; only the 5 group colours and the near/far hatch colours change, applied exactly as asked, pincode maps only) and map_title (replaces the map title). If requested colours make the hatching hard to see, warnings carry a suggestion to pass on to the user. catchment_type is OPTIONAL at start: if omitted, the geo-match service detects the branch file's place columns (a pincode column means pincode, a village column means village), and a catchment_type / area_type / mapping_type column also counts (must be uniform across rows). If the file is unclear (several such columns) or neither the caller nor the file specifies it — or they disagree — the job pauses in phase=awaiting_catchment_type and the poll response carries clarification_needed=true with a clarification_message instead of an error; answer by calling again with that same job_id plus the chosen catchment_type to resume. A file with mixed village/pincode values in its own column fails outright with AMBIGUOUS_CATCHMENT_TYPE. While a job runs, each response carries poll_after_seconds=10: wait 10 seconds, then poll again. Expect phase transitions: validating → isochroning → overlapping → grouping → bunching → routing → distancing → rendering_map → writing_output → complete (or awaiting_catchment_type, from which a resume call re-enters at validating). Flow: upload_file → upload bytes → territory_mapping{file_key,…} → territory_mapping{job_id} until phase=complete or phase=awaiting_catchment_type → if awaiting, territory_mapping{job_id, catchment_type} to resume → territory_mapping{job_id} until phase=complete.
Upload a CSV or XLSX file for server-side ingestion under policy (auth, size cap, malware scan, injected-intent scan) and receive a file_key. This is the first step for ANY tool that works on the user's file: question_to_map, geocode, reverse_geocode, pincode_lookup and compute_column all take the returned file_key. When the user names a local CSV/XLSX and wants results added to it (pincodes, cities, coordinates, a computed column), upload it here rather than reading it yourself. Step 1: Call upload_file with file_name, file_size, and question. The response contains a signed upload_url and a curl command — run the curl command to POST the file bytes. The curl response contains file_key, columns, a row preview, and optionally 'intent' (geo-match service detected geo_column, geo_level, value_column, map_type, confidence) and 'guidance' (a ready-to-fire question_to_map action with all detected parameters pre-filled). Forward the intent fields into question_to_map to skip auto-detection and render immediately. For multi-sheet XLSX: the curl response is 'sheet_selection_required' with a file_key and sheets list. Pass file_key and sheet to question_to_map (or any other tool that accepts file_key) — do not call upload_file again. After upload, pass the returned file_key to question_to_map to render a map from the full dataset. The file_key is reusable — for additional questions on the same file, pass the same file_key again without re-uploading. When the upload response includes 'guidance', use its next_actions directly for a zero-round-trip render.
| Parameter | Type | Description |
|---|---|---|
| sheet | string | |
| file_key | string | |
| question | string | |
| file_name * | string | |
| file_size * | integer |
LatLong Maps MCP Server — Usage Guide ## Authentication All tool calls require a valid token. For HTTP transport, send the "X-Authorization-Token" header. For stdio transport, set the "X_AUTHORIZATION_TOKEN" environment variable in your MCP client config. ## SVG artifacts Map tools return a version-pinned signed "svg_url" and "svg_expires_at"; the default TTL is about 8 hours and is configurable by the server. Do not expect raw SVG markup in tool JSON. To display the map to the user: 1. ALWAYS render the svg_url as a clickable image using markdown:  2. The URL is a direct link to an SVG file — it renders in any browser or image viewer. 3. Include the image inline in your response so the user sees the map immediately. 4. Copy svg_url EXACTLY, character for character, including EVERY query parameter (versionId, Expires, Key-Pair-Id, Signature). Never shorten, clean up, re-encode or drop any part of it. The signature covers the whole URL: removing or changing even one parameter makes the link return "AccessDenied". Example response format:  For saving locally: fetch the URL without altering its query string: "curl --fail --location --output map.svg <svg_url>" ## Download links (file_url) geocode, reverse_geocode, pincode_lookup and compute_column return file_url, a signed link to the result CSV/XLSX. The same rule applies as for svg_url: copy file_url EXACTLY, including EVERY query parameter (versionId, Expires, Key-Pair-Id, Signature), e.g. [Download the CSV](file_url). A link cut at ".csv" or ".xlsx" returns "AccessDenied". When the user asked for a file, always give them file_url. ## Chaining Policy - When a result carries a "guidance" object, prefer its numbered menu and its next_actions over improvising a follow-up. - An action with "arguments_from" names an object already in the exchange. Use that object as the base request and overlay the small "arguments" map on top. "render_map_input" means the field of that name in the result you just received; "previous_call_input" means the arguments you just sent. Never rebuild a data table by hand. - An action with a label but no arguments is an invitation, not a complete call: you still have to supply the missing choice. - If you do not understand an action, ignore the whole guidance object rather than acting on part of it. - Do not invent tools, output formats, or capabilities. get_capabilities reports which tools are actually available in this process — treat its available_tools list as authoritative over anything below. ## Tools ### 1. get_capabilities Returns the server's capability matrix: supported map types (choropleth, categorical), output formats (SVG is the default; PNG and both are opt-in), classification methods, feature flags, and available_tools — the tools actually registered in this process. Call this first to discover what the server can do. ## Recommended Workflows ### Upload-then-map workflow 1. Call upload_file with file_name, file_size, and question to get a signed upload URL. 2. Run the curl command from the response to upload the file bytes. 3. Read the curl response for file_key, columns, and row preview. 4. If the response is 'sheet_selection_required' (multi-sheet XLSX), note the returned file_key and sheet names. Pass file_key + sheet directly to question_to_map (or any other tool that accepts file_key) — do not call upload_file again. 5. Call question_to_map with the returned file_key and question: {"question": "...", "file_key": "mcp-uploads/<user-id>/2026/01/15/<uuid>.csv"} 6. For subsequent questions on the same file, reuse the same file_key — do not re-upload. The server re-fetches the file from S3 on each call. ## Data Format Pass data as an array of row objects (key-value maps). Each row must contain at least the geo_column and value_column fields. Example: {"data": [{"state": "Maharashtra", "population": 123456789}, {"state": "Karnataka", "population": 67562686}], "ma
Names, descriptions and schemas were written by the server and are shown as data.
Pattern matches on what the server declares. They show what it says it can do, not what it does.
None yet. Changes appear after a server's second daily check.
{
"name": "geocode",
"description": "Geocode addresses from an uploaded CSV or XLSX file into latitude/longitude. Pass a file_key from upload_file.\n\nSingle place, no file: pass only address (e.g. {\"address\": \"India Gate, New Delhi\"}). The reply carries latitude, longitude, address, pincode, city, district, state and landmark. status=not_found means no match; tell the user rather than answering yourself.\n\nColumn selection: if you know it, pass address_column (or address_columns for several). Otherwise the server asks the geo-match service to detect it. When the answer is not unambiguous — several address columns, a weak match, or only structured columns like District/State/PIN that must be combined — the response is status=clarification_required with candidates and ready-to-fire guidance actions. Present the choice to the user and re-call with their answer; never invent a column name.\n\nThe result overwrites the same file_key as a new version, plus a small preview, not the full rows. Pass that file_key to question_to_map to map the coordinates, or hand the user file_url (a signed download link, when present) to fetch the file directly.",
"inputSchema": {
"type": "object",
"properties": {
"sheet": {
"type": "string"
},
"job_id": {
"type": "string"
},
"address": {
"type": "string"
},
"file_key": {
"type": "string"
},
"force_new": {
"type": "boolean"
},
"address_column": {
"type": "string"
},
"address_columns": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"compose_columns": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
}| style | object |
| table | string |
| title | string |
| file_key | string |
| map_type | string |
| question * | string |
| subtitle | string |
| geo_level | string |
| geo_column | string |
| state_hint | ["null","array"] |
| enrich_with | ["null","object"] |
| detected_geo | ["null","object"] |
| legend_title | string |
| value_column | string |
| output_format | string |
| render_params | object |
{
"name": "question_to_map",
"description": "Render a geographic map from your data. Call upload_file first to ingest a CSV/XLSX file, then pass the returned file_key: {\"question\": \"show total by pincode\", \"file_key\": \"mcp-uploads/<user-id>/2026/01/15/<uuid>.csv\"}. The file_key is reusable — for additional questions on the same file, pass the same file_key again without re-uploading.\n\nAlternatively, pass rows directly as 'data' (e.g. from the upload_file preview): {\"question\": \"show total by pincode\", \"data\": [<rows>]}\n\ngeo_column and value_column are preferred if easily identifiable from the column names, but not required — the server auto-detects them using a geo-match service that matches your data against known Indian geographies (states, districts, ACs, PCs, pincodes, RTOs, cities).\nHints: geo_column usually contains place names (state, district, city, pincode, constituency) or numeric codes (pincode=560049); value_column usually contains the metric to plot (sales, count, total, percentage) or a category (party affiliation, status, type).\nIf value_column is 'total' and doesn't exist in data, all numeric columns are summed automatically. String value columns render as categorical maps (each distinct value gets its own color, e.g. party affiliation). If the server cannot determine which columns to use, it returns a 'clarification_required' response with suggested columns and guidance — pick a geo_column and value_column from the suggestions and re-call.\nSupported geo types: state, district, pincode, rto, city, ac, pc.\n\nPoints mode: if your file has latitude/longitude columns (e.g. from a prior geocoding step, or coordinates you already had) and your question asks to plot/pin/mark locations (\"plot my stores\", \"show me the outlet locations\", \"mark these points\"), the server detects the coordinate columns automatically and renders markers instead of shaded regions — no geo_column/value_column needed. The boundary lines drawn beneath the markers and how far the map zooms are chosen automatically from where the points actually fall (tightens to a state or district for a local cluster, falls back to all-India for a nationwide spread); you can also name a level explicitly (\"plot by assembly constituency\", \"rto wise\") to force it. A response may report points that fall outside every boundary (e.g. offshore or swapped lat/lon) — check for that in the warnings.",
"inputSchema": {
"type": "object",
"required": [
"question"
],
"properties": {
"data": {
"type": [
"null",
"array"
],
"items": {
"type": "object",
"additionalProperties": true
}
},
"sheet": {
"type": "string"
},
"style": {
"type": "object",
"additionalProperties": true
},
"table": {
"type": "string"
},
"title": {
"type": "string"
},
"file_key": {
"type": "string"
},
"map_type": {
"type": "string"
},
"question": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"geo_level": {
"type": "string"
},
"geo_column": {
"type": "string"
},
"state_hint": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"enrich_with": {
"type": [
"null",
"object"
],
"required": [
"table",
"columns"
],
"properties": {
"table": {
"type": "string"
},
"columns": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"join_on": {
"type": "string"
}
},
"additionalProperties": false
},
"detected_geo": {
"type": [
"null",
"object"
],
"required": [
"column",
"geo_type",
"confidence",
"matched_count",
"total_count"
],
"properties": {
"column": {
"type": "string"
},
"parent": {
"type": "string"
},
"geo_type": {
"type": "string"
},
"confidence": {
"type": "number"
},
"total_count": {
"type": "integer"
},
"matched_count": {
"type": "integer"
}
},
"additionalProperties": false
},
"legend_title": {
"type": "string"
},
"value_column": {
"type": "string"
},
"output_format": {
"type": "string"
},
"render_params": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"mode"
],
"properties": {
"map": {
"type": [
"null",
"object"
],
"required": [
"url",
"format",
"render_id"
],
"properties": {
"url": {
"type": "string"
},
"title": {
"type": "string"
},
"format": {
"type": "string"
},
"svg_url": {
"type": "string"
},
"html_url": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"geo_scope": {
"type": "string"
},
"mime_type": {
"type": "string"
},
"render_id": {
"type": "string"
},
"dimensions": {
"type": [
"null",
"object"
],
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "integer"
},
"height": {
"type": "integer"
}
},
"additionalProperties": false
},
"expires_at": {
"type": "string"
},
"total_count": {
"type": "integer"
},
"total_value": {
"type": "string"
},
"value_label": {
"type": "string"
},
"active_count": {
"type": "integer"
},
"join_summary": {
"type": [
"null",
"object"
],
"required": [
"matched",
"unmatched",
"total"
],
"properties": {
"total": {
"type": "integer"
},
"matched": {
"type": "integer"
},
"unmatched": {
"type": "integer"
}
},
"additionalProperties": false
},
"preview_image_base64": {
"type": "string"
}
},
"additionalProperties": false
},
"mode": {
"type": "string"
},
"usage": {
"type": [
"null",
"object"
],
"required": [
"this_call",
"breakdown",
"month_used",
"month_limit",
"month_remaining"
],
"properties": {
"breakdown": {
"type": "object",
"additionalProperties": {
"type": "integer"
}
},
"this_call": {
"type": "integer"
},
"month_used": {
"type": "integer"
},
"month_limit": {
"type": "integer"
},
"month_remaining": {
"type": "integer"
}
},
"additionalProperties": false
},
"guidance": {
"type": [
"null",
"object"
],
"required": [
"next_actions",
"allow_freeform",
"next_steps_text"
],
"properties": {
"next_actions": {
"type": [
"null",
"array"
],
"items": {
"type": "object",
"required": [
"id",
"label",
"tool"
],
"properties": {
"id": {
"type": "string"
},
"tool": {
"type": "string"
},
"label": {
"type": "string"
},
"reason": {
"type": "string"
},
"arguments": {
"type": "object",
"additionalProperties": true
},
"arguments_from": {
"type": "string"
}
},
"additionalProperties": false
}
},
"allow_freeform": {
"type": "boolean"
},
"next_steps_text": {
"type": "string"
}
},
"additionalProperties": false
},
"warnings": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"confidence": {
"type": "number"
},
"clarification": {
"type": [
"null",
"object"
],
"required": [
"status",
"message",
"columns",
"suggested_geo_columns",
"suggested_value_columns"
],
"properties": {
"status": {
"type": "string"
},
"columns": {
"type": [
"null",
"array"
],
"items": {
"type": "object",
"required": [
"name",
"type",
"class"
],
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"class": {
"type": "string"
}
},
"additionalProperties": false
}
},
"message": {
"type": "string"
},
"guidance": {
"type": [
"null",
"object"
],
"required": [
"next_actions",
"allow_freeform",
"next_steps_text"
],
"properties": {
"next_actions": {
"type": [
"null",
"array"
],
"items": {
"type": "object",
"required": [
"id",
"label",
"tool"
],
"properties": {
"id": {
"type": "string"
},
"tool": {
"type": "string"
},
"label": {
"type": "string"
},
"reason": {
"type": "string"
},
"arguments": {
"type": "object",
"additionalProperties": true
},
"arguments_from": {
"type": "string"
}
},
"additionalProperties": false
}
},
"allow_freeform": {
"type": "boolean"
},
"next_steps_text": {
"type": "string"
}
},
"additionalProperties": false
},
"suggested_geo_columns": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"suggested_value_columns": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"computed_data": {
"type": [
"null",
"object"
],
"required": [
"columns",
"rows",
"total_rows",
"returned_rows"
],
"properties": {
"rows": {
"type": [
"null",
"array"
],
"items": {
"type": "object",
"additionalProperties": true
}
},
"columns": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"sort_order": {
"type": "string"
},
"total_rows": {
"type": "integer"
},
"sort_column": {
"type": "string"
},
"returned_rows": {
"type": "integer"
}
},
"additionalProperties": false
},
"rejected_rows": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"points_plotted": {
"type": "integer"
},
"points_rejected": {
"type": "integer"
},
"resolved_params": {
"type": [
"null",
"object"
],
"required": [
"map_type",
"geo_type",
"geo_column",
"value_column"
],
"properties": {
"style": {
"type": "object",
"additionalProperties": true
},
"geo_type": {
"type": "string"
},
"map_type": {
"type": "string"
},
"geo_column": {
"type": "string"
},
"state_hint": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"value_column": {
"type": "string"
}
},
"additionalProperties": false
},
"level_resolution": {
"type": [
"null",
"object"
],
"required": [
"datasets",
"resolved_level",
"method"
],
"properties": {
"method": {
"type": "string"
},
"reason": {
"type": "string"
},
"datasets": {
"type": [
"null",
"array"
],
"items": {
"type": "object",
"required": [
"source",
"level",
"geo_col",
"rows"
],
"properties": {
"rows": {
"type": "integer"
},
"level": {
"type": "string"
},
"source": {
"type": "string"
},
"geo_col": {
"type": "string"
}
},
"additionalProperties": false
}
},
"aggregations": {
"type": [
"null",
"array"
],
"items": {
"type": "object",
"required": [
"dataset",
"from_level",
"to_level",
"method",
"columns"
],
"properties": {
"method": {
"type": "string"
},
"columns": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"dataset": {
"type": "string"
},
"to_level": {
"type": "string"
},
"from_level": {
"type": "string"
}
},
"additionalProperties": false
}
},
"alternatives": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"resolved_level": {
"type": "string"
}
},
"additionalProperties": false
},
"resolution_method": {
"type": "string"
},
"aggregation_applied": {
"type": [
"null",
"object"
],
"required": [
"original_rows",
"aggregated_rows",
"method",
"note"
],
"properties": {
"note": {
"type": "string"
},
"method": {
"type": "string"
},
"grouped_by": {
"type": "string"
},
"original_rows": {
"type": "integer"
},
"aggregated_rows": {
"type": "integer"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
}| coordinate_pairs | ["null","array"] |
| longitude_column | string |
| accept_low_precision | boolean |
{
"name": "reverse_geocode",
"description": "Turn latitude/longitude coordinates in an uploaded CSV or XLSX into addresses. Pass a file_key from upload_file.\n\nSingle point, no file: pass only latitude and longitude in decimal degrees (e.g. {\"latitude\": 28.6129, \"longitude\": 77.2295}). The reply carries address, pincode, city, district, state and landmark. status=not_found means no match; tell the user rather than answering yourself.\n\nColumn selection: pass latitude_column and longitude_column, or latlong_column for a single combined column, or coordinate_pairs for several sets. Otherwise the server detects them. When the answer is not unambiguous — several coordinate columns, a weak match, coordinates outside the supported region, or coarse whole-number values — the response is status=clarification_required. Present the choice to the user and re-call with their answer.\n\nResults are written back into the uploaded file: the response carries file_key, a signed file_url, and a small preview. Each pair adds address, pincode, landmark and status columns.",
"inputSchema": {
"type": "object",
"properties": {
"sheet": {
"type": "string"
},
"job_id": {
"type": "string"
},
"file_key": {
"type": "string"
},
"latitude": {
"description": "one point's latitude in decimal degrees, e.g. 28.6129 (a string is accepted too)"
},
"force_new": {
"type": "boolean"
},
"longitude": {
"description": "one point's longitude in decimal degrees, e.g. 77.2295 (a string is accepted too)"
},
"latlong_column": {
"type": "string"
},
"latitude_column": {
"type": "string"
},
"coordinate_pairs": {
"type": [
"null",
"array"
],
"items": {
"type": "object",
"properties": {
"latlong_column": {
"type": "string"
},
"latitude_column": {
"type": "string"
},
"longitude_column": {
"type": "string"
}
},
"additionalProperties": false
}
},
"longitude_column": {
"type": "string"
},
"accept_low_precision": {
"type": "boolean"
}
},
"additionalProperties": false
}
}| Parameter | Type | Description |
|---|---|---|
| job_id | string | |
| file_key | string | |
| map_title | string | |
| render_map | ["null","boolean"] | |
| style_request | string | |
| catchment_type | string | |
| catchment_distance_km | number |
{
"name": "territory_mapping",
"description": "Run the territory-management pipeline on a branch file uploaded via upload_file. Hybrid async with three modes: pass file_key to START a job (returns a job_id immediately); pass only job_id on subsequent calls to POLL progress; pass job_id AND catchment_type together to RESUME a job that paused for clarification. The pipeline validates that all branches are in one state, computes each branch's isochrone at catchment_distance_km, finds villages (catchment_type='village') or pincodes (catchment_type='pincode') that overlap the isochrone by ≥50%. A village/pincode inside several catchments is kept under EVERY branch (never deduplicated), and the last column closest_branch names the nearest branch by driving distance for those shared units (blank otherwise). Each catchment is split into 5 wedges of 72° (group_number 1-5); each wedge is split into bunches of 1-5 neighbouring units (bunch_number 1..N); each bunch is sequenced via the Trips API (trip_number 1-5); s_no numbers each branch's rows 1..N in that order. Returns a signed URL to an XLSX (download_url) with a Territory sheet of rows and a Maps sheet, and maps: one SVG per branch (map_url) with the branch at the centre, its units shaded by group_number and labelled by s_no, overlaps hatched green (this branch is closest) or red (another branch is closer); render_map=false skips the maps. Optional at start: style_request (the user's words for the map colours, e.g. 'groups in pink shades'; only the 5 group colours and the near/far hatch colours change, applied exactly as asked, pincode maps only) and map_title (replaces the map title). If requested colours make the hatching hard to see, warnings carry a suggestion to pass on to the user. catchment_type is OPTIONAL at start: if omitted, the geo-match service detects the branch file's place columns (a pincode column means pincode, a village column means village), and a catchment_type / area_type / mapping_type column also counts (must be uniform across rows). If the file is unclear (several such columns) or neither the caller nor the file specifies it — or they disagree — the job pauses in phase=awaiting_catchment_type and the poll response carries clarification_needed=true with a clarification_message instead of an error; answer by calling again with that same job_id plus the chosen catchment_type to resume. A file with mixed village/pincode values in its own column fails outright with AMBIGUOUS_CATCHMENT_TYPE. While a job runs, each response carries poll_after_seconds=10: wait 10 seconds, then poll again. Expect phase transitions: validating → isochroning → overlapping → grouping → bunching → routing → distancing → rendering_map → writing_output → complete (or awaiting_catchment_type, from which a resume call re-enters at validating). Flow: upload_file → upload bytes → territory_mapping{file_key,…} → territory_mapping{job_id} until phase=complete or phase=awaiting_catchment_type → if awaiting, territory_mapping{job_id, catchment_type} to resume → territory_mapping{job_id} until phase=complete.",
"inputSchema": {
"type": "object",
"properties": {
"job_id": {
"type": "string"
},
"file_key": {
"type": "string"
},
"map_title": {
"type": "string"
},
"render_map": {
"type": [
"null",
"boolean"
]
},
"style_request": {
"type": "string"
},
"catchment_type": {
"type": "string"
},
"catchment_distance_km": {
"type": "number"
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"required": [
"job_id",
"phase",
"percent"
],
"properties": {
"maps": {
"type": [
"null",
"array"
],
"items": {
"type": "object",
"required": [
"branch_id",
"map_url"
],
"properties": {
"map_url": {
"type": "string"
},
"district": {
"type": "string"
},
"branch_id": {
"type": "string"
},
"branch_name": {
"type": "string"
}
},
"additionalProperties": false
}
},
"phase": {
"type": "string"
},
"state": {
"type": "string"
},
"job_id": {
"type": "string"
},
"percent": {
"type": "integer"
},
"guidance": {
"type": [
"null",
"object"
],
"required": [
"next_actions",
"allow_freeform",
"next_steps_text"
],
"properties": {
"next_actions": {
"type": [
"null",
"array"
],
"items": {
"type": "object",
"required": [
"id",
"label",
"tool"
],
"properties": {
"id": {
"type": "string"
},
"tool": {
"type": "string"
},
"label": {
"type": "string"
},
"reason": {
"type": "string"
},
"arguments": {
"type": "object",
"additionalProperties": true
},
"arguments_from": {
"type": "string"
}
},
"additionalProperties": false
}
},
"allow_freeform": {
"type": "boolean"
},
"next_steps_text": {
"type": "string"
}
},
"additionalProperties": false
},
"warnings": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
},
"error_code": {
"type": "string"
},
"download_url": {
"type": "string"
},
"error_message": {
"type": "string"
},
"total_branches": {
"type": "integer"
},
"poll_after_seconds": {
"type": "integer"
},
"processed_branches": {
"type": "integer"
},
"clarification_needed": {
"type": "boolean"
},
"clarification_message": {
"type": "string"
}
},
"additionalProperties": false
}
}{
"name": "upload_file",
"description": "Upload a CSV or XLSX file for server-side ingestion under policy (auth, size cap, malware scan, injected-intent scan) and receive a file_key. This is the first step for ANY tool that works on the user's file: question_to_map, geocode, reverse_geocode, pincode_lookup and compute_column all take the returned file_key. When the user names a local CSV/XLSX and wants results added to it (pincodes, cities, coordinates, a computed column), upload it here rather than reading it yourself.\n\nStep 1: Call upload_file with file_name, file_size, and question. The response contains a signed upload_url and a curl command — run the curl command to POST the file bytes. The curl response contains file_key, columns, a row preview, and optionally 'intent' (geo-match service detected geo_column, geo_level, value_column, map_type, confidence) and 'guidance' (a ready-to-fire question_to_map action with all detected parameters pre-filled). Forward the intent fields into question_to_map to skip auto-detection and render immediately.\n\nFor multi-sheet XLSX: the curl response is 'sheet_selection_required' with a file_key and sheets list. Pass file_key and sheet to question_to_map (or any other tool that accepts file_key) — do not call upload_file again.\n\nAfter upload, pass the returned file_key to question_to_map to render a map from the full dataset. The file_key is reusable — for additional questions on the same file, pass the same file_key again without re-uploading. When the upload response includes 'guidance', use its next_actions directly for a zero-round-trip render.",
"inputSchema": {
"type": "object",
"required": [
"file_name",
"file_size"
],
"properties": {
"sheet": {
"type": "string"
},
"file_key": {
"type": "string"
},
"question": {
"type": "string"
},
"file_name": {
"type": "string"
},
"file_size": {
"type": "integer"
}
},
"additionalProperties": false
}
}