GIS Cloud

Delete a bookmark by ID. Irreversible. Confirmation handshake: a destructive call without `confirmed` makes NO change — it returns a plain-language `summary` (5-minute TTL). Show the summary and STOP: approval must be a NEW user message sent after seeing it (the triggering request is NOT approval). Only then repeat the call with identical arguments plus `confirmed: true` to execute.

delete_bookmark

Delete a feature from a layer. Confirmation handshake: a destructive call without `confirmed` makes NO change — it returns a plain-language `summary` (5-minute TTL). Show the summary and STOP: approval must be a NEW user message sent after seeing it (the triggering request is NOT approval). Only then repeat the call with identical arguments plus `confirmed: true` to execute.

delete_feature

Delete a file from user storage, or remove an EMPTY directory. Removing a directory is non-recursive — a non-empty directory is refused (delete its contents first); this never mass-deletes a folder's files. Irreversible. Confirmation handshake: a destructive call without `confirmed` makes NO change — it returns a plain-language `summary` (5-minute TTL). Show the summary and STOP: approval must be a NEW user message sent after seeing it (the triggering request is NOT approval). Only then repeat the call with identical arguments plus `confirmed: true` to execute.

delete_file

Delete a form by ID. Irreversible. Does NOT automatically unbind it from layers — call update_layer with `form: null` on bound layers first if you want the binding cleared too. Confirmation handshake: a destructive call without `confirmed` makes NO change — it returns a plain-language `summary` (5-minute TTL). Show the summary and STOP: approval must be a NEW user message sent after seeing it (the triggering request is NOT approval). Only then repeat the call with identical arguments plus `confirmed: true` to execute.

delete_form

Delete a layer from a map. Confirmation handshake: a destructive call without `confirmed` makes NO change — it returns a plain-language `summary` (5-minute TTL). Show the summary and STOP: approval must be a NEW user message sent after seeing it (the triggering request is NOT approval). Only then repeat the call with identical arguments plus `confirmed: true` to execute.

delete_layer

Delete a map by ID. Confirmation handshake: a destructive call without `confirmed` makes NO change — it returns a plain-language `summary` (5-minute TTL). Show the summary and STOP: approval must be a NEW user message sent after seeing it (the triggering request is NOT approval). Only then repeat the call with identical arguments plus `confirmed: true` to execute.

delete_map

Delete a table and all its rows. Irreversible. cascade=true drops dependent DB views along with the table — but NOT map layers: a vector layer whose source is this table (source.type=pg) is left orphaned, not removed or warned about. Remove such layers separately with delete_layer. The delete succeeds (204) even while map layers still reference the table; cascade is a Postgres DROP … CASCADE that reaches DB views only, never gc_layer rows. The orphaned layer stays registered on its map with its source/query still pointing at the now-deleted table, so its feature reads fail. Find dependents with list_layers and drop them with delete_layer. Note: a failed delete on a table that appears orphaned may surface only as a generic "FATAL" error; the actionable detail is in the server-side log. Confirmation handshake: a destructive call without `confirmed` makes NO change — it returns a plain-language `summary` (5-minute TTL). Show the summary and STOP: approval must be a NEW user message sent after seeing it (the triggering request is NOT approval). Only then repeat the call with identical arguments plus `confirmed: true` to execute.

delete_table

Delete a single row from a table by its row ID. Confirmation handshake: a destructive call without `confirmed` makes NO change — it returns a plain-language `summary` (5-minute TTL). Show the summary and STOP: approval must be a NEW user message sent after seeing it (the triggering request is NOT approval). Only then repeat the call with identical arguments plus `confirmed: true` to execute.

delete_table_row

Compute a per-column statistic on a layer. `action` is REQUIRED and selects what to compute. Per-column actions ("distinct", "min", "max", "minmax") need a `column`; "info" returns layer-wide column metadata and ignores `column`. For an average (or any other aggregate), use query_read with AVG()/SUM()/etc.

get_attribute_stats

Get a specific bookmark by ID, including its saved viewport (`state`). Read-back `state` is `{position:{lon,lat}, zoom, bearing, pitch}` with `position` in the map's projection (often Web Mercator metres) — this differs from the create_bookmark/update_bookmark input shape `{zoom, lat, lng}` in WGS84 degrees.

get_bookmark

Get the currently authenticated user profile.

get_current_user

Get details of a specific datasource.

get_datasource

Get a specific feature by ID.

get_feature

Get a single form by ID. The response includes `definition` (raw JSON string as stored) and a convenience `definition_decoded` object — read fields from the decoded object, never re-parse the string yourself.

get_form

Get detailed information about a specific layer. PG-backed layers include `query_table` (schema-qualified table name) — pass it verbatim as the `table` value in a query_read/query_write AST. The default expand is "columns,form,options", so a form-bound layer already carries its full form definition under `form` — ALWAYS inspect that form before writing features to the layer (see create_feature). The `form` map is keyed by layer id and includes `definition_decoded` with each field's type, `required` flag and option list. IS THIS LAYER FORM-BOUND? A real bound form's `form` object carries an `id` (and `mappings`); strict feature-write validation applies only then. A vector layer with NO bound form still returns a `form` object — a synthesized attribute form derived from its columns — but WITHOUT an `id`/`mappings`, and writes to it are validated only by DB column type, not by the form. So key the decision on `form.id`, not on whether `form` is present. Pass an explicit `expand` to override the default set.

get_layer

Get the column (attribute) definitions for a layer. Returns {"columns": [{"name", "type"}, ...]}. `type` uses this tool's own vocabulary (string/int/real/timestamp) and excludes the primary key — it differs from get_table (string=text, int|real=number, timestamp=datetime).

get_layer_columns

Get detailed information about a specific map by ID. Response includes an "editor_url" deep link. When reporting the map to the user, make the map's NAME a clickable markdown link to editor_url (e.g. `[City Parks](https://<editor>/map/20)`).

get_map

Get a single table by name, including its column definitions and geometry type. Pass `connection_id` to read a table on an external database connection (see list_dbconnections). `columns[].type` is text/number/datetime — "number" merges integer, decimal and the key (use `primary_key`); it maps to get_layer_columns as text=string, number=int|real, datetime=timestamp. A column made with the create_table "!<raw>" escape reports its native PG type instead ("boolean", or "unknown" for anything unrecognised), so the type vocabulary is not limited to text/number/datetime. KEY VISIBILITY: a non-spatial table's serial/declared key (e.g. "id") appears in `columns` as a "number"; a spatial table's auto key "ogc_fid" and its geometry column do NOT appear in `columns` (they are reported via `primary_key`/`geometry`), so there `columns` lists user attribute columns only.

get_table

Import a file from user storage into a PostgreSQL table. Tabular (.csv/.xls/.xlsx): point geometry from lat/lon columns via geometry_column_x/_y, or a WKT column via geometry_column + geometry_format=WKT; if_exists supports fail/rename/overwrite/append/replace. Spatial vector files (.shp/.geojson/.kml/.gpkg/…) import with their native geometry; if_exists fail/rename/overwrite only. The file must already exist in user storage (upload_file / upload_binary_file first; a .zip must be extracted with unzip_file before importing the dataset inside). A .shp needs its companion .dbf/.shx/(.prj) files alongside it in storage. Rasters (.tif, …) cannot be imported into a table — add them to a map with create_layer(type:"file") instead. For spatial vector files, importing is worthwhile when the data must be EDITABLE (file layers are read-only) or needs full PostGIS spatial SQL (file layers query through a limited SQLite dialect); to simply show the file on a map, add it directly with create_layer(type:"file") — no import needed. Tabular-only parameters (separator, geometry_column*, geometry_srs, create_datasource) are rejected for spatial files — they already carry geometry. For spatial files, epsg declares the source SRID and geometry_type forces the layer geometry (useful for mixed-geometry GeoJSON). After import, render the table on a map with create_layer (type point/line/polygon, source {"type":"pg","src":"<tablename>"}). TABULAR (.csv) TYPES: CSV columns import as TEXT — there is no type inference, so a numeric/date column lands as text. If you need it typed (for numeric filters/sorts or date math), cast it in query_read/query_write (e.g. col::numeric) or add a typed column and copy the cast values over. Runs synchronously — large files may take time. Confirmation handshake: a destructive call without `confirmed` makes NO change — it returns a plain-language `summary` (5-minute TTL). Show the summary and STOP: approval must be a NEW user message sent after seeing it (the triggering request is NOT approval). Only then repeat the call with identical arguments plus `confirmed: true` to execute.

import_file

List the basemaps ACTUALLY available on THIS account (OSM plus whatever the account has access to, e.g. Mapbox/HERE). Call this to answer "what/which basemaps do I have / are available" — the set is account-specific and is NOT the generic web list, so report ONLY the names it returns and NEVER answer from general knowledge or assume Google/Bing/Satellite etc. are present (they usually are not). Each item has a `name` (pass as a tile layer source in create_map/create_layer) and a human-readable `title`.

list_basemaps

List bookmarks (saved map views) for a map. Each bookmark has a `state` object capturing a viewport. NOTE the read-back shape differs from the write shape: stored state reads back as `{position:{lon,lat}, zoom, bearing, pitch}` with `position` in the MAP's projection (often Web Mercator metres), whereas create_bookmark/update_bookmark take `{zoom, lat, lng}` in WGS84 degrees — so a read-back state cannot be fed straight back into an update without reprojecting `position` to lon/lat.

list_bookmarks

List available datasources (databases, files, WMS/WFS services). PAGINATED: one page per call (default 100) — the envelope's `total` is the real count, so when it exceeds the number of rows you received you have only a PAGE; fetch the rest with `page`/`perpage` rather than assuming the list is complete or that no further datasources exist.

list_datasources

List the user's external database connections (e.g. an external PostgreSQL server such as AWS RDS). Use an entry's `id` as `connection_id` in list_tables / get_table, and as `connid` in a create_layer pg source. This is how you answer "list my external databases" and how you obtain a connection id to reach tables that are NOT in the user's own GIS Cloud schema. Each entry has an `id` and a `name`.

list_dbconnections

List features (rows) in a layer. Supports attribute/spatial filtering and pagination. Use this to read or filter rows from ONE layer. For anything that spans multiple layers, joins, aggregations (COUNT/SUM/GROUP BY), or richer PostGIS predicates, use query_read instead.

list_features

List or search files in user storage. To FIND files by name OR by extension/type, pass `search` — one recursive, case-insensitive substring sweep across ALL directories (an extension is a substring: search ".tif" finds every TIFF anywhere in storage) — do NOT walk directories one by one. Browse mode: pass `path` for one directory's direct contents, or omit it for the storage root. Results are PAGINATED — read `total` in the response envelope and fetch further pages with `page` (search defaults to 100 per page, browse to 1000). Each entry is {name, path, type:"file"|"directory", extension, size (bytes), modified (unix epoch), id, url}; size and modified are populated in BOTH modes (id and url are null for storage-backed listings). When the user was NOT specific about where to look, omit `path` — searching everywhere is the right default. When the user named a specific place, pass it as `path` (must be a directory): the search then checks just that directory's direct contents; set `recursive` to sweep its whole subtree (when the user asks for everything UNDER a folder). Passing a file path as `path` in browse mode returns that file's metadata (size, mtime, extension). Both modes return the same {type:"files", total, page, data:[...]} shape.

list_files

List Mobile Data Collection forms (owned by or shared with the caller). Match a user-given form name against BOTH `name` and `title` (case-insensitive) — the title is usually what the user means. Each item is lean: `id`, `name` (often a slug), human `title` (from the definition, may be null), `owner`, and `bound_layers` (layer ids the form is already attached to). Fetch a form's full fields/definition with get_form.

list_forms

List all layers in a map. PG-backed layers include a `query_table` field (schema-qualified table name, e.g. "usrsch3.parcels") — use this verbatim as the `table` value in query_read/query_write. By default the response is expanded with `columns` and `form`. The default expansion means any form-bound vector layer already carries its form definition inline under `form` (keyed by layer id) — pass an explicit `expand` to override the default set.

list_layers

List maps for the authenticated user, including Mobile Data Collection (MDC) projects — data collection projects are maps whose name starts with the "MDC:" prefix. By DEFAULT this returns only the user's own maps and maps shared with them (visibility "private,shared") — public maps are excluded; pass visibility="public" for public maps and ALWAYS paginate them. Each map includes an "editor_url" deep link — when presenting maps to the user, you MUST make each map's NAME a clickable markdown link to its editor_url. There can be thousands of public maps system-wide, so with visibility="public" set "perpage", fetch one page at a time, read the "total" in the response envelope to gauge how many pages exist, and never assume a single call returned them all. Link format example: `[City Parks](https://<editor>/map/20)` — do not just show plain text names, and do not drop the link to save space. This applies in any format (table, bulleted list, prose). When you render the list as a table, use just two columns — ID and Name (the Name being the clickable link); do NOT add a leading row-number/ordinal "#" column, it is redundant noise.

list_maps

List rows of a table by table name. For layer-scoped access (with layer styling/permissions) use list_features instead.

list_table_rows

List tables readable by the current user — the caller's own GIS Cloud schema by default, or an external DB connection via `connection_id` (see list_dbconnections). PAGINATED: one page per call — compare the received count against the envelope `total` and fetch further pages rather than infer missing names. For the caller's OWN tables `num_rows` is an AUTHORITATIVE count (maintained feature_count, same as list_datasources) — never a planner estimate; for external-connection tables it is ABSENT. expand="columns" adds column definitions (or use get_table for one table). Pass `query` to filter by name (case-insensitive substring) and narrow the listing server-side instead of paging through everything. A table is the underlying spatial or non-spatial PostgreSQL store that backs a vector layer (or stands alone). By default lists tables in the caller's own GIS Cloud schema; pass `connection_id` to instead list tables on an external database connection (see list_dbconnections). Use list_layers if you want layers in a specific map instead. PAGINATED: the response is ONE page (default 100 tables) and the envelope reports the true `total` — a connection can hold far more tables than one page. Always compare the number of tables you received against `total`: if `total` is larger, you have only a PAGE, so say the list is partial and fetch the rest with `page`/`perpage` (or narrow with only_spatial) — NEVER infer, extrapolate, or pattern-fill the table names you did not receive. By default each table carries NO column definitions (just name, geometry, srid, num_rows, primary_key, is_view) to keep the listing small; pass expand="columns" to include them, or call get_table for one table's full columns. COUNTS: for the caller's own tables `num_rows` is the table's maintained feature_count (same source as list_datasources), with a live COUNT fallback for tables that have no datasource record; it is never a raw planner estimate, so it is reliable for "is this empty / roughly how big". A backend monitor keeps it current rather than bumping it on every write, so it can briefly LAG just after rows change (it self-corrects) — when you need an EXACT count run a query_read COUNT(*). For external-connection tables (connection_id) no count is available and `num_rows` is omitted; query_read/query_write only reach your OWN GIS Cloud schema (usrsch*) and layers — they cannot address an external table by name — so to size an external table add it to a map as a layer first and run query_read COUNT(*) against that layer_id.

list_tables

Create a directory (and any missing parents) in user storage.

make_directory

Run a structured SQL-AST read — a SELECT, or a UNION of SELECTs — against one or more PG-backed GIS Cloud layers: filters, aggregations, joins, subqueries, PostGIS spatial predicates. Returns attribute rows. This tool is READ-ONLY and never modifies data — for update/delete/insert use the query_write tool. Top-level node is one of: - {"type":"query", "from":{relation}, "select":[items], "joins":[], "where":null, "group_by":[], "having":null, "order_by":[], "limit":null, "offset":0} — SELECT - {"type":"union","operator":"UNION ALL","queries":[...]} — UNION of SELECTs Node types: column {table,column}, literal {value}, call {name,args}, star {} (the COUNT(*) wildcard — ONLY valid as count's single argument), binary_op {operator,left,right} (comparisons =, !=, >, >=, <, <=, IN, LIKE; arithmetic +, -, *, /, %; string concat ||; integer division truncates — cast a side to numeric for a fractional result), logical_op {operator,conditions} (AND, OR), unary_op {operator,operand} (NOT, IS NULL, IS NOT NULL), cast {expression,as}, case {whens:[{condition,then}],else}, scalar_subquery {query}. Relation: table {table,alias} or relation_subquery {query,alias}. Join: {join_type,source,on} (INNER/LEFT/RIGHT/FULL). select_item {expression,as}. order_by item {expression, direction} — `direction` is REQUIRED, "asc" or "desc"; bare expression objects in order_by are rejected. Example: "order_by":[{"expression":{"type":"call","name":"COUNT","args":[{"type":"column","table":"e","column":"ogc_fid"}]},"direction":"desc"}]. Rules: every table needs an alias, every column reference uses the alias as {type:"column",table:"alias",column:"name"}. Use the `query_table` field from get_layer / list_layers as the `table` value (it's already schema-qualified, e.g. "usrsch3.parcels") — do not guess or strip the schema. PG layers always have wkb_geometry (geometry) and ogc_fid (integer pk) — use ogc_fid for GROUP BY/JOIN. NOTE: a bare ogc_fid in the SELECT list comes back under the key "__id" (the same row-id key get_feature/list_features use) — the engine reserves the literal name "ogc_fid" for the feature id and would otherwise drop it from the row; alias it yourself (ogc_fid AS something) to pick a different output name. To count rows use COUNT(*), written as a call to count with a single star arg: {"type":"call","name":"count","args":[{"type":"star"}]} (or COUNT(ogc_fid) for non-null pk counts). PostGIS functions (ST_Contains, ST_Within, ST_Intersects, ST_DWithin, ST_Transform, etc.) work as call nodes. For cross-SRID spatial predicates, wrap one side with ST_Transform(geom, srid). IN lists: an `IN` right operand may be (a) a scalar_subquery, (b) {"type":"in_list","values":[1,2,3]} for an explicit set of ids/values you can write out (the ONLY correct way to write a literal list — do NOT use a `literal` whose value is an array, that is rejected), or (c) {"type":"in_varints","encoded":"<base64 delta-varint>"} to match a compressed integer id set WITHOUT expanding it (only pass a blob produced by the server, never fabricate one). Each is valid ONLY as the right side of an IN, e.g. ogc_fid IN {"type":"in_list","values":[3,4]}. Datasets: pass `datasets` as a list of items. Each item is either {"layer_id": N} (for items from list_layers / get_layer) or {"table": "name"} (for items from list_tables — bare name is auto-promoted to the caller's usrsch schema; use `usrschN.foo` for tables owned by another user that are shared via a datasource). Joinability: items are joinable iff they share the same conn_id. Per-layer datasource_id is irrelevant. Errors name the conflicting conn_ids. Permissions: reads require READ on every referenced layer/datasource. Permission denials surface as 403 FORBIDDEN.

query_read

Run a structured SQL-AST write — an UPDATE, DELETE or INSERT — against one or more PG-backed GIS Cloud layers, with conditional logic and joins. Returns ONLY the number of affected rows (rows_affected); the per-row RETURNING values/ids are NOT returned to you (a write can touch tens of thousands of rows — there is no point streaming them back). If you need specific updated/inserted values (e.g. a new row's ogc_fid), run a query_read afterwards. For SELECT/UNION reads use the query_read tool. Top-level node is one of: - {"type":"update","target":{table-relation},"set":[set_items],"from":[opt],"joins":[opt],"where":expr,"returning":[items]} — UPDATE - {"type":"delete","target":{table-relation},"using":[opt],"joins":[opt],"where":expr,"returning":[items]} — DELETE - {"type":"insert","target":{table-relation},"columns":["c1","c2"],"values":[[expr,expr],[expr,expr]],"returning":[items]} — INSERT (multi-row VALUES form) Node types: column {table,column}, literal {value}, call {name,args}, star {} (the COUNT(*) wildcard — ONLY valid as count's single argument), binary_op {operator,left,right} (comparisons =, !=, >, >=, <, <=, IN, LIKE; arithmetic +, -, *, /, %; string concat ||; integer division truncates — cast a side to numeric for a fractional result), logical_op {operator,conditions} (AND, OR), unary_op {operator,operand} (NOT, IS NULL, IS NOT NULL), cast {expression,as}, case {whens:[{condition,then}],else}, scalar_subquery {query}. Relation: table {table,alias}. select_item {expression,as} (for `returning`). set_item {column:"<bare name>",value:expr}. Rules: every table needs an alias, every column reference uses the alias as {type:"column",table:"alias",column:"name"}. Use the `query_table` field from get_layer / list_layers as the `table` value (it's already schema-qualified, e.g. "usrsch3.parcels") — do not guess or strip the schema. PG layers always have wkb_geometry (geometry) and ogc_fid (integer pk). THIS TOOL USES A TWO-CALL PREVIEW/CONFIRM FLOW. Called WITHOUT `confirmed` the server DOES NOT MUTATE DATA: it runs validation, generates the SQL, computes a row-count estimate (the values-array length for a VALUES insert, a server-side COUNT(*) over the SELECT for an INSERT … SELECT, and a COUNT(DISTINCT target.ctid) WHERE … for update/delete), and returns {preview_sql, rows_affected_estimate, confirmation_required, expires_at}. You must then: (1) summarize the change for the user in PLAIN LANGUAGE — name the layer/table, what will change (or that rows will be deleted), the filter in human terms (e.g. "rows where status is 'archived'"), and the rows_affected_estimate. DO NOT paste the preview_sql into the user-facing message by default — most users don't read SQL. Treat preview_sql as an internal/debug field; only show it if the user explicitly asks "show me the SQL" or similar; (2) wait for explicit "yes, do it" / "go ahead" — a NEW user message sent after the preview was shown; the request that triggered the preview is not approval; (3) call query_write AGAIN with the SAME datasets + ast PLUS `confirmed: true` to actually execute the write. If the user says no or wants changes, abandon the action or call query_write again (without confirming) to preview the new shape. Confirmations have a 5-minute TTL and are bound to the calling user, the AST, and the datasets — any byte change invalidates them. Do NOT send the confirming call in the same turn as the preview; the user needs a chance to read the preview first. Write rails: - update/delete: `where` is REQUIRED and must not be null (prevents accidental whole-table writes). - insert: `columns` non-empty, `values` non-empty, each `values[i]` row length matches `columns` length, no duplicate column names. - All writes: `returning` REQUIRED and non-empty (the backend uses it internally for the audit trail and form automation). Its VALUES are not returned to you, so keep it minimal — just `[ogc_fid]`; do not add extra columns expecting to read them back. - Validator rejects writes to system columns __id, ogc_fid, and wkb_geometry — geometry edits go through update_feature/create_feature, which handle SRID reprojection. - FORM-BOUND LAYERS: if a referenced layer has a bound form, the write is validated STRICTLY against that form — read-only fields, required fields, types, and allowed option CODEs — exactly as create_feature/update_feature/bulk_update_features are. query_write does NOT bypass form validation when the layer is addressed by {"layer_id"}: setting a read-only field (or violating any form rule) through raw SQL fails the same way it would through the feature tools. SCOPE — this form check is keyed on the {"layer_id": N} dataset reference, because the form is a layer-scoped resource. Referencing the SAME backing store as a raw table — {"table": "usrschN.foo"} — writes straight to the table and SKIPS form validation entirely (option CODEs, required/read-only fields, and form types are NOT enforced). DEFAULT RULE: when data is governed by a bound form, address it by {"layer_id"} so the form is enforced. Do NOT switch to a {"table"} reference in order to get around a form — not even when the caller owns the table or has direct table access; owning the store is not license to bypass its form, and silently routing around form rules can write values the form would reject. A {"table"} write to form-governed data is permitted ONLY when the user has EXPLICITLY asked for a raw / form-free write (e.g. "write straight to the table", "skip the form", a deliberate one-off seed). When unsure whether the user wants to bypass the form, use {"layer_id"} or ask — never bypass on your own initiative. - update/delete/insert targets must be {type:"table",...} (subqueries cannot be write targets). update example: {"type":"update","target":{"type":"table","table":"usrsch3.parcels","alias":"p"},"set":[{"type":"set_item","column":"status","value":{"type":"literal","value":"archived"}}],"where":{"type":"binary_op","operator":"=","left":{"type":"column","table":"p","column":"zone"},"right":{"type":"literal","value":"X"}},"returning":[{"type":"select_item","expression":{"type":"column","table":"p","column":"ogc_fid"},"as":null}]}. delete example: replace the "type"/"set" with {"type":"delete"} and drop "set". insert example: {"type":"insert","target":{"type":"table","table":"usrsch3.parcels","alias":"p"},"columns":["name","status"],"values":[[{"type":"literal","value":"Foo"},{"type":"literal","value":"active"}]],"returning":[{"type":"select_item","expression":{"type":"column","table":"p","column":"ogc_fid"},"as":null}]}. IN lists: an `IN` right operand may be (a) a scalar_subquery, (b) {"type":"in_list","values":[1,2,3]} for an explicit set of ids/values (the ONLY correct way to write a literal list — do NOT use a `literal` whose value is an array, that is rejected), or (c) {"type":"in_varints","encoded":"<base64 delta-varint>"} to match a compressed id set without expanding it (e.g. updating/deleting exactly a set of ogc_fid; only pass a server-produced blob, never fabricate one). Each is valid ONLY as the right side of an IN, e.g. ogc_fid IN {"type":"in_list","values":[3,4]}. Datasets: pass `datasets` as a list of items, each {"layer_id": N} or {"table": "name"} (bare table name is auto-promoted to the caller's usrsch schema; use `usrschN.foo` for another owner's shared table). Joinability: items are joinable iff they share the same conn_id. Permissions: writes require EDIT or LEGACY_WRITE on every referenced layer/datasource (the same set update_feature/bulk_update_features enforce). Permission denials surface as 403 FORBIDDEN.

query_write

Read the content of a text file in user storage. Subject to a server-side 2 MB size cap — files larger than that return FILE_TOO_BIG. Use list_files first to check size.

read_file

Re-mint the short-lived access token for the inline map viewer (see render_map). The embedded viewer calls this ITSELF to keep a PRIVATE map loading on long sessions and after a page reload (where the original token, replayed from chat history, has expired) — you do NOT need to call it. Returns a fresh "accessToken" for the given map. No-op for public maps.

refresh_access_token

Show a map as an INTERACTIVE viewer inline in the chat — the real GIS Cloud map, pannable and zoomable, not a static image. Use this whenever the user wants to SEE, LOOK AT, or EXPLORE a map (open it, view it, preview it, browse it, or check it after edits/adds/style changes). It renders the live GIS Cloud viewer (api.js) right in the conversation, so the user can pan and zoom without leaving the chat. Pass `bounds` to frame a specific extent (e.g. a feature bbox); omit it to fit the map's default extent. Requires a host that supports inline interactive components (MCP Apps); on other hosts the map's name + editor link is returned instead. This is read-only — it never changes the map.

render_map

Extract a ZIP archive that is still sitting un-extracted in user storage, into the same directory (useful for shapefile bundles .shp/.shx/.dbf/.prj before layer creation). IMPORTANT: do NOT call this after upload_binary_file — that tool AUTO-EXTRACTS ZIPs on upload and removes the original archive, so no .zip remains and unzip_file would fail with "Resource not found". The extracted files are already in the directory after the upload (use list_files to see them). unzip_file is only for a .zip that reached storage some other way and is genuinely still archived. Files are extracted into the same directory as the ZIP. The trap to avoid: a ZIP put through upload_binary_file (or a multipart web-UI upload) is expanded into its contents immediately and the .zip itself is removed, so a follow-up unzip_file on that path returns NOTFOUND — the upload already did the extraction. Only reach for unzip_file when a .zip genuinely persists in storage un-extracted. Confirmation handshake: a destructive call without `confirmed` makes NO change — it returns a plain-language `summary` (5-minute TTL). Show the summary and STOP: approval must be a NEW user message sent after seeing it (the triggering request is NOT approval). Only then repeat the call with identical arguments plus `confirmed: true` to execute.

unzip_file

Update an existing bookmark. Only the fields you pass are changed. Confirmation handshake: a destructive call without `confirmed` makes NO change — it returns a plain-language `summary` (5-minute TTL). Show the summary and STOP: approval must be a NEW user message sent after seeing it (the triggering request is NOT approval). Only then repeat the call with identical arguments plus `confirmed: true` to execute.

update_bookmark

Update an existing feature's "attributes" and/or WKT "geometry"; omitted fields stay unchanged. ALWAYS pass "map_id" when known and show the returned editor_url as a clickable markdown link. WKT is read in the parent MAP's SRID by default — pass srid=4326 for lon/lat. Form-bound layers validate changed attributes STRICTLY against the form (inspect via get_layer; exact types, option CODEs case-sensitive). To attach photos/files: upload_binary_file first, then set the column to {"rid": <int>, "path": "<pathname>"} — never a bare path. ALWAYS pass "map_id" when you know it — the response will include an "editor_url" deep link that you MUST show the user as a clickable markdown link. Pass changed attributes under "attributes" and/or new WKT geometry under "geometry". Omitted fields are left unchanged. COORDINATES: by default the WKT is interpreted in the parent MAP's SRID — if you are passing user-friendly lon/lat, pass srid=4326 so the server reprojects. FORM-BOUND LAYERS: if the layer has a bound form, the changed "attributes" are validated STRICTLY against it — inspect the form first via get_layer (returned inline under `form`) and use each field's exact `type` and, for option/select fields, the stored option CODE exactly (case-sensitive), not a display label. See create_feature for the full rule. PHOTO / FILE / SIGNATURE fields: this is the tool that attaches an uploaded file to a feature. First upload the file with upload_binary_file (it returns "pathname" and "rid"), then set the photo column in "attributes" to an attachment spec — {"rid": <int>, "path": "<pathname>"} for one file, or an array of those objects for several. The MCP server expands that into the "___json" storage reference giscloud requires and fills in the layer/feature ids itself; a column set to a bare path (no rid) renders broken. Optional per-file keys: "title" (display name, defaults to the filename) and "panorama" (boolean). create_feature accepts the same attachment spec — it resolves the new feature id for you. Confirmation handshake: a destructive call without `confirmed` makes NO change — it returns a plain-language `summary` (5-minute TTL). Show the summary and STOP: approval must be a NEW user message sent after seeing it (the triggering request is NOT approval). Only then repeat the call with identical arguments plus `confirmed: true` to execute.

update_feature

Update an existing form. Two modes — pick ONE: REPLACE MODE — pass a full new `definition` (and/or `name`, `mappings`). The supplied definition fully replaces the stored one. Use this when you have the complete new form in hand. See create_form for the definition shape. GRANULAR MODE — pass an `edits` array of typed operations. The MCP server fetches the current form, applies edits in order, and PUTs the result. This is the preferred mode for incremental changes (add a field, rename, translate, set a property). Group items are recursed: name-based ops find nested items inside `group` containers automatically. Edit operations: - `{"op":"add","item":<itemDef>, "after"?:"<name>"}` — add an item; positioned after `<name>` at top level, or appended. - `{"op":"remove","name":"<name>"}` — remove the named item (searches nested groups too). - `{"op":"rename","old_name":"<old>","new_name":"<new>","new_title"?:"<title>"}` — rename a field (and optionally retitle). - `{"op":"reorder","order":["<name1>","<name2>", ...]}` — reorder top-level items. List EVERY top-level field name; missing names are appended in original order. - `{"op":"change_property","name":"<field>","property":"<prop>","value":<v>}` — set ANY item property (required, description, persistent, readOnly, value, active, multiline, mode, options, agreement, autocomplete, autofill, automationRules, title, ...). See create_form for the full property list and value shapes (`active` predicate, `automationRules`, `options[]`, translations). To attach an auto-fill rule to a field, use this op with `property:"automationRules"` and the per-item rule array as `value`. - `{"op":"change_type","name":"<field>","new_type":"<type>"}` — change a field's type (text/numeric/select/etc.). - `{"op":"set_form_property","property":"<prop>","value":<v>}` — set a property at the form ROOT (not on an item). Valid `property`: `title`, `description`, `defaultLanguage`, `translatedLanguages`, `noLocation`, `crowdsource`, `mdcp`. Use this (NOT `change_property`) for form-level changes. (`automationRules` is per-item — set it with `change_property`, never here.) Translation note: to add languages, emit one `set_form_property` for `defaultLanguage`, one for `translatedLanguages`, one each for form-root `title`/`description` with language-keyed objects, and one `change_property` per item for `title` + `description` (and `options` on select/radio/checkbox, `agreement` on signature). Every translatable property gets `{default, <lang1>, <lang2>, ...}`. You can also pass `name` and/or `mappings` alongside `edits` — they're forwarded to the API in the same PUT. Confirmation handshake: a destructive call without `confirmed` makes NO change — it returns a plain-language `summary` (5-minute TTL). Show the summary and STOP: approval must be a NEW user message sent after seeing it (the triggering request is NOT approval). Only then repeat the call with identical arguments plus `confirmed: true` to execute.

update_form