More tools by module

This page is generated from the repository on every merge to main; changes made here are overwritten.

These tools were added after the category list in the generator was last curated, so the reference groups them by the module that defines them. They are real, registered tools like the others.

allocation_tools

calculate_allocation_envelope

Split a budget the user gives across areas in proportion to need (optionally times population), with optional ceiling and floor per area, optional rounding, and areas below a need threshold left out. This is an ADVISORY CALCULATION of an envelope, not a recommendation of who should receive what: the budget, the need field, the exponent, the ceiling/floor and the exclusion threshold are the user's decisions, so ask for them and state them with the result. Need can be a severity score, a people-in-need count or any non-negative field; population is optional. Areas with a missing or negative value are excluded and listed, never imputed. If ceilings stop the whole budget being spent the rest is reported as unallocated. Optionally writes each area's amount to the layer (needs confirmation). Never invent a budget, a cost per person or a coefficient.

Parameter	Type	Required	Description
layer_name	string	yes	Vector layer with the areas (e.g. admin polygons).
budget	number	yes	The total to split, in the user's own unit. Must be given by the user.
need_field	string	yes	Non-negative numeric field that drives the split (e.g. a 0-1 severity score or people in need).
population_field	string	no	Optional numeric field; when given the weight is need x population.
unit_name_field	string	no	Optional field used to label areas in the results.
need_exponent	number	no	Weight = need ** exponent. Default 1 (proportional). Above 1 favours the neediest areas more, below 1 spreads more evenly.
max_share_per_unit	number	no	Optional ceiling per area as a share of the budget, above 0 and at most 1 (e.g. 0.15).
min_amount_per_unit	number	no	Optional floor guaranteed to every area with a positive weight.
exclude_need_below	number	no	Optional: areas with need below this get nothing.
rounding	number	no	Optional: round amounts to multiples of this (e.g. 100); the total is preserved.
unit_label	string	no	Optional label for the budget's unit (e.g. 'USD'); echoed in the result.
output_field	string	no	Optional: write each area's amount to the layer under this field name.

attribute_edit_tools

add_feature_from_wkt

Add one feature to an existing layer from WKT geometry (POINT, LINESTRING, POLYGON ...). crs is the CRS of the WKT coordinates (default: the layer's own); it is transformed in code. attributes is {field: value}. The geometry type must match the layer.

Parameter	Type	Required	Description
layer_name	string	yes
wkt	string	yes
attributes	object	no
crs	string	no	e.g. EPSG:4326

add_field

Add an empty field to a layer. field_type: string, integer, long, double, date or datetime.

Parameter	Type	Required	Description
layer_name	string	yes
field_name	string	yes
field_type	string	no

clear_selection

Deselect all features: of one layer, or of every layer in the project when layer_name is omitted.

Parameter	Type	Required	Description
layer_name	string	no

delete_features

Delete features from a layer: those matching an expression, or the currently selected ones (only_selected). Destructive: a preview with the exact count is shown for confirmation first. Never deletes everything unless the expression says so.

Parameter	Type	Required	Description
layer_name	string	yes
expression	string	no
only_selected	boolean	no

delete_field

Delete a field (column) and all its values from a layer. Destructive: a preview is shown for confirmation first.

Parameter	Type	Required	Description
layer_name	string	yes
field_name	string	yes

rename_field

Rename a field of a layer.

Parameter	Type	Required	Description
layer_name	string	yes
field_name	string	yes
new_name	string	yes

select_all_features

Select every feature of a layer.

Parameter	Type	Required	Description
layer_name	string	yes

select_by_expression

Select features of a layer with any QGIS expression (for example "population" > 1000 AND "type" = 'school'). mode: replace (default), add, remove or intersect with the current selection.

Parameter	Type	Required	Description
layer_name	string	yes
expression	string	yes
mode	string	no	replace, add, remove or intersect

set_attribute_value

Set one field to a value on specific features: pick them by feature_id or by an expression. Numeric fields need numbers; a typo is refused, not turned into NULL. Use the string null to clear a value. Changes data: a preview with the count is shown first.

Parameter	Type	Required	Description
layer_name	string	yes
field	string	yes
value	string	yes
feature_id	integer	no
expression	string	no

barrier_tools

apply_network_barriers

Put blocked or degraded places into a road network for routing: destroyed bridges, checkpoints, flooded stretches or any other barrier layer (points, lines or polygons such as a flood extent). Every road segment within buffer_m metres of a barrier is blocked (mode='block') or has its speed multiplied by penalty_factor (mode='penalise'); all other segments keep their speed. Writes the result to a new numeric speed field (km/h) on the road layer, and draws the affected segments as a separate red (blocked) or orange (slowed) layer '_barrier_affected' so the effect is visible on the map; pass that field as speed_field to calculate_service_area / travel_time_matrix / optimize_delivery_route. Blocked segments are REMOVED from the network by those tools (any strategy), so nothing can cross them; slowed segments only matter with strategy='fastest'. Pass speed_field (e.g. from build_composite_impedance_field) to keep realistic base speeds; without it unaffected segments are 30 km/h.

Parameter	Type	Required	Description
road_network_layer	string	yes	Line layer representing the road network.
barrier_layer	string	yes	Layer of barriers: points (bridge, checkpoint), lines or polygons (flood extent).
buffer_m	number	no	Distance in metres around each barrier within which roads are affected. 0 = only roads that touch/cross the barrier. Default 50.
mode	string	no	'block' (default) or 'penalise'.
penalty_factor	number	no	For mode='penalise': speed multiplier between 0 and 1 (e.g. 0.25). Ignored for 'block'.
speed_field	string	no	Optional existing numeric speed field (km/h) to start from, e.g. from build_composite_impedance_field.
output_field	string	no	Name of the new speed field. Default 'barrier_speed'.

batch_tool

run_processing_batch

Run ONE approved Processing algorithm over several layers (1 to 20), one run per layer, with the same settings for each, and put the results together in a new layer group. For example buffer 5 layers by 100 m, or compute slope for 8 rasters. layers are layer names; parameters are the settings shared by all runs (not the input and not an output); input_parameter names the algorithm's input (default INPUT). Each result layer is named _ and is temporary. A layer that fails does not stop the others: the reply lists each failure and its reason. Algorithms that change your own layers (selections) are refused. The group name must be new. Stop ends the batch and the reply says how far it got.

Parameter	Type	Required	Description
algorithm_id	string	yes	An approved algorithm id such as native:buffer.
layers	array[string]	yes	1 to 20 layer names, each once.
parameters	object	no	Settings shared by all runs, for example {"DISTANCE": 100}.
input_parameter	string	no	The algorithm's input parameter name (default INPUT).
group_name	string	no	Name of the new layer group (default _batch); it must not exist yet.

cartographic_advisory_tools

recommend_visualization_method

Recommends which styling tool fits a layer/field's actual data semantics -- geometry type, field type, cardinality, and distribution -- before you style it, instead of guessing the renderer or defaulting to whichever tool was used last. ADVISORY ONLY: returns a recommendation and rationale, never applies any styling itself -- you still call the recommended tool (or a different one, if you have good reason) yourself. Use this before any apply_*_style call on a field you haven't already styled by in this conversation, especially before a choropleth on a polygon layer, since the single most common real-world misuse is coloring raw counts instead of a rate/density.

Parameter	Type	Required	Description
layer_name	string	yes
field	string	no	Optional. Omit for a reference/location-only map with no field to style by.
intended_message	string	no	Optional free-text hint, e.g. 'show which districts have the worst access gap' or 'show route status'. Used only to explain a recommendation more specifically -- never to override what the data itself actually supports.

cluster_scan_tool

detect_spatial_clusters

Find the most likely CLUSTER of excess cases with Kulldorff's circular spatial scan statistic (Poisson model): it tries circles of every size around every area, scores each by how many more cases it holds than its population would give, and reports the best circle with its centre, radius, cases, expected cases, relative risk and a Monte Carlo p-value (how often chance alone does as well), plus further non-overlapping circles that are also significant. Writes the circles to a NEW layer (the input is never changed). Needs a whole-number case field and a population field on every area, a projected CRS, and numpy (ships with QGIS). Use it for 'is this a real cluster', 'where is the most likely cluster', outbreak or incident clustering; it shows where cases exceed population, never why. max_pop_fraction (default 0.5, the largest allowed) caps a cluster's share of the population. At most 1,500 areas.

Parameter	Type	Required	Description
layer_name	string	yes
case_field	string	yes	Whole-number case counts per area.
population_field	string	yes	Population at risk per area (above zero).
model	string	no	Only 'poisson' is built.
max_pop_fraction	number	no	Largest share of the population a cluster may hold, 0.01 to 0.5 (default 0.5).
max_radius	number	no	Largest cluster radius in layer units (default: no limit besides the population cap).
monte_carlo	integer	no	Random re-draws for the p-value, 99 to 9999 (default 999).
seed	integer	no	Random seed (default 1); the same seed gives the same numbers on the same numpy version.
max_clusters	integer	no	Most clusters to report, 1 to 20 (default 5).
alpha	number	no	Significance level for secondary clusters (default 0.05).
output_layer_name	string	no	Name of the new layer (default '_scan_clusters').

confidence_tools

get_layer_confidence

Reads a layer's current confidence/epistemic-status classification, if any was set via set_layer_confidence. Returns level=null if never tagged -- not the same as UNKNOWN, just unclassified.

Parameter	Type	Required	Description
layer_name	string	yes

set_layer_confidence

Tags a layer with its epistemic-status/confidence level -- OBSERVED (directly recorded, e.g. a surveyed facility location), DERIVED (computed from observed data with no modeling assumptions, e.g. a buffer or spatial join), MODELED (built from a model with real assumptions, e.g. a service area or population-exposure estimate), INFERRED (a conclusion drawn beyond what the data directly shows), or UNKNOWN (provenance genuinely unclear). Use this on any layer whose confidence level matters for how a reader should trust it -- especially anything that will be exported or printed. No automated classification exists -- only what's explicitly set here is tracked.

Parameter	Type	Required	Description
layer_name	string	yes
level	string	yes	OBSERVED, DERIVED, MODELED, INFERRED, or UNKNOWN.
reason	string	no	Optional short reason, e.g. 'buffer output, no field verification' or 'population estimate, WorldPop 2025 raster'.

copy_features_tool

copy_features_between_layers

Copy features from one vector layer into another existing layer of the SAME geometry type (point, line or polygon; a mismatch is refused): the selected features (default when some are selected), those matching filter_expression, or all of them. field_mapping is {target field: source field}; fields with the same name are matched automatically, the rest stay empty, and a value that does not fit the target field's type stops the copy with nothing changed. A different CRS is transformed to the target's. Changes the target layer: a preview with the mapping is shown for confirmation first, the edit is one undoable step (undo_manual_edit), and the source layer is never changed.

Parameter	Type	Required	Description
source_layer	string	yes	The vector layer to copy from.
target_layer	string	yes	The existing vector layer to copy into (same geometry type).
only_selected	boolean	no	Copy only the selected features (default: yes when the source has a selection, else all).
filter_expression	string	no	A QGIS expression: copy the features it is true for (instead of the selection).
field_mapping	object	no	{target field: source field}; unnamed target fields match a source field of the same name.

corridor_tools

generate_contours

Make contour lines from a DEM raster layer at a fixed elevation interval (in the DEM's own elevation units, normally metres), as a NEW LINE LAYER with an 'ELEV' field -- the usual meaning of 'draw / make / create contour lines of the DEM, every 100'. Use set_raster_relief instead only when the user wants the raster itself shown as contours (render / style) without a new layer. The interval is the vertical spacing between lines, NOT the accuracy of the terrain: the result reports the DEM's pixel size and source so the user can judge what the lines can show. Refuses very large rasters. When the request names a DEM that is already in the project ("the dem", "smoke_dem"), call this directly with that layer: do not fetch a new DEM and do not plan a fetch first.

Parameter	Type	Required	Description
raster_layer	string	yes	Name of the DEM raster layer.
interval	number	no	Elevation step between contour lines, default 10.
band	integer	no	Band number, default 1.
output_name	string	no

split_lines_by_zones

Split a line layer (a road, a highway, a pipeline) by a polygon layer of zones (exclusion zones, flood areas, buffers) into compromised pieces (inside any zone) and clear pieces (outside every zone), style them red and green, and report both the total passable length in km and the longest continuous passable segment in km (they are different numbers). Lengths are ellipsoidal. Connected line features are joined first, so a road stored as many OSM segments counts as one continuous road. Creates a new layer; the inputs are not changed.

Parameter	Type	Required	Description
line_layer	string	yes	Name of the line layer.
zone_layer	string	yes	Name of the polygon layer (for example the checkpoint buffers).
output_name	string	no	Optional name of the result layer.

critical_link_tools

analyze_critical_links

Screen a road network for bottlenecks: how much origin-to-destination demand has its shortest path through each road segment. A segment with a high load is one many routes depend on -- closing it would push all of them onto other roads. This is a SCREENING measure of dependence, not a closure simulation and not a traffic forecast: one shortest path per pair (cost = distance, or time from the speed field), no congestion, convoy size or security, and the load counts OD pairs unless weight fields are given. Origins are capped (default 50, max 200) and a time budget stops the run between origins and labels the result partial; for national road data clip the network to the area first. Closed roads (negative speed) are left out. Draws the roads graded by load in a new layer and returns the heaviest segments.

Parameter	Type	Required	Description
road_network_layer	string	yes	Line layer with the road network.
origins_layer	string	yes	Point layer of origins (e.g. warehouses, hubs).
destinations_layer	string	no	Point layer of destinations (e.g. facilities, settlements). Default: the origins layer.
strategy	string	no	'shortest' (distance, default) or 'fastest' (time).
default_speed	number	no	km/h for segments without a speed, used only for 'fastest'. Default 50.
speed_field	string	no	Optional per-segment speed (km/h). A negative value marks a closed road, which is removed.
direction_field	string	no	Optional one-way field.
value_forward	string	no	direction_field value for forward-only. Default 'yes'.
value_backward	string	no	direction_field value for backward-only. Default '-1'.
value_both	string	no	direction_field value for both ways. Default 'no'.
origin_weight_field	string	no	Optional non-negative numeric field weighting each origin.
destination_weight_field	string	no	Optional non-negative numeric field weighting each destination (e.g. population).
max_origins	integer	no	Origins to use, at most 200. Default 50; more origins are left out and counted.
max_snap_m	number	no	A destination further than this from the road graph is left out. Default 2000 m.
time_budget_s	number	no	Stop between origins after this many seconds. Default 120.
top_n	integer	no	Heaviest segments to return. Default 10.
output_layer_name	string	no	Name of the output line layer. Default 'critical_links'.

data_export_tools

export_stored_data

Exports everything Cartogen AI has stored for this project and this machine -- project memory notes, global memory notes/preferences, and chat history (if chat history saving is enabled in Settings) -- into one structured JSON file. Use this when the user asks what data the plugin has stored, wants a copy of their conversation/notes, or needs a data-portability export. Chat history is included only if the user has opted into 'Save chat history in the project file' -- this tool does not change that setting or read history that was never saved. The chat history it exports is only a rolling window of the most recent messages plus a short digest of older ones (see chat_history_info in the file), never a full transcript; say so when reporting it.

Parameter	Type	Required	Description
output_path	string	yes	Full file path to write the JSON export to, e.g. 'C:/Users/me/Desktop/cartogen_data_export.json'.

data_layer_tools

add_postgis_layer

Add a PostGIS table or view to the project as a layer, using a database connection already saved in QGIS (Browser panel > PostgreSQL). Give the connection name, schema and table; geometry_column and key_column are only needed when the table has several geometry columns or no primary key. Read-only data access: it adds a layer, it changes nothing in the database. Use execute_read_only_sql for a query instead of a whole table.

Parameter	Type	Required	Description
connection_name	string	yes
table	string	yes
schema	string	no
geometry_column	string	no
key_column	string	no
layer_name	string	no

create_virtual_layer

Create a virtual layer: a live SQL (SQLite/SpatiaLite) query over the layers in the project, for example SELECT a.name, count(b.id) AS n FROM districts a JOIN points b ON ST_Contains(a.geometry, b.geometry) GROUP BY a.name. Reference layers by their project layer name. Only a single SELECT is accepted; paths, URLs, comments, ATTACH and other statements are refused. The layer is not saved to disk and follows the source layers.

Parameter	Type	Required	Description
layer_name	string	yes
sql	string	yes
geometry_column	string	no	name of the geometry column in the result, if it is not detected

load_layer_definition

Load a QGIS layer definition file (.qlr) into the project: the layers it holds come with their styles. The layers read their own data sources, so a .qlr is only as safe as the files and services it points to.

Parameter	Type	Required	Description
file_path	string	yes

package_layers_offline

Package vector layers into ONE GeoPackage file for offline use or hand-over, keeping their styles and metadata (QGIS native:package). layer_names is the list of vector layers; file_path ends in .gpkg. only_selected packs just the selected features. An existing file is only replaced after confirmation. Raster layers are not packaged.

Parameter	Type	Required	Description
layer_names	array[string]	yes
file_path	string	yes
only_selected	boolean	no

save_layer_definition

Save chosen layers of the project, with their styles, to a QGIS layer definition file (.qlr) that can be loaded into other projects. layer_names is the list of layers. An existing file is only replaced after confirmation.

Parameter	Type	Required	Description
layer_names	array[string]	yes
file_path	string	yes

data_source_tools

add_basemap

Add a background map to the QGIS project from a fixed list: openstreetmap, opentopomap, satellite (Esri imagery), esri streets, carto light, carto dark. The layer is placed at the bottom of the layer tree. Tiles are loaded by QGIS directly from the provider.

Parameter	Type	Required	Description
basemap	string	yes	openstreetmap, topo, satellite, esri streets, carto light, carto dark

add_web_layer

Add a web map or feature service to the project. service_type: xyz (tile URL with {z}/{x}/{y}), wms, wmts, wfs or arcgis_feature. Only https URLs are accepted. wms/wmts need layer (the service layer name), wmts also tile_matrix_set, wfs needs layer (typename).

Parameter	Type	Required	Description
service_type	string	yes
url	string	yes
layer_name	string	no
layer	string	no	service layer / typename
crs	string	no
image_format	string	no
tile_matrix_set	string	no
style	string	no

create_empty_layer

Create a new EMPTY vector layer (or a table with no geometry) with the fields you choose, ready for digitising. geometry_type: point, line, polygon, multipoint, multiline, multipolygon or none. fields: list of {name, type} with type string, integer, long, double, date or datetime. By default a scratch (in-memory) layer is added; give file_path ending .gpkg, .shp or .geojson to create a file.

Parameter	Type	Required	Description
layer_name	string	yes
geometry_type	string	yes
fields	array[object]	no
crs	string	no	e.g. EPSG:4326 (default)
file_path	string	no	optional .gpkg/.shp/.geojson to create on disk

find_broken_layers

List the project layers whose data source cannot be read (moved or deleted file, lost drive) with the path they point to. Read-only.

No parameters.

repair_layer_source

Point a broken layer at its data again. Give new_path if you know where the file is; otherwise the project folder (and search_folder, if given) is searched for a file with the same name. One match is applied; several are listed so you can choose one.

Parameter	Type	Required	Description
layer_name	string	yes
new_path	string	no
search_folder	string	no

save_layer_as

Save a vector layer to a file in another CRS and/or with only some fields and/or only the selected features (the QGIS 'Save As' options). format: gpkg, shp, geojson or kml. The original layer is not changed and the new file is NOT added to the project unless add_to_project is true.

Parameter	Type	Required	Description
layer_name	string	yes
output_path	string	yes
format	string	yes
crs	string	no	target CRS, e.g. EPSG:4326; omit to keep the layer's CRS
fields	array[string]	no	field names to keep; omit for all
only_selected	boolean	no
add_to_project	boolean	no

dataset_status_tools

advance_dataset_status

Move a layer's QA-gate lifecycle status forward one step (e.g. STAGED -> VALIDATED), backward (to mark a regression), or re-state it -- never skipping a state. The INGESTED -> STAGED step automatically runs a P-code depth check (uniqueness + parent/child hierarchy prefix-match) when the layer has P-code-shaped fields, and auto-passes as not-applicable otherwise -- so it never blocks a non-admin-boundary layer. The STAGED -> VALIDATED step automatically runs the existing geometry-validity check (diagnose_topology) and refuses to advance if it fails, unless override=True is passed with a note justifying the bypass. The VALIDATED -> ANALYSIS_READY step runs a schema-contract check (validate_schema) instead, but ONLY when contract_name is supplied -- omit it and this transition behaves like any other unchecked one (a note is required). The CARTOGRAPHY_READY -> PUBLICATION_READY step runs a map-QA check (generate_map_product_qa_checklist) when layout_name is supplied -- refuses to advance if the layout is missing a mandatory element (map/title/legend/scale bar/north arrow) or the layer is tagged RESTRICTED/SENSITIVE, unless override=True is passed with a note justifying the bypass. Omit layout_name and this transition behaves like any other unchecked one. Every other transition has no automated check yet and requires a note explaining the manual advance. Moving backward always requires a note. Call get_dataset_status first if unsure of the layer's current status, set_dataset_status first if it isn't tracked yet, and list_schema_contracts to see available contract_name values.

Parameter	Type	Required	Description
layer_name	string	yes
target_status	string	yes	One of INGESTED, STAGED, VALIDATED, ANALYSIS_READY, CARTOGRAPHY_READY, PUBLICATION_READY.
note	string	no	Required for transitions with no automated check, for any backward move, and for an override.
override	boolean	no	Bypass a failed automated check. Requires note. Defaults to false.
contract_name	string	no	Only used for VALIDATED -> ANALYSIS_READY, e.g. 'health_facilities' or 'admin2'. See list_schema_contracts.
layout_name	string	no	Only used for CARTOGRAPHY_READY -> PUBLICATION_READY -- the print layout built for this map product (from create_print_layout).

get_dataset_status

Read a layer's tracked QA-gate lifecycle status (one of INGESTED, STAGED, VALIDATED, ANALYSIS_READY, CARTOGRAPHY_READY, PUBLICATION_READY), its full status-change history, and any automated check results recorded against it. Returns status=null for a layer that has never been tagged -- call set_dataset_status first to start tracking it.

Parameter	Type	Required	Description
layer_name	string	yes

set_dataset_status

Start QA-gate lifecycle tracking on a layer that isn't tracked yet, tagging it with a starting status (defaults to INGESTED). Refuses to run on a layer that already has a tracked status -- use advance_dataset_status to move an already-tracked layer forward or back instead, so this can't accidentally erase real QA history.

Parameter	Type	Required	Description
layer_name	string	yes
status	string	no	Starting status. One of INGESTED, STAGED, VALIDATED, ANALYSIS_READY, CARTOGRAPHY_READY, PUBLICATION_READY. Defaults to INGESTED.
note	string	no	Optional note explaining why tracking starts at this status.

dem_tools

fetch_dem

Download elevation (a DEM raster) for an area from the Copernicus DEM GLO-30 open dataset (about 30 m, no account or key needed) and add it to the project. Give the area as a layer name (its extent), as a bounding box in degrees (west, south, east, north), or as a centre point (lat, lon) with radius_km. The result is a surface model (includes buildings/trees), not bare earth, about 30 m resolution; the reply records source, tiles used, retrieval date, vertical datum and the required attribution. Refuses very large areas. Use generate_contours or slope_analysis on the result. ONLY for an area with no DEM in the project yet: when the request names a DEM layer that is already loaded ("the dem", "smoke_dem"), use that layer and do not call this.

Parameter	Type	Required	Description
layer_name	string	no	Name of a layer whose extent defines the area.
west	number	no
south	number	no
east	number	no
north	number	no
lat	number	no	Centre latitude (with lon and radius_km).
lon	number	no	Centre longitude.
radius_km	number	no	Half-width of the square around the centre, km.
output_path	string	no	Optional GeoTIFF path; relative paths are anchored to the project folder.
output_name	string	no	Optional layer name.

edit_ops_tools

change_field_type

Change the data type of a field to string, integer, long or double, converting the values. Values that cannot be converted become NULL and numbers lose their fraction when going to integer: the preview says how many. The field moves to the end of the table.

Parameter	Type	Required	Description
layer_name	string	yes
field	string	yes
new_type	string	yes

merge_features

Merge (union) several features of a layer into one: those matching an expression or the selected ones. The first feature keeps its attributes and gets the combined geometry; the others are deleted. Needs at least two features. Destructive: a preview is shown first.

Parameter	Type	Required	Description
layer_name	string	yes
expression	string	no	QGIS expression choosing the features
only_selected	boolean	no	use the currently selected features instead

redo_manual_edit

Redo the last undone edit step on a layer that is in edit mode.

Parameter	Type	Required	Description
layer_name	string	yes

set_layer_editing

Start editing a layer, save its edits, or discard them (action: start, save or discard). Discarding unsaved edits is destructive and needs confirmation.

Parameter	Type	Required	Description
layer_name	string	yes
action	string	yes	start, save or discard

set_layer_filter

Set or clear a layer's filter (definition query): only features matching the filter are shown and used. The filter is a plain condition in the data source's own syntax, such as "population" > 1000. Statements, comments and semicolons are refused. clear=true removes the filter. The data is not changed.

Parameter	Type	Required	Description
layer_name	string	yes
filter	string	no
clear	boolean	no

split_features_by_line

Cut features of a polygon or line layer along a line given as WKT (LINESTRING(x1 y1, x2 y2, ...)) in the layer's CRS or in the CRS given. Splits the features matching an expression or the selected ones that the line crosses. Changes data: a preview is shown first.

Parameter	Type	Required	Description
layer_name	string	yes
expression	string	no	QGIS expression choosing the features
only_selected	boolean	no	use the currently selected features instead
line_wkt	string	yes
crs	string	no	e.g. EPSG:4326

transform_features

Move, rotate and/or scale features of a layer: those matching an expression, or the selected ones (only_selected). move_x and move_y are in the layer's units, rotate_degrees is clockwise about each feature's centre, scale_factor scales about each feature's centre. Changes geometry: a preview with the exact count is shown for confirmation first.

Parameter	Type	Required	Description
layer_name	string	yes
expression	string	no	QGIS expression choosing the features
only_selected	boolean	no	use the currently selected features instead
move_x	number	no
move_y	number	no
rotate_degrees	number	no
scale_factor	number	no

undo_manual_edit

Undo the last edit step on a layer that is in edit mode (the layer's own undo history, including edits made by hand). Use undo_last_operation for assistant operations on a layer not in edit mode.

Parameter	Type	Required	Description
layer_name	string	yes

elevation_tools

set_layer_elevation

Change a layer's elevation settings (used by elevation profiles and 3D views). Raster: enabled, mode 'surface' (the cells are heights) or 'fixed_range', band, z_offset, z_scale. Vector (no on/off switch): clamping 'absolute', 'relative' or 'terrain', z_offset, z_scale, extrusion (metres). Only the values you give are changed; the result lists the settings read back.

Parameter	Type	Required	Description
layer_name	string	yes
enabled	boolean	no
mode	string	no
band	integer	no
z_offset	number	no
z_scale	number	no
clamping	string	no
extrusion	number	no

set_project_terrain

Set the project's terrain used by elevation profiles and 3D views: source 'flat' (optional offset) or 'dem' (a raster layer, optional offset and scale). Stored in the project; nothing is written to the data.

Parameter	Type	Required	Description
source	string	yes
layer_name	string	no
offset	number	no
scale	number	no

engineering_tools

assess_watershed_hydrology_request

Preflight a watershed/peak-flow engineering request before any result is reported. It normalizes a DMS outlet and identifies the measured data and cited design inputs still required. A coordinate plus return period is insufficient: never invent a DEM-derived basin, IDF intensity, runoff coefficient, elevation drop, flow length, Tc, or peak flow. Call this first for coordinate-only watershed requests.

Parameter	Type	Required	Description
location	string	yes	Outlet location in DMS form.
return_period_years	number	yes	Requested design return period in years.
dem_source	string	no	Loaded DEM layer or authoritative DEM dataset and resolution, if available.
idf_source	string	no	Local authoritative IDF station/curve/publication, if available.
runoff_coefficient	number	no	Locally justified Rational Method runoff coefficient C, if available.

calculate_rational_watershed_peak_flow

Calculate H, main-channel slope, Kirpich channel-flow Tc, and Rational Method peak discharge from explicit measured inputs. First call it WITHOUT rainfall_intensity_mm_h to get Tc, then read the cited local IDF curve at that duration and call again with the intensity, its duration, its source and the runoff coefficient. It does not delineate a watershed and must never receive guessed area, length, elevations, intensity, or C.

Parameter	Type	Required	Description
area_km2	number	yes	Delineated watershed area in km².
flow_length_km	number	yes	Longest hydraulic flow-path/main-channel length in km; not total stream length.
upstream_elevation_m	number	yes	DEM elevation at the selected hydraulically remote upstream point in metres.
outlet_elevation_m	number	yes	DEM elevation at the snapped outlet in metres, using the same vertical datum.
return_period_years	number	yes	Design return period in years.
rainfall_intensity_mm_h	number	no	Local IDF rainfall intensity in mm/h for the return period and Tc duration. Omit on the first call to get Tc.
intensity_duration_minutes	number	no	Duration in minutes used to read/interpolate the supplied IDF intensity.
intensity_source	string	no	Authoritative local IDF station, curve, publication, and edition/date.
runoff_coefficient	number	no	Dimensionless Rational Method runoff coefficient C, locally justified.

parse_dms_location

Convert a user-supplied latitude/longitude in degrees-minutes-seconds (DMS) to an exact WGS84 decimal-degree outlet coordinate. Use this instead of manually converting DMS. This only normalizes the coordinate; it does not delineate a watershed or infer elevations.

Parameter	Type	Required	Description
location	string	yes	DMS latitude and longitude, including N/S and E/W hemispheres.

event_data_tools

fetch_ucdp_conflict_events (two-phase)

Fetch organised-violence events (state-based conflict, non-state conflict, one-sided violence against civilians) from UCDP, the Uppsala Conflict Data Program's Candidate Events dataset, filtered by country name, bounding box and dates, and load them as a point layer with deaths (best, low, high estimates), conflict name, location precision and event clarity. Free, no API key; downloaded from ucdp.uu.se and cached for 12 hours. NOT live: candidate data is preliminary and lags real time by weeks, so always state the dataset's latest event date. IMPORTANT: bbox is [min_lon, min_lat, max_lon, max_lat]. Dates are 'YYYY-MM-DD'. Re-running REPLACES the layer's features. Cite UCDP (CC BY 4.0).

Parameter	Type	Required	Description
country	string	no	Country name or part of it, e.g. 'Yemen' or 'Sudan'. Omit for all countries.
bbox	array[number]	no	Optional [min_lon, min_lat, max_lon, max_lat] in WGS84 degrees.
start_date	string	no	Earliest event date, 'YYYY-MM-DD'.
end_date	string	no	Latest event date, 'YYYY-MM-DD'.
min_deaths	integer	no	Only events with at least this many deaths (UCDP best estimate). Defaults to 0.
max_events	integer	no	Most events to load (newest first). Defaults to 1000, at most 5000.
layer_name	string	no	Name for the layer. Defaults to 'UCDP Conflict Events'.

fetch_usgs_earthquakes (two-phase)

Fetch recent earthquakes from the USGS (United States Geological Survey) for an optional bounding box and load them as a point layer coloured by magnitude band, with magnitude, depth, time, alert level, tsunami flag and a link per event. Free, no API key. IMPORTANT: bbox is [min_lon, min_lat, max_lon, max_lat], same convention as fetch_nasa_eonet_events. Defaults: last 7 days, magnitude 4.5 or more, up to 1000 events. Re-running REPLACES the layer's features, so it is safe to schedule.

Parameter	Type	Required	Description
bbox	array[number]	no	Optional [min_lon, min_lat, max_lon, max_lat] in WGS84 degrees. Omit for global coverage.
days	integer	no	How many days back (1 to 365). Defaults to 7.
min_magnitude	number	no	Smallest magnitude to include. Defaults to 4.5.
max_events	integer	no	Most events to return (newest first). Defaults to 1000, at most 5000.
layer_name	string	no	Name for the layer. Defaults to 'USGS Earthquakes'.

fact_check_tools

search_fact_checks (network-only)

Look up whether a CLAIM, VIDEO, PHOTO or RUMOUR has recently been fact-checked, in the published feeds of named fact-checking outlets (Snopes, PolitiFact, FactCheck.org, Full Fact, Lead Stories and the Arabic-language Fatabyyano). Use it when the user asks 'is this true', 'was this video really from ', 'has this been debunked' or wants to verify a social-media report before mapping it. Give the distinctive words of the claim (place, event, person), not a whole sentence. Returns each matching check with the outlet, date, link and a short summary, and ALWAYS says which outlets answered or failed and that this covers only each outlet's newest entries: no match is NOT evidence that a claim is true, false or unchecked, so never say that. Reuters, AFP, Africa Check and AP cannot be asked (they refuse automated requests). Quote the outlet's conclusion as theirs and give the link; do not add your own verdict.

Parameter	Type	Required	Description
query	string	yes	Distinctive words of the claim, e.g. 'Hodeidah port strike video' or 'Taiz protest'.
days	integer	no	Only checks published in the last N days (default 60).
max_results	integer	no	Most matches to return, 1-50 (default 15).
sources	array[string]	no	Optional subset of ['snopes', 'politifact', 'factcheck_org', 'full_fact', 'lead_stories', 'fatabyyano']; default all.

field_rules_tools

add_virtual_field

Add a virtual (calculated) field to a layer: its value is computed from a QGIS expression every time the layer is read, and nothing is written into the data file, so it can never be out of date. For example density = "population" / $area. field_type: string, integer, long, double, date or datetime. The expression must be valid and evaluate on the first feature. Stored with the project, not in the file. Remove it with remove_virtual_field.

Parameter	Type	Required	Description
layer_name	string	yes	The vector layer.
name	string	yes	The new field's name (letters, digits, underscore, spaces).
field_type	string	no	string, integer, long, double, date or datetime (default string).
expression	string	yes	The QGIS expression that gives the value.

remove_virtual_field

Remove a virtual field made with add_virtual_field. Only virtual fields can be removed this way; a real column is never touched (use delete_field for that, which asks first).

Parameter	Type	Required	Description
layer_name	string	yes
name	string	yes	The virtual field's name.

set_default_value

Set or remove the default value of a field: a QGIS expression QGIS evaluates to fill the field of every NEW feature (for example now(), @user_account_name or a number). apply_on_update also re-evaluates it whenever the feature is edited. An empty expression removes the default. Existing features are not changed. Stored with the project, not in the data file.

Parameter	Type	Required	Description
layer_name	string	yes	The vector layer.
field	string	yes	The field that gets the default.
expression	string	yes	The QGIS expression; empty text removes the default.
apply_on_update	boolean	no	Also re-evaluate when the feature is edited (default false).

set_field_constraint

Set or remove the rules QGIS enforces on a field: not_null, unique and/or an expression (with a description shown when it fails), hard (blocks the value) or soft (warns). A rule that is given is set (true / a text) or removed (false / an empty text); one that is left out is untouched. The reply reads the rules back and checks the existing features against them: how many break them is reported, nothing is changed. Stored with the project, not in the data file.

Parameter	Type	Required	Description
layer_name	string	yes	The vector layer.
field	string	yes	The field the rules are on.
not_null	boolean	no	true: the value may not be empty; false: remove that rule.
unique	boolean	no	true: no two features may have the same value; false: remove that rule.
expression	string	no	A QGIS expression that must be true, for example "population" >= 0; empty text removes it.
description	string	no	The message shown when the expression fails.
strength	string	no	hard (default) blocks the value, soft only warns.

hazard_monitoring_tools

fetch_gdacs_disaster_alerts (two-phase)

Fetch current UN-coordinated disaster alerts from GDACS (Global Disaster Alert and Coordination System) -- earthquakes, floods, tropical cyclones, volcanoes, wildfires, droughts -- each with a human-assigned Green/Orange/Red severity, and load them as a point layer. GDACS's own terms of use (verified 2026-09-12) state that its automated alerts and impact estimations 'may require further validation' and 'should not be used for decision making without prior confirmation of their validity' -- pass this caveat along if a user asks about acting on a specific alert. Free, no API key. Defaults to Orange and above (excludes minor/localized Green advisories) -- pass min_alert_level='Green' to include everything. IMPORTANT: bbox (when given) is [min_lon, min_lat, max_lon, max_lat], same convention as fetch_nasa_active_fires and fetch_nasa_eonet_events. IMPORTANT: if the user names a specific place ('the latest GDACS alerts for Yemen') rather than giving coordinates, pass country (e.g. country='Yemen') -- omitting BOTH bbox and country returns every alert worldwide, which is very rarely what a place-scoped request actually wants. Re-running this tool REPLACES the layer's features with the latest fetch, so it's safe to schedule on a recurring interval. Each returned alert's 'unit' value is also stored on the layer as an 'event_id' field -- to act on SPECIFIC named alerts (e.g. 'buffer around alerts 123,456'), select by that field (select_by_attribute for one, or highlight_features with "event_id IN ('123','456')" for several) rather than operating on the whole layer.

Parameter	Type	Required	Description
bbox	array[number]	no	Optional [min_lon, min_lat, max_lon, max_lat] in WGS84 degrees. Omit for global coverage.
min_alert_level	string	no	Minimum alert level to include: 'Green', 'Orange' (default), or 'Red'.
country	string	no	Optional country name to scope results to (case-insensitive substring match against GDACS's own per-alert country field, e.g. 'Yemen'). Use this or bbox (or both) whenever the user named a specific place -- don't leave both empty for a place-scoped request.
layer_name	string	no	Name for the layer. Defaults to 'GDACS Disaster Alerts'. Re-fetching with the same name replaces its features rather than duplicating them.

fetch_nasa_active_fires (two-phase)

Fetch near-real-time active fire/thermal-anomaly detections from NASA FIRMS (VIIRS satellite instrument) for a bounding box, and load them as a point layer. Needs a free NASA FIRMS API key configured in Settings -- if missing, this returns a clear error with a link to get one. IMPORTANT: bbox is [min_lon, min_lat, max_lon, max_lat] (matches search_stac_satellite_imagery's convention) -- NOT the [south, west, north, east] order fetch_building_footprints uses. Re-running this tool (e.g. via schedule_recurring_workflow) REPLACES the layer's features with the latest fetch rather than accumulating duplicates, so it's safe to schedule on a recurring interval to watch for new fire activity -- run_monitoring_workflow will then report new/disappeared detections automatically.

Parameter	Type	Required	Description
bbox	array[number]	yes	[min_lon, min_lat, max_lon, max_lat] in WGS84 degrees.
days	integer	no	How many days back to look, 1-10. Defaults to 1.
min_confidence	string	no	Minimum detection confidence to include: 'low', 'nominal' (default), or 'high'.
layer_name	string	no	Name for the layer. Defaults to 'NASA Active Fires'. Re-fetching with the same name replaces its features rather than duplicating them.

fetch_nasa_eonet_events (two-phase)

Fetch open (or closed/all) natural events from NASA EONET -- wildfires, severe storms, volcanoes, floods, sea/lake ice, drought, dust/haze, and more -- for an optional bounding box, and load them as a point layer (each event's most recent known position). Free, no API key. IMPORTANT: bbox is [min_lon, min_lat, max_lon, max_lat], same convention as fetch_nasa_active_fires and search_stac_satellite_imagery. Re-running this tool REPLACES the layer's features with the latest fetch, so it's safe to schedule on a recurring interval. Each returned event's 'unit' value is also stored on the layer as an 'event_id' field -- to act on a SPECIFIC named event, select by that field (select_by_attribute, or highlight_features for several) rather than operating on the whole layer.

Parameter	Type	Required	Description
bbox	array[number]	no	Optional [min_lon, min_lat, max_lon, max_lat] in WGS84 degrees. Omit for global coverage.
category	string	no	Optional EONET category id to filter to, e.g. 'wildfires', 'severeStorms', 'volcanoes', 'floods', 'drought'.
days	integer	no	How many days back to look. Defaults to 20.
status	string	no	'open' (default), 'closed', or 'all'.
layer_name	string	no	Name for the layer. Defaults to 'NASA EONET Events'. Re-fetching with the same name replaces its features rather than duplicating them.

generate_situation_dashboard

Fetch live hazard data (NASA active fires, NASA EONET natural events, GDACS disaster alerts) for a bounding box and export it all as one interactive HTML situation dashboard in a single call -- the fastest way to answer 'what hazards are happening in this area right now'. Internally calls fetch_nasa_active_fires/fetch_nasa_eonet_events/fetch_gdacs_disaster_alerts (each skipped gracefully, not fatally, if its source errors -- e.g. no FIRMS API key configured) then generate_html_dashboard. IMPORTANT: bbox is [min_lon, min_lat, max_lon, max_lat], same convention as the 3 fetch tools it calls.

Parameter	Type	Required	Description
bbox	array[number]	yes	[min_lon, min_lat, max_lon, max_lat] in WGS84 degrees.
output_path	string	no	Optional output HTML file path.
title	string	no	Optional dashboard title.
include_fires	boolean	no	Include NASA FIRMS active fires. Defaults to true.
include_eonet	boolean	no	Include NASA EONET natural events. Defaults to true.
include_disasters	boolean	no	Include GDACS disaster alerts. Defaults to true.

health_rates_tool

calculate_health_rates

Compute disease or incident RATES for areas from a case count and a population: the crude rate per 100,000 (or per), its 95% interval, the RELATIVE RISK (area rate over the overall rate), the indirectly standardised ratio SMR (observed over expected, ONLY when you supply an expected-count field: this tool never invents expected counts, so age or sex adjustment must come from you), and a global empirical-Bayes SMOOTHED rate that steadies small areas. method chooses the headline value ('crude', 'smr' or 'eb'). Every area with cases below 5 (min_cases) or a population below min_population gets a small-number flag and an EMPTY value_shown, so a map made from value_shown never shows an unstable figure. Writes a NEW layer; the input is never changed. Needs a whole-number case field and a population field above zero on every area.

Parameter	Type	Required	Description
layer_name	string	yes
case_field	string	yes	Whole-number case counts per area.
population_field	string	yes	Population at risk per area (above zero).
method	string	no	crude (default), smr (needs expected_field) or eb (smoothed).
expected_field	string	no	Expected case counts you computed (for example by age and sex standardisation). Required for method='smr'.
per	number	no	Rate denominator (default 100000).
min_population	number	no	Flag areas with a smaller population (default: no population floor).
min_cases	integer	no	Flag areas with fewer cases than this (default 5).
output_layer_name	string	no	Name of the new layer (default '_rates').

hotspot_tool

analyze_hotspots_gi_star

Find statistically significant HOT SPOTS (clusters of high values) and COLD SPOTS (clusters of low values) of a numeric field with Getis-Ord Gi*: a z-score and p-value per feature, an optional false-discovery (Benjamini-Hochberg) correction, and a class 'Hot spot 99%' / 'Hot spot 95%' / 'Hot spot 90%' / 'Cold spot ...' / 'Not significant', written to a NEW layer (the input is never changed). This is a significance TEST on the field's values, not a density map: for a density surface of where points are concentrated use hotspot_analysis. weights: 'queen' or 'rook' (polygon layers), 'knn' (pass k) or 'distance' (a band in layer units, projected CRS only, pass distance); each feature counts itself as part of its own neighbourhood. Needs a number on every feature (it refuses and says how many are missing); at most 5,000 features. A hot spot means high values near high values, not a cause: do not describe it as an outbreak or a threat without other evidence.

Parameter	Type	Required	Description
layer_name	string	yes
field	string	yes	A numeric field (a count, a rate, an index).
weights	string	no	queen (default), rook, knn or distance.
k	integer	no	For weights='knn': how many nearest neighbours each feature counts besides itself.
distance	number	no	For weights='distance': the band in the layer's units (projected CRS).
fdr	boolean	no	Apply the Benjamini-Hochberg false-discovery correction (default true).
alpha	number	no	The weakest significance reported: 0.05 (default) reports 99% and 95% spots, 0.10 adds 90%, 0.01 reports only 99%.
output_layer_name	string	no	Name of the new layer (default '_gi_star').

humanitarian_look_tools

apply_humanitarian_look

Style a layer's analysis-result field the way humanitarian maps expect, after calculate_severity_index, calculate_population_in_need, calculate_presence_gap, calculate_damage_exposure_severity, calculate_mcda_ranking or calculate_allocation_envelope wrote it (their results carry a map_look hint with the exact arguments). look='severity': a 0-1 score in five equal classes yellow to dark red that match the tool's own 1-5 classes; 'people_in_need', 'exposure' or 'allocation': a count or amount in quantile classes; 'presence_gap': gap / covered / unmatched; 'rank': the top_k ranked units dark. Changes only the layer's renderer (nothing is written to the data); units with no value in the field are not drawn. Only call it when the user wants the result shown on the map or accepts the offer.

Parameter	Type	Required	Description
layer_name	string	yes	The layer that holds the result field.
look	string	yes	severity: a 0-1 composite severity score (calculate_severity_index, calculate_damage_exposure_severity): five equal-interval classes, yellow to dark red, the same classes the tools report; people_in_need: a people / population count (calculate_population_in_need): quantile classes in purple; exposure: an exposed-population count: quantile classes in orange-brown; allocation: an allocation amount (calculate_allocation_envelope): quantile classes in green; presence_gap: the gap / covered / unmatched status from calculate_presence_gap; jiaf_severity: a JIAF 2 severity PHASE 1-5 (jf_pre_sev, jf_fin_sev): phase colours 1 none/minimal to 5 catastrophic; a unit with no phase is drawn grey as not assessed; jiaf_review_pin: JIAF 2 PiN review status (jf_pin_st): which units have no flag, were closed in bulk, were decided, or still wait for the group; jiaf_review_severity: JIAF 2 severity review status (jf_sev_st): preliminary accepted, decided, pending the group, or incomplete sector coverage; jiaf_count: a small JIAF 2 count per unit (jf_npinfl, jf_nsevfl, jf_nsec40, jf_nsev45): how many flags or sectors; zero its own class; ipc_phase: an IPC acute food insecurity phase 1-5 (ipc_phase from import_humanitarian_table): the IPC phase colours; an area with no phase is grey, not phase 1; inform_risk: an INFORM score on its 0-10 scale (inf_risk, inf_haz, inf_vuln, inf_coping): the five published classes very low to very high; damage_class: UNOSAT damage classes on a point layer (destroyed, severe, moderate, possible, none), matched on the file's own wording such as 'Severe Damage'; measure: any measured number (zonal mean, road speed, impedance cost): five quantile classes light to dark blue, low to high; rank: a rank field (calculate_mcda_ranking, _rank): the top_k units dark, the next top_k mid, the rest pale
field	string	yes	The result field to style.
top_k	integer	no	For look='rank': how many top-ranked units to emphasise. Defaults to 10.

identify_tool

identify_at_point

Say what is at a coordinate, as the Identify tool does on the map but without a click: the attributes of the features of the vector layers under the point and the cell value of each band of the raster layers. x and y are in crs (default: the project CRS). By default the visible layers are checked; layers names others. Give a radius (in the units of that CRS: metres for a projected CRS, degrees for a geographic one) to find points and lines near the coordinate: without it only features exactly under the point match. At most 50 features are returned in total and the reply says when more matched. Read-only.

Parameter	Type	Required	Description
x	number	yes	X (longitude or easting) in crs.
y	number	yes	Y (latitude or northing) in crs.
crs	string	no	The CRS of x and y, for example EPSG:4326 (default: the project CRS).
layers	array[string]	no	Layer names to look at (default: all visible layers).
radius	number	no	Search radius in the CRS's units (default 0: only what is exactly under the point). Vector layers only.
max_features	integer	no	Fewest features wanted, 1 to 50 (default 50). 50 is the most that is ever returned.

impedance_tools

build_composite_impedance_field

Builds a single blended per-segment speed field on a road network layer -- combining OSM highway-class baseline speed, OSM surface-condition penalty, an optional damage/passability field, and an optional DEM-derived slope penalty into one number in km/h. Feeds directly into calculate_service_area/travel_time_matrix/optimize_delivery_route's existing speed_field parameter -- run this first, then pass output_field's name as speed_field to those tools with strategy='fastest' for realistic routing that avoids unpaved/damaged/steep roads instead of treating every segment as equally fast. Requires highway_field/surface_field to already exist on the layer (e.g. from fetch_osm_features) -- a layer without them still gets a flat default speed with no penalties, not an error.

Parameter	Type	Required	Description
road_network_layer	string	yes	Line layer representing the road/path network.
highway_field	string	no	Field holding the OSM highway=* class (e.g. 'primary', 'track'). Defaults to 'highway'.
surface_field	string	no	Field holding the OSM surface=* value (e.g. 'paved', 'gravel'). Defaults to 'surface'.
damage_field	string	no	Optional numeric field, 0.0-1.0, giving each segment's passability (1.0=fully passable, 0.0=closed: the segment is removed from the network by the routing tools, e.g. from a road-status assessment). Non-numeric values default to 1.0 (unknown = assumed passable).
dem_layer	string	no	Optional DEM raster layer. When given, each segment's endpoints are sampled for elevation and a slope penalty applied -- steeper segments get a lower effective speed.
output_field	string	no	Name of the new field to write the blended speed (km/h) into. Defaults to 'impedance_cost'.
dem_vertical_unit	string	no	Vertical unit of the DEM's elevation values: 'm' (default), 'ft' or 'us_ft'. A raster does not carry it.

in_place_tool

run_algorithm_in_place

Apply an approved Processing algorithm that supports editing in place (for example native:smoothgeometry, native:translategeometry, native:simplifygeometries) DIRECTLY to a vector layer instead of making a new layer. selected_only true changes only the selected features, false changes every feature. parameters are the algorithm's settings (not the input or output). Changes your data: a preview with the exact feature count is shown first, the change is ONE undoable step (undo_manual_edit) and stays UNSAVED in the layer's edit session until you save it (set_layer_editing). Your selection is put back afterwards.

Parameter	Type	Required	Description
algorithm_id	string	yes	An approved algorithm id that supports in-place editing, e.g. native:smoothgeometry.
layer_name	string	yes	The vector layer to change.
selected_only	boolean	yes	true: only the selected features; false: every feature.
parameters	object	no	The algorithm's settings, for example {"ITERATIONS": 2}.

incident_search_tools

find_incident_reports (two-phase)

Find incident and hazard reports for a country / place and a time window from a FIXED list of reliable sources, with the source, its rating and a link on every record: GDACS (UN alerts), USGS (earthquakes), NASA EONET (storms, fires, volcanoes, floods), UCDP (armed conflict events; preliminary, weeks old) and ReliefWeb (declared disasters; listed, not mapped). Records with a position are loaded as a point layer. Use this INSTEAD of search_web for 'what incidents / disasters / conflict events happened in ' questions. News is searched only when sources includes 'news' (unverified headlines, placed by the place named in the headline, lowest rating); fact-checkers and social media are never searched. The reply lists every source that could not be asked: always say which sources were checked and that an empty result is not proof nothing happened. Free, no keys. IMPORTANT: give a country (or place name) and/or bbox [min_lon, min_lat, max_lon, max_lat]; days is 1 to 365 (default 30). Re-running REPLACES the layer's features.

Parameter	Type	Required	Description
country	string	no	Country or place name, e.g. 'Yemen' or 'Sudan'. Matched by name against each source.
bbox	array[number]	no	Optional [min_lon, min_lat, max_lon, max_lat] in WGS84 degrees.
days	integer	no	How many days back (1 to 365). Defaults to 30.
sources	array[string]	no	Optional subset of: gdacs, usgs, eonet, ucdp, reliefweb, news. Default: the five agency sources. Add 'news' (or use only ['news']) when the user asks for NEWS or media reports.
max_reports	integer	no	Most records to return (newest first). Defaults to 200, at most 500.
layer_name	string	no	Name for the layer. Defaults to 'Incident reports'.

jiaf_engine

compute_jiaf_preliminary

Compute the PRELIMINARY JIAF 2 figures from sector inputs (support for the JIAF 2 process; NOT the JIAF method, not endorsed by OCHA or the IASC; never call the result JIAF-compliant or official). Per unit: the preliminary joint PiN (the highest of the eight main sectors' PiN -- the Mosaic Method; never an average, never a sum across sectors; AoRs excluded), the PiN flags 1-6 of Reference Table 3A, the preliminary intersectoral severity from the overlap of sectoral severities, and the severity flags 1-4 of Table 3B1. The national figure is the sum over units. This is not the Final PiN or the final severity: those are group decisions for flagged units, recorded later, and nothing here decides them. Intersectoral severity is per unit; there is no national severity and no PiN per severity phase. Incomplete sector coverage is never turned into phase 1: the sectors in scope (default all eight main sectors) that have no phase are missing, and if they could change the result the unit has NO preliminary severity (status incomplete_coverage, with lower and upper bounds); a severity of 0 means not-applicable unless zero_severity_as='missing'. Several flag thresholds are readings of the manual that are not verified against OCHA's worksheet formulas: they are settings, echoed in the result, to be confirmed by the analysis team. Reads the same files as import_jiaf_inputs; give previous_file_path for flag 6. Optionally writes jf_pre_pin, jf_pre_sev, jf_npinfl, jf_nsevfl to an admin layer (needs confirmation) and a per-unit CSV.

Parameter	Type	Required	Description
file_path	string	yes	The sector-input file (OCHA worksheet, HXL table or sector template), as for import_jiaf_inputs.
input_format	string	no	'auto' (default), 'ocha_worksheet', 'hxl' or 'sector_template'.
sheet_name	string	no
previous_file_path	string	no	Optional previous-year file of the same kind, for flag 6.
previous_sheet_name	string	no
rules_profile	string	no	'ocha_worksheet_2026' (default: the flag formulas read from OCHA's official Worksheet 3A/3B) or 'manual_reading' (this tool's older interpretation of the manual, for comparison only).
sectors_sev_5	integer	no	Worksheet profile: severity flag 1 fires at this many sectors in phase 5 (and flag 4 uses it too). Default: the workbook's Thresholds cell, else 2.
sectors_sev_4	integer	no	Worksheet profile: the header-text reading of severity flag 4 (reported only, not used by the formula). Default 5.
sectors_in_scope	array[string]	no	Main sectors the HCT activated. Default: all eight. A sector in scope with no value is MISSING, never phase 1.
zero_severity_as	string	no	'not_applicable' (default) or 'missing': what a severity of 0 means.
f1_min_sectors	integer	no	Flag 1 fires at this many sectors that are missing or zero. Worksheet profile: the workbook's zero_pin_thresh, else 2 (manual_reading: 1).
f1_count_missing	boolean	no	manual_reading profile only. Flag 1 counts sectors with NO PiN. Default true.
f1_count_zero	boolean	no	manual_reading profile only. Flag 1 counts sectors with an explicit PiN of 0. Default true. Missing and zero are different facts.
f2_pct	number	no	Flag 2 threshold as a fraction (0.30 = 30%). Default: the workbook's perc_1st_2nd, else 0.30.
f3_pct	number	no	Flag 3 threshold as a fraction. Default: the workbook's perc_1st_3rd, else 0.50.
f4_subpopulation_sectors	array[string]	no	Sectors that count a sub-population. Worksheet profile: the workbook's own list, else the template's (education). manual_reading: flag 4 is evaluated only if given.
f5_share	number	no	Flag 5 threshold as a share of population (fires at >=). Default: the workbook's flag_pin_perc, else 0.90.
f6_pct	number	no	Flag 6 threshold on the (rounded to 0.1) change from last year, up or down, as a fraction. Default: the workbook's flag_pin_historical, else 1.0.
f6_min_previous_pin	number	no	manual_reading profile only. Flag 6 is only evaluated when last year's PiN is at least this. Default 1000.
s4_sector_count	integer	no	manual_reading profile only. Severity flag 4 fires when MORE THAN this many sectors are in phase 4 (and the preliminary phase is 4). Default 4.
export_csv_path	string	no	Optional new .csv file for the per-unit table (refuses to overwrite).
layer_name	string	no
layer_key_field	string	no	Admin 2 P-code field on that layer.
write_fields	boolean	no	With layer_name: write jf_pre_pin, jf_pre_sev, jf_npinfl, jf_nsevfl. Needs confirmation.

jiaf_inputs

get_jiaf_setup

Read the JIAF 2 analysis set-up and sector alignment records stored in the project by record_jiaf_setup (support for the JIAF 2 process; not endorsed by OCHA or the IASC).

No parameters.

import_jiaf_inputs

Read and validate the sector inputs for a JIAF 2 analysis (support for the JIAF 2 process; not the JIAF method, not endorsed by OCHA or the IASC, no joint PiN or severity is computed here). Reads an .xlsx/.csv of one of three kinds: the OCHA Workspace 3A/3B worksheet ('WS - 3.1 Overall PiN' + 'WS - 3.2 Intersectoral Severity'), an HXL-tagged published table (#adm2 +code, #inneed +wsh, #severity +shl ...), or the manual's per-sector template (give sector and template_kind). Reports units, sectors found, per-sector totals, and every problem: severity must be a phase 1-5 (0 is reported as not-applicable, never turned into a phase), PiN must be a non-negative number, duplicates and missing values are listed and never filled. Stored columns (Preliminary/Final PiN, Final Severity) are returned only as stored and are NOT trusted. Optionally joins to an admin layer by P-code and, after confirmation, writes the values as new numeric fields (jp_ for PiN, js_ for severity). Never invent a threshold or fill a missing value.

Parameter	Type	Required	Description
file_path	string	yes	Absolute path to the .xlsx or .csv file.
input_format	string	no	'auto' (default), 'ocha_worksheet', 'hxl' or 'sector_template'.
sheet_name	string	no	Sheet to read for 'hxl' or 'sector_template' (default: the first).
sector	string	no	For 'sector_template': the sector the file belongs to (cccm, education, nutrition, food_security, health, protection, shelter, wash, child_protection, gbv, mine_action, hlp).
template_kind	string	no	For 'sector_template': 'pin' or 'severity'.
layer_name	string	no	Optional admin polygon layer to join to.
layer_key_field	string	no	Field on that layer holding the Admin 2 P-code.
write_fields	boolean	no	With layer_name: write jp_ (PiN) and js_ (severity) fields. Needs confirmation.

record_jiaf_setup

Record the JIAF 2 analysis set-up in the project (support for the JIAF 2 process; not endorsed by OCHA or the IASC): country, planning cycle, unit of analysis (e.g. admin 2), the manual edition followed (e.g. 'July 2024'), areas and population groups in scope, whether the Humanitarian Country Team endorsed the scope, and optionally each sector's alignment self-assessment (manual Workspaces 2A/2B): whether its PiN is aligned with the joint-overall-PiN guidance, whether its severity scale is aligned or adapted, with an explanation whenever it is not aligned or is adapted, and the indicators and thresholds it used. Replaces any earlier record. Stored in the QGIS project; nothing is computed or decided.

Parameter	Type	Required	Description
country	string	yes
planning_cycle	string	yes	e.g. 'HPC 2026'.
unit_of_analysis	string	yes	e.g. 'admin 2' or 'admin 2 x population group'.
manual_edition	string	yes	The JIAF 2 Technical Manual edition followed, e.g. 'July 2024'.
areas_in_scope	string	no
population_groups	string	no
scope_note	string	no
hct_endorsed_scope	boolean	no	Whether the HCT endorsed the scope; omit if unknown.
sector_alignment	array[object]	no

jiaf_patterns

compute_jiaf_patterns

Produce the JIAF 2 intersectoral pattern outputs of Workspace 3C (support for the JIAF 2 process; not the JIAF method, not endorsed by OCHA or the IASC): where the PiN is concentrated, which units have many sectors with more than 40% of the population in need, which sectors drive the PiN, the change against last year, units in severity phases 4-5 and with five or more sectors in phase 4-5, sector severity distributions, units with both high PiN and high severity, and the sector pairs whose PiN correlates above 0.7. These are lists and counts for the analysts' discussion, not conclusions. Thresholds are country-level settings (the manual's defaults where it gives one; the others are the module's and are echoed). Uses the recorded group decisions where they exist and the preliminary severity otherwise (reported). No national severity; not for ranking crises. Optionally writes jf_nsec40 and jf_nsev45 (counts per unit, for mapping) to an admin layer after confirmation.

Parameter	Type	Required	Description
file_path	string	yes
input_format	string	no
sheet_name	string	no
previous_file_path	string	no
previous_sheet_name	string	no
sectors_in_scope	array[string]	no	Main sectors the HCT activated. Default: all eight.
zero_severity_as	string	no	'not_applicable' (default) or 'missing'.
sector_population_share	number	no	Share of a unit's population that makes a sector's PiN 'large'. Manual: 0.40.
many_sectors_with_large_pin	integer	no
top_units	integer	no
high_pin_share	number	no
severe_phases	array[integer]	no	Default [4, 5].
many_severe_sectors	integer	no	Manual: 5.
top_sectors	integer	no	Manual: 3.
correlation_threshold	number	no	Manual: 0.7.
group_shares	object	no	Optional population shares per group, e.g. {'girls': 0.25}, for the extrapolated estimates.
layer_name	string	no
layer_key_field	string	no
write_fields	boolean	no	With layer_name: write jf_nsec40 and jf_nsev45. Needs confirmation.

jiaf_review

finalize_jiaf_results

Apply the recorded JIAF 2 group decisions to the preliminary figures and report the FINAL results (support for the JIAF 2 process; NOT the JIAF method, not endorsed by OCHA or the IASC; never call the result JIAF-compliant or official). A unit with no flag keeps the preliminary figures; a flagged unit uses its recorded decision; a flagged unit with no decision is PENDING: its Final PiN is shown at the highest sectoral PiN as a provisional figure (counted and totalled separately) and its final severity is left empty. The Final PiN total is the sum over units; there is no national severity and no PiN per severity phase. bulk_accepted_flags (e.g. [1]) closes units whose only fired PiN flags are those; this is an analysis-team decision and REQUIRES bulk_rationale (why) and ideally bulk_decided_by, which are recorded in the result and against every unit closed. The flag conditions are unverified interpretations of the manual (see validation_blockers in the result): the number of pending units depends on them. Reads the same files and uses the same flag settings as compute_jiaf_preliminary. Optionally writes jf_fin_pin, jf_fin_sev, jf_pin_rk to an admin layer (needs confirmation) and a per-unit CSV with the Evidence & Comments (never overwrites).

Parameter	Type	Required	Description
file_path	string	yes
input_format	string	no
sheet_name	string	no
previous_file_path	string	no
previous_sheet_name	string	no
bulk_accepted_flags	array[integer]	no	PiN flag numbers the team agreed to close in bulk, e.g. [1]. Needs bulk_rationale.
bulk_rationale	string	no	Why the team closed these flags in bulk (required with bulk_accepted_flags).
bulk_decided_by	string	no	Who decided, e.g. 'JIAF analysis group, 12 Oct'.
rules_profile	string	no	'ocha_worksheet_2026' (default) or 'manual_reading' (older interpretation, comparison only).
sectors_sev_5	integer	no
sectors_sev_4	integer	no
f1_min_sectors	integer	no
f1_count_missing	boolean	no
f1_count_zero	boolean	no
sectors_in_scope	array[string]	no	Main sectors the HCT activated. Default: all eight; a sector with no value is missing, never phase 1.
zero_severity_as	string	no	'not_applicable' (default) or 'missing'.
f2_pct	number	no
f3_pct	number	no
f4_subpopulation_sectors	array[string]	no
f5_share	number	no
f6_pct	number	no
f6_min_previous_pin	number	no
s4_sector_count	integer	no
export_csv_path	string	no	Optional new .csv file (refuses to overwrite).
layer_name	string	no
layer_key_field	string	no
write_fields	boolean	no	With layer_name: write jf_fin_pin, jf_fin_sev, jf_pin_rk. Needs confirmation.

get_jiaf_decisions

Read the JIAF 2 group decisions stored in the project by record_jiaf_decisions (support for the JIAF 2 process; not endorsed by OCHA or the IASC).

No parameters.

record_jiaf_decisions

Record the multi-partner group's JIAF 2 decisions for flagged units (support for the JIAF 2 process; not endorsed by OCHA or the IASC; this tool decides nothing, it only records what the group decided). pin_decisions: for a flagged unit, which main sector's PiN is used as the Final PiN (the manual offers the highest or second highest; any main sector is accepted and the rank of the chosen one is reported) with the rationale (required). severity_decisions: the agreed intersectoral severity phase 1-5 for a flagged unit with the evidence basis (outcome_indicators, proxy_indicators, expert_judgement or sector_overlap_accepted) and the evidence (required). Stored in the QGIS project, merged with earlier records unless replace=true. Never invent a decision; ask the team.

Parameter	Type	Required	Description
pin_decisions	array[object]	no
severity_decisions	array[object]	no
replace	boolean	no	Replace all stored decisions instead of merging.

land_cover_look_tool

apply_land_cover_look

Colour a land-cover or change layer the way the standard does. scheme 'esa_worldcover': the official ESA WorldCover class colours on a classified raster, or on a vector field (pass field) holding the class code (10, 20 ... 100) or the class name. scheme 'change_classes': loss, stable and gain (-1, 0, 1 or those words) in orange, grey and purple, never red and green. scheme 'protected_area_hatch': a diagonal hatch with an outline on a polygon layer, so what is underneath stays visible. The legend carries each class name and code. Values that are not a class are drawn grey and named in the reply; nothing is silently recoloured. This only changes how the layer is drawn.

Parameter	Type	Required	Description
layer_name	string	yes
scheme	string	yes	esa_worldcover, change_classes or protected_area_hatch.
field	string	no	For a VECTOR layer with esa_worldcover or change_classes: the field holding the class code or class name. Not used for a raster or for protected_area_hatch.

layer_display_tools

add_feature_action

Add an action to a layer's feature action menu that OPENS A WEB ADDRESS built from the feature's values (action_type open_url, url starting with http:// or https://, with [% expression %] fields, for example https://en.wikipedia.org/wiki/[% "name" %]). Actions that run a command, Python code or a program are REFUSED by policy: they run on the user's computer on every click. Stored with the project.

Parameter	Type	Required	Description
layer_name	string	yes	The vector layer.
name	string	yes	The label shown in the action menu.
action_type	string	yes	open_url (the only type that is added; command types are refused).
url	string	no	http(s) address, may contain [% expression %] fields.

set_conditional_formatting

Colour the cells of a layer's attribute table by rules: each rule is a QGIS expression condition (@value is the cell's value, or use any field) and a background_color and/or text_color, for one field, or for whole rows when field is left out. For example {"condition": "@value > 1000", "background_color": "#ffcccc"}. The rules replace the ones already set for that field (or the row rules); an empty list is not accepted, use clear true to remove them. Stored with the project, not in the data file. Display only: no data changes.

Parameter	Type	Required	Description
layer_name	string	yes	The vector layer.
field	string	no	The field to colour; leave out to colour whole rows.
rules	array[object]	no	[{condition, background_color, text_color, name}], 1 to 20 rules, the first that matches wins.
clear	boolean	no	true: remove the rules of that field (or the row rules) instead of setting any.

set_map_tip

Set the map tip of a layer: the HTML bubble shown when the pointer rests on a feature, written with [% expression %] fields, for example '[% "name" %]
Population [% "pop" %]'. Only plain HTML and expression fields are allowed: script, frame, object, embed, form, link, meta and base tags, event handlers and javascript: addresses are refused. An empty template removes the tip. Stored with the project. Map tips only show while View > Show Map Tips is on, which this tool does not change.

Parameter	Type	Required	Description
layer_name	string	yes	The vector layer.
template	string	yes	HTML with [% expression %] fields; empty text removes the map tip.

layout_chart_profile_tools

add_layout_chart

Add a chart to a print layout: chart_type 'bar', 'line' or 'pie' of layer_name, with x_field (the categories) and y_field (the values), both plain field names. Position and size in millimetres. A chart item draws the layer's own features, so it follows the layer.

Parameter	Type	Required	Description
layout_name	string	yes
layer_name	string	yes
chart_type	string	no
x_field	string	yes
y_field	string	yes
x_mm	number	no
y_mm	number	no
width_mm	number	no
height_mm	number	no
item_id	string	no

add_layout_elevation_profile

Add an elevation profile to a print layout along a straight line from (start_x, start_y) to (end_x, end_y) in the project CRS. layer_names are the layers to profile; each needs elevation turned on first (set_layer_elevation). Give either start/end coordinates or along_layer, the name of a LINE layer (a road, a river): the profile then runs from the first to the last vertex of its selected feature, or its first feature. Position and size in millimetres.

Parameter	Type	Required	Description
layout_name	string	yes
layer_names	array[string]	yes
start_x	number	no
start_y	number	no
end_x	number	no
end_y	number	no
x_mm	number	no
y_mm	number	no
width_mm	number	no
height_mm	number	no
item_id	string	no
along_layer	string	no

layout_extra_tools

add_overview_map

Show where one layout map is looking on another map (a locator or overview inset): overview_map_id is the map that draws the frame (the small inset), extent_map_id is the map whose extent the frame shows (default MAP_MAIN). To create the inset too, give inset_box {x_mm, y_mm, width_mm, height_mm}; it is zoomed out around the main map. color and width_mm style the frame.

Parameter	Type	Required	Description
layout_name	string	yes
overview_map_id	string	no
extent_map_id	string	no
color	string	no
width_mm	number	no
inset_box	object	no

set_layout_atlas

Turn a print layout into an atlas: one page per feature of coverage_layer. page_name_field names each page, sort_field orders them, filter_expression keeps only some features (a QGIS expression), hide_coverage hides the coverage layer outside the current feature, margin_percent pads the map around each feature, scaling is auto, fixed or predefined, map_item_id is the map that follows the atlas (default MAP_MAIN). disable=true switches the atlas off. Export it with export_layout_atlas.

Parameter	Type	Required	Description
layout_name	string	yes
coverage_layer	string	no
page_name_field	string	no
sort_field	string	no
filter_expression	string	no
hide_coverage	boolean	no
margin_percent	number	no
scaling	string	no
map_item_id	string	no
disable	boolean	no

set_layout_guides_grid

Set a print layout's alignment aids: guides (a list of {orientation: horizontal|vertical, position_mm}; replaces the guides on the first page), clear_guides=true to remove them, grid_mm for the snapping grid spacing, snap_to_grid and snap_to_guides to switch snapping on or off. These affect how items snap when edited; they do not print.

Parameter	Type	Required	Description
layout_name	string	yes
guides	array[object]	no
clear_guides	boolean	no
grid_mm	number	no
snap_to_grid	boolean	no
snap_to_guides	boolean	no

layout_item_tools

add_layout_item

Add one item to a print layout that already exists (see list_layouts): a text label, a picture from a local image file (png, jpg, svg), a shape (rectangle, ellipse, triangle), an arrow, or an attribute table of a vector layer. Position and size are in millimetres from the page's top-left corner (an A4 landscape page is 297 x 210). An arrow is given by its start and end points instead of a box. Give the item an item_id to find it again; list_layout_items shows what is there. HTML frames and pictures from a web address are refused on purpose.

Parameter	Type	Required	Description
layout_name	string	yes
kind	string	yes	label, picture, shape, arrow or table
item_id	string	no	Letters, digits, space, - and _ (max 64). Generated if omitted.
x_mm	number	no
y_mm	number	no
width_mm	number	no
height_mm	number	no
text	string	no
font_size	number	no
font_color	string	no
picture_path	string	no
shape	string	no
fill_color	string	no
outline_color	string	no
outline_width_mm	number	no
from_x_mm	number	no
from_y_mm	number	no
to_x_mm	number	no
to_y_mm	number	no
layer_name	string	no	For a table: the vector layer.
fields	array[string]	no	For a table: the columns to show.
max_rows	integer	no	For a table: rows to show (default 10, at most 200).

edit_layout_item

Change or remove one item of a print layout by its id (list_layout_items shows the ids): move it (x_mm, y_mm), resize it (width_mm, height_mm), rotate it (rotation in degrees), switch its frame on or off (frame), or remove it (remove=true). Give only what should change.

Parameter	Type	Required	Description
layout_name	string	yes
item_id	string	yes
x_mm	number	no
y_mm	number	no
width_mm	number	no
height_mm	number	no
rotation	number	no
frame	boolean	no
remove	boolean	no

export_layout

Export an existing print layout to a file: .pdf, .png, .jpg, .tif (image) or .svg (vector). dpi applies to PDF and images (default 150). Replacing an existing file needs confirmation. create_print_layout can export while it builds; this exports a layout that already exists. The result lists any RESTRICTED or SENSITIVE layer the map draws and any missing title, legend, scale bar or north arrow in export_warnings: tell the user. A map that draws a RESTRICTED or SENSITIVE layer waits for the user's confirmation before it is written. purpose='publication' is for a file that will be shared outside the team: it is refused while the layout lacks a mandatory element or draws a protected layer, unless the user gives a reason (ask them; pass it as override_reason) and confirms.

Parameter	Type	Required	Description
layout_name	string	yes
output_path	string	yes
dpi	integer	no
preset	string	no	export purpose instead of a dpi number: 'draft' (96), 'web' (150) or 'print' (300). An explicit dpi wins.
output_format	string	no	only when output_path is a FOLDER: pdf (default), png, jpg, tif or svg; the file is then named _.
world_file	boolean	no	image exports: also write a world file (.pgw, .jgw, .tfw) so GIS software can place the picture
geopdf	boolean	no	pdf exports: write a georeferenced PDF (needs the GDAL PDF driver)
purpose	string	no	'publication' only when the user says the file will be shared outside the team; omit for drafts
override_reason	string	no	with purpose='publication': the USER's stated reason for exporting despite problems. Never invent one; ask.

load_layout_template

Create a new print layout from a template file (.qpt) made by save_layout_template or QGIS. The new layout gets new_layout_name, which must not be taken. A template that contains an HTML frame is refused (it would run web content).

Parameter	Type	Required	Description
template_path	string	yes
new_layout_name	string	yes

save_layout_template

Save a print layout as a reusable template file (.qpt) that load_layout_template can turn into a new layout later, in this or another project. Replacing an existing file needs confirmation.

Parameter	Type	Required	Description
layout_name	string	yes
output_path	string	yes	Ends in .qpt

set_layout_map

Set what a print layout's map shows: the scale (scale = the denominator, 250000 for 1:250,000), the extent (extent_layer = zoom to a layer, or bbox = [min_lon, min_lat, max_lon, max_lat] in degrees), the rotation in degrees, lock_layers=true to freeze the layers the map shows now so later changes in the project do not alter the layout, or map_theme to follow a saved map theme. Works on MAP_MAIN unless map_item_id names another map. If both an extent and a scale are given, the extent is set first and the scale applied around its centre.

Parameter	Type	Required	Description
layout_name	string	yes
map_item_id	string	no
scale	number	no
rotation	number	no
extent_layer	string	no
bbox	array[number]	no
lock_layers	boolean	no
map_theme	string	no

set_layout_page

Change a print layout's page: size (A0 to A5, Letter, Legal, Tabloid), orientation (landscape or portrait) and the number of pages (1 to 20; new pages copy the size). Items already on the page keep their positions: move them with edit_layout_item if the new size needs it.

Parameter	Type	Required	Description
layout_name	string	yes
size	string	no
orientation	string	no
pages	integer	no

line_edit_tools

offset_curve

Make a parallel copy of every line of a line layer at distance (layer units; positive to the left of the line's direction, negative to the right) as a NEW layer; the input is not changed. join is round (default), miter or bevel. Attributes are copied. Lines that cannot be offset by that distance (for example a tight bend inwards) are counted in the reply.

Parameter	Type	Required	Description
layer_name	string	yes	A line layer.
distance	number	yes	Offset distance in the layer's units; negative = the other side.
join	string	no	Corner style (default round).
segments	integer	no	Segments per quarter circle for round joins, 1 to 64 (default 8).
miter_limit	number	no	Miter limit, 1 or more (default 2).
output_name	string	no	Name of the new layer (default _offset).

reshape_geometry

Reshape one feature of a line or polygon layer with a line drawn across it: line_wkt (a LINESTRING in the layer's CRS) cuts a new edge where it enters and leaves the feature, as QGIS's Reshape tool does. A line that does not cross the feature changes nothing and the reply says so. Changes geometry: a preview is shown for confirmation first, the edit is one undoable step (undo_manual_edit), and a result that would make a valid geometry invalid is refused.

Parameter	Type	Required	Description
layer_name	string	yes	A line or polygon layer.
feature_id	integer	yes	The feature's id (the QGIS feature id).
line_wkt	string	yes	The reshaping line as WKT in the layer's CRS, for example LINESTRING(-1 5, 5 7, 11 5).

reverse_line

Reverse the direction of the lines of a line layer (the first vertex becomes the last): all features, or only feature_ids. Use it when a one-way street, a river or a pipeline points the wrong way. Changes geometry: a preview with the number of features is shown for confirmation first, and the edit is one undoable step (undo_manual_edit).

Parameter	Type	Required	Description
layer_name	string	yes	A line layer.
feature_ids	array[integer]	no	Only these features (default: all).

trim_extend_lines

Close small gaps and overshoots between lines of a line layer: the two ends of every line move onto the nearest point of ANOTHER line when that point is within tolerance (layer units): a line that stops short is extended to it, a line that overshoots is trimmed back to where they cross. Only line ends move; no vertex is added or removed. Changes geometry: a preview with the number of ends that would move is shown for confirmation first, and the edit is one undoable step (undo_manual_edit).

Parameter	Type	Required	Description
layer_name	string	yes	A line layer.
tolerance	number	yes	The largest move of one end, in the layer's units (degrees on a geographic layer).

management_zones_tool

create_zoning_map

Divide a field or area into 2 to 8 zones of similar values (3 to 5 is usual for management zones) from one or more index rasters already in the project, for example NDVI, NDRE or any single-band raster: seeded k-means on the standardised bands, an optional smoothing pass, and merging of patches smaller than min_zone_area_ha into the neighbouring zone with the nearest mean. rasters is a list of 1 to 5 layer names (or 'layer name@band'). Zone 1 is the lowest mean of the first raster. Adds a polygon layer with one feature per zone and the mean of each raster in its legend label. The zones describe differences in the index values only: this tool gives NO yield forecast and NO fertiliser or input-rate recommendation. The rasters must share one pixel grid (or pass align_to_first); the raster must be at most 4 million cells (clip first).

Parameter	Type	Required	Description
rasters	array[string]	yes	1 to 5 raster layers to cluster on (names or 'name@band').
n_zones	integer	no	Number of zones, 2 to 8 (default 3).
min_zone_area_ha	number	no	Patches smaller than this are merged into a neighbouring zone (default: 1 percent of the valid area; 0 keeps every patch).
smooth	boolean	no	Run one 3 x 3 majority pass first to remove isolated cells (default false).
seed	integer	no	Random seed for the clustering (default 0); the same seed gives the same zones.
output_name	string	no	Name of the polygon layer (default management_zones).
align_to_first	boolean	no	If the rasters are not on one pixel grid, warp the others onto the first raster's grid (its CRS, extent and cell size) instead of refusing. The result says which raster was the reference and the resampling used. Default false: refuse.
resampling	string	no	With align_to_first: 'bilinear' (default, for continuous values such as reflectance), 'nearest' (for classes or counts) or 'cubic'.

map_view_tools

assign_layer_crs

Tell QGIS what CRS a layer's coordinates are ALREADY in ('Assign projection'). This does NOT move or reproject the data: choosing the wrong CRS places the layer in the wrong location. Use only when the layer's CRS is missing or known to be wrong. A preview is shown for confirmation first.

Parameter	Type	Required	Description
layer_name	string	yes
crs	string	yes

create_bookmark

Save a spatial bookmark in the project: of a layer's extent (layer_name), of an explicit extent [xmin, ymin, xmax, ymax] in crs, or of the current map view when neither is given.

Parameter	Type	Required	Description
name	string	yes
layer_name	string	no
extent	array[number]	no
crs	string	no

create_layer_group

Create a layer group in the layer tree (optionally inside another group) and optionally move layers into it.

Parameter	Type	Required	Description
group_name	string	yes
layer_names	array[string]	no
parent_group	string	no

go_to_bookmark

Zoom the map to a saved spatial bookmark by name.

Parameter	Type	Required	Description
name	string	yes

list_bookmarks

List the spatial bookmarks saved in the project. Read-only.

No parameters.

measure_distance

Measure on the ellipsoid along a path of points [[x, y], ...] given in crs (default EPSG:4326): total length in metres and kilometres, and for exactly two points the bearing in degrees. With close_polygon=true the points are a polygon and its area in square metres and hectares is returned too.

Parameter	Type	Required	Description
points	array[array]	yes
crs	string	no
close_polygon	boolean	no

move_layers_to_group

Move existing layers into an existing layer group.

Parameter	Type	Required	Description
group_name	string	yes
layer_names	array[string]	yes

set_group_options

Show or hide a whole layer group, collapse or expand it, and/or make its layers mutually exclusive (only one visible at a time).

Parameter	Type	Required	Description
group_name	string	yes
visible	boolean	no
expanded	boolean	no
mutually_exclusive	boolean	no

set_map_view

Move the map canvas: set the scale (denominator, e.g. 25000 for 1:25 000), zoom to an extent [xmin, ymin, xmax, ymax] in crs (default EPSG:4326), centre on a point [x, y] in crs, and/or rotate the map in degrees. Several can be combined.

Parameter	Type	Required	Description
scale	string	no
extent	array[number]	no
center	array[number]	no
crs	string	no
rotation	number	no

set_project_crs

Set the project (map) CRS, for example EPSG:3857. Layers are reprojected on the fly for display; no layer data is changed.

Parameter	Type	Required	Description
crs	string	yes

set_project_properties

Set the project title and/or project variables (a {name: value} object usable as @name in expressions).

Parameter	Type	Required	Description
title	string	no
variables	object	no

mcda_tools

calculate_mcda_ranking

Rank areas (or any features) on several weighted criteria and test how much the ranking depends on the weights. For each criterion give the field, a weight and which end gets priority: direction 'higher' (a high value means higher priority, e.g. people in need) or 'lower' (a low value means higher priority, e.g. water coverage). Values are min-max scaled to 0-1, scores are the weighted sum, ranks are 1 = top priority. It then re-ranks many times with the weights randomly perturbed (default +/-20%) and returns each unit's best and worst rank and, with top_k, the share of trials it stayed in the top k -- so say which priorities are robust and which only come from the chosen weights. Units missing any criterion are excluded and listed, never imputed. The weights are the user's judgement: ask for them rather than inventing them, and report them with the ranking. Optionally writes score and rank to the layer (needs confirmation). The sensitivity check covers the weights only, not data errors or the choice of criteria.

Parameter	Type	Required	Description
layer_name	string	yes	Vector layer with the units to rank (e.g. admin polygons).
criteria	array[object]	yes	At least two criteria.
unit_name_field	string	no	Optional field used to label units in the results.
top_k	integer	no	Report, per unit, the share of weight-perturbation trials in which it stays in the top k.
perturbation	number	no	Relative weight change tested, 0 to 0.9. Default 0.2 (+/-20%).
trials	integer	no	Number of perturbation trials, default 500, maximum 5000.
seed	integer	no	Random seed for the perturbation. Omit for a generated one (returned).
output_prefix	string	no	Optional: write _score, _rank, _rank_min, _rank_max to the layer.

model_tool

run_processing_model

Run a model made in QGIS's graphical modeler (a .model3 file in the project folder, so save the project first). It is run ONLY if every step is an approved algorithm: a model that contains a Python script, another model, an unapproved algorithm, one that changes your own layers, or an expression that calls a denied function is REFUSED and the reply names the step and the algorithm. inputs gives the model's inputs ({input name: layer name or value}); outputs always become temporary new layers in the project, and a model that writes a folder or file is refused. The run keeps the window painting but cannot be stopped with Stop.

Parameter	Type	Required	Description
model_file	string	yes	Name of the .model3 file in the project folder (or a path inside it).
inputs	object	no	{input name: layer name or plain value} for the model's inputs.
output_name	string	no	Name for the result layer(s) (default: the model's name).

new_layer_tools

add_3d_tiles_layer

Add a 3D Tiles tileset (a tileset.json, local or https) as a tiled scene layer. Only https URLs are accepted.

Parameter	Type	Required	Description
source	string	yes
layer_name	string	no

add_point_cloud_layer

Add a point cloud (.las, .laz, .copc.laz, or an EPT dataset's ept.json) from a local file as a layer. Read-only: the file is not changed.

Parameter	Type	Required	Description
file_path	string	yes
layer_name	string	no

add_vector_tile_layer

Add a vector tile layer: an https XYZ service URL containing {z}/{x}/{y}, or a local .mbtiles / .vtpk file. Only https URLs are accepted.

Parameter	Type	Required	Description
source	string	yes
layer_name	string	no
min_zoom	integer	no
max_zoom	integer	no

parts_edit_tool

edit_parts_and_rings

Add or delete a part, or cut, fill or delete a hole (ring), in one feature of a line or polygon layer. action 'add_ring' cuts a hole given as geometry_wkt (a POLYGON inside the feature); 'fill_ring' fills the hole that contains the point x, y; 'delete_ring' deletes hole number ring_index (1, 2, ...; part_index chooses the part, default 0); 'add_part' adds geometry_wkt (a POLYGON, or a LINESTRING on a line layer) as a new part and needs a multi-part layer; 'delete_part' removes part number part_index (not the last part). Coordinates are in the layer's CRS. Changes geometry: a preview is shown for confirmation first, the edit is one undoable step (undo_manual_edit), and a change that would make a valid geometry invalid is refused.

Parameter	Type	Required	Description
layer_name	string	yes	A line or polygon layer.
feature_id	integer	yes	The feature's id (the QGIS feature id).
action	string	yes	add_part, add_ring, fill_ring, delete_part or delete_ring.
geometry_wkt	string	no	add_part / add_ring: the shape as WKT in the layer's CRS, for example POLYGON((3 3,3 7,7 7,7 3,3 3)).
part_index	integer	no	delete_part: the part; delete_ring / fill_ring: the part holding the hole (default 0 / any).
ring_index	integer	no	delete_ring: the hole number, 1 or more (0 is the outer boundary).
x	number	no	fill_ring: x of a point inside the hole (layer CRS).
y	number	no	fill_ring: y of a point inside the hole (layer CRS).

pcode_validation_tools

check_pcode_hierarchy

Check that each feature's child P-code (e.g. admin2_pcode) is prefixed by its own parent P-code (e.g. admin1_pcode) on the same row -- the real OCHA/HDX COD-AB convention (admin2 'YE1201' under admin1 'YE12'). This is a string-prefix check on two sibling attributes, NOT a spatial containment check -- it does not verify the admin2 polygon actually sits inside the admin1 polygon's geometry, only that the codes are structurally consistent. Auto-detects both fields from common P-code field names if not given.

Parameter	Type	Required	Description
layer_name	string	yes
child_pcode_field	string	no	Optional. Defaults to an admin2 P-code alias.
parent_pcode_field	string	no	Optional. Defaults to an admin1 P-code alias.

check_pcode_uniqueness

Check that every P-code value in a layer is unique across its features -- flags duplicate admin-unit codes that would silently corrupt a P-code join in calculate_severity_index or calculate_presence_gap. Tries the admin2 P-code field aliases (admin2_pcode/adm2_pcode/ADM2_PCODE) automatically if pcode_field isn't given.

Parameter	Type	Required	Description
layer_name	string	yes
pcode_field	string	no	Optional. Field to check; auto-detected from common P-code field names if omitted.

processing_allowlist_tools

find_processing_algorithm

Search the approved QGIS Processing algorithms by a few words (for example 'densify', 'polygons to lines', 'smooth') and get each match's id, name and exact parameter names with types and defaults, ready for run_allowlisted_processing_algorithm. Read-only. With algorithm_id set, returns just that algorithm's parameters.

Parameter	Type	Required	Description
query	string	no
algorithm_id	string	no
family	string	no	Browse one family instead of searching: geometry, table, analysis, expression, raster, mixed, grass or mesh. Lists id, name and what each is for.

run_allowlisted_processing_algorithm

Runs one QGIS Processing algorithm from a fixed, pre-approved list -- prefer this over execute_pyqgis_script when the task is achievable via a single Processing algorithm that isn't already covered by a dedicated tool. It calls only the named, pre-approved algorithm with the given parameters and never accepts a FORMULA or EXTRA (raw backend arguments) parameter; algorithms that evaluate free-form expressions as code (such as the GDAL raster calculator) are not on the list. Only algorithms already used elsewhere in this codebase are allowed -- an unlisted algorithm id is rejected outright, not run. Output is always kept in-memory as a new project layer (auto-named), never written to a file path -- use a dedicated export tool (export_layer, export_to_csv) afterward if a file is actually needed. Don't specify the output (destination) parameters yourself -- they are set automatically and any value you give is ignored. An unknown parameter name is rejected before the algorithm runs, with the list of valid names; an algorithm with several outputs returns each as its own layer (additional_outputs); native:selectbylocation changes the selection of the existing layer instead of creating one. Any string parameter value matching a currently-loaded layer's name is automatically resolved to that layer; every other value is passed through as-is.

Parameter	Type	Required	Description
alg_id	string	yes	Processing algorithm id, e.g. 'native:buffer'. Must be an approved id; call find_processing_algorithm to search the approved list by words and see each algorithm's exact parameter names.
params	object	yes	Flat dict of algorithm parameters, e.g. {"INPUT": "my_layer", "DISTANCE": 500}. String values matching a loaded layer's name are resolved to that layer automatically.
new_layer_name	string	no	Name to give the algorithm's output layer once added to the project. Defaults to '<alg_id>_output' if omitted -- and an omitted name is treated as a signal that this output is an internal/scratch step (e.g. a reprojection before a buffer), so it's added to the project hidden (unchecked in the layer tree) rather than cluttering the visible map. Give this an explicit name whenever the output IS the deliverable you want the user to see.

project_ops_tools

add_text_annotation

Put a text note on the map at x, y (in crs, default EPSG:4326). It is kept in the project's annotation layer.

Parameter	Type	Required	Description
text	string	yes
x	number	yes
y	number	yes
crs	string	no

create_relation

Create a 1-N relation between two layers: parent_layer.parent_field is referenced by child_layer.child_field (for example districts.pcode and schools.district_pcode). The relation is stored in the project.

Parameter	Type	Required	Description
name	string	yes
parent_layer	string	yes
parent_field	string	yes
child_layer	string	yes
child_field	string	yes

get_layer_metadata

Read a layer's metadata: title, abstract, licenses, rights, keywords and contacts.

Parameter	Type	Required	Description
layer_name	string	yes

list_relations

List the project's relations between layers.

No parameters.

remove_annotations

Remove all text annotations from the map. Destructive: a preview with the count is shown first.

No parameters.

rename_layer_group

Rename a layer group in the layer tree.

Parameter	Type	Required	Description
group_name	string	yes
new_name	string	yes

set_layer_metadata

Set a layer's metadata: title, abstract, license, rights, keywords (a list of words) and one contact (name, organization, email). Fields you leave out are kept. The metadata is stored in the project (save the project to keep it).

Parameter	Type	Required	Description
layer_name	string	yes
title	string	no
abstract	string	no
license	string	no
rights	string	no
keywords	array[string]	no
contact_name	string	no
contact_organization	string	no
contact_email	string	no

set_layer_temporal

Make a vector layer time-aware: give the date or date-time field (start_field) and optionally an end_field for features that last a period. Set clear=true to switch it off. The fields must be of date or date-time type.

Parameter	Type	Required	Description
layer_name	string	yes
start_field	string	no
end_field	string	no
clear	boolean	no

set_project_time_range

Set the project's temporal range (the period the temporal controller covers). start and end are dates such as 2026-03-01 or 2026-03-01T12:00:00.

Parameter	Type	Required	Description
start	string	yes
end	string	yes

set_snapping_options

Set the project's snapping: enabled, snap_type (vertex, segment, vertex and segment, centroid, middle of segment, line endpoint, area), tolerance, units (pixels or project units), mode (all layers, active layer, advanced) and topological editing. Options you leave out are kept.

Parameter	Type	Required	Description
enabled	boolean	no
snap_type	string	no
tolerance	number	no
units	string	no
mode	string	no
topological_editing	boolean	no

zoom_history

Zoom the map canvas to the previous or the next extent in its history (like the Zoom Last / Zoom Next buttons). direction: previous or next.

Parameter	Type	Required	Description
direction	string	yes	previous or next

project_settings_tools

define_custom_crs

Check a custom coordinate system given as a PROJ string (+proj=tmerc +lat_0=0 ...) or a WKT, and optionally make it the project CRS. QGIS validates it first; an invalid definition is refused. It is used for THIS project only: it is not added to the shared custom-CRS database of the user's QGIS. The reply gives its units and whether it is geographic.

Parameter	Type	Required	Description
name	string	yes	A label for the reply (a custom CRS has no stored name here).
definition	string	yes	A PROJ string starting +proj= or a WKT starting PROJCRS[ / GEOGCRS[.
use_as_project_crs	boolean	no	Also make it the project's CRS (default false).

set_canvas_decoration

Switch a map-canvas decoration on or off and place it: kind title, copyright, scale_bar, north_arrow or grid; placement bottom_left, top_left, top_right, bottom_right, top_center or bottom_center; text for the title and the copyright. These are saved as project properties which QGIS reads when the project is opened, so save the project and reopen it (or use the View > Decorations menu) to see the change. Hand-verified only: the canvas is not available to automatic tests. No layer data changes.

Parameter	Type	Required	Description
kind	string	yes	title, copyright, scale_bar, north_arrow or grid.
enabled	boolean	no	true to show it, false to hide it.
placement	string	no	Where it sits on the canvas.
text	string	no	The words for the title or the copyright (those two kinds only).

set_project_measurement

Set the project's ellipsoid (for example WGS84, EPSG:7030, or NONE for flat planimetric measurement), distance units and area units: what the measuring tools and the layout use. distance_units: meters, kilometers, feet, yards, miles, nautical miles or degrees. area_units: square meters, square kilometers, hectares, acres, square feet, square yards, square miles or square degrees. The values are read back. Stored with the project; no layer data changes.

Parameter	Type	Required	Description
ellipsoid	string	no	An ellipsoid name or code (WGS84, EPSG:7030, ...) or NONE.
distance_units	string	no	meters, kilometers, feet, yards, miles, nautical miles or degrees.
area_units	string	no	square meters, square kilometers, hectares, acres, square feet, square yards, square miles or square degrees.

set_project_transform_context

Choose the datum transformation the PROJECT uses between two coordinate systems, or list the choices. Without operation_id it only LISTS the coordinate operations PROJ offers between source_crs and dest_crs (name, accuracy in metres, whether its grid files are installed, and which one the project uses now); the choice can move points by metres, for example between EPSG:4326 and a local datum. With operation_id (an id from that listing) a preview is shown for confirmation first, then the project uses it for every layer. Only an operation QGIS lists for that pair is accepted. Stored with the project.

Parameter	Type	Required	Description
source_crs	string	yes	The source CRS, for example EPSG:4326.
dest_crs	string	yes	The destination CRS, for example EPSG:32636.
operation_id	string	no	An id from the listing (an authority code like EPSG:1150, or the operation's PROJ text); leave out to list.

project_tidy_tools

tidy_project_layers

Find and repair clutter left in a project by older Cartogen AI builds: (1) the same layer loaded more than once (identical name and data) -- the extra copies are HIDDEN, never deleted; (2) a WorldPop population raster drawn opaque black instead of with the population colour ramp -- restyled; (3) temporary scratch layers (such as origin points) that are lost when the project is closed -- saved into the project's results GeoPackage (the project must already be saved). Call with apply=false (default) to only list what it found, then apply=true to repair. It does not delete layers; use remove_layer, which asks for confirmation, to delete a hidden duplicate.

Parameter	Type	Required	Description
apply	boolean	no	false (default): report only. true: ask the user to confirm, then hide duplicate copies, restyle population rasters and save scratch layers.

provenance_tools

get_provenance_record

Read a layer's machine-readable provenance record without writing anything to disk: the QGIS version, its full tool-execution lineage (what tool chain produced/modified it, see get_layer_lineage-tracked history), where fetched data came from (sources), the automatic result checks stored after each analysis (result_checks), and the manual lifecycle gate (qa_status: status/history/checks, empty unless set with the status tools; see get_dataset_status). The last two are different records: an empty qa_status does not mean no checks ran. Use this to inspect provenance in-conversation; use write_provenance_sidecar instead to save it as a real JSON file.

Parameter	Type	Required	Description
layer_name	string	yes

write_provenance_sidecar

Write a layer's machine-readable provenance record (QGIS version, tool-execution lineage, QA-gate status/history/checks) to a real JSON sidecar file -- named '<source_file>.provenance.json' beside the layer's own on-disk source when one can be resolved, or an explicit output_path when supplied. Falls back to a Desktop file named after the layer (with a warning in the result) for a layer with no real on-disk source, e.g. a scratch/memory layer.

Parameter	Type	Required	Description
layer_name	string	yes
output_path	string	no	Optional explicit file path for the sidecar. Omit to derive one from the layer's own source, or fall back to Desktop.

write_workflow_report

Write a verified workflow report (Markdown) for one or more result layers, built only from what the plugin recorded: result checks (failed ones first), data sources with licence/date/coverage, the steps that made the layers in order with their parameters (a rerun recipe), and the assumptions and limitations, including every gap (layers never checked, origin unknown). Pass the layer(s) that hold the final answer; upstream layers are followed through lineage. Use it for 'document how this result was made', 'method note' or 'show the evidence for this map'. It does not prove a rerun gives the same numbers.

Parameter	Type	Required	Description
title	string	yes
layer_names	array[string]	yes	The result layer(s) to document.
assumptions	array[string]	no	Optional assumptions or limits the analyst states (one sentence each); added to the report as given.
output_path	string	no	Optional file path (.md). Omit for Desktop.

public_health_look_tool

apply_public_health_look

Draw the public-health look on a layer. look 'rate': a single-hue (blue) quantile map of a rate field (default field value_shown, from calculate_health_rates), with areas whose figure is suppressed for small numbers drawn as a grey hatch labelled 'Suppressed (n < 5)'; the legend title is 'Rate per 100,000; suppressed where n < 5'. look 'cluster': a black line with a narrower white line on top and no fill, never red, for the circles from detect_spatial_clusters. look 'lisa': the Local Moran classes (field lisa_class). look 'hotspot': the Getis-Ord hot and cold spot classes (field gi_class). No class is red or green. This only changes how the layer is drawn; it never changes data.

Parameter	Type	Required	Description
layer_name	string	yes
look	string	yes	rate, cluster, lisa or hotspot.
field	string	no	The field to draw. Defaults: value_shown for rate, lisa_class for lisa, gi_class for hotspot. Not used for cluster.
classes	integer	no	For look 'rate': number of quantile classes, 2 to 5 (default 5).
per	number	no	For look 'rate': the rate denominator named in the legend (default 100000).
min_cases	integer	no	For look 'rate': the small-number threshold named in the legend (default 5); use the same value as calculate_health_rates.

qa_checklist_tools

generate_map_product_qa_checklist

Assembles a QA checklist for one map product -- a layer, optionally paired with a print layout -- covering data readiness, cartographic completeness, disclosure/sensitivity, and export/provenance. Reads from what's already tracked (dataset_status, layout item ids, provenance) rather than re-deriving or guessing any of it. Point 26 of docs/QGIS_PRODUCTION_ARCHITECTURE_REVIEW_2026-09-04.md -- distinct from this plugin's own docs/RELEASE_SMOKE_TEST.md, which verifies the plugin's tools work in a live QGIS session, not an individual map product's readiness.

Parameter	Type	Required	Description
layer_name	string	yes
layout_name	string	no	Optional print layout built for this product (from create_print_layout) -- checked for the mandatory MAP_MAIN/TITLE/LEGEND/SCALEBAR/NORTH_ARROW elements. Omit to skip the cartography section.
output_path	string	no	Optional exported file path (e.g. create_print_layout's own output_path) to verify it actually exists on disk with real content. Omit to skip the export-integrity section.

raster_calculator_tool

raster_calculator

Raster calculator (map algebra): computes a new raster from one or more raster layers in the project with an expression, using QGIS's own raster calculator. Write each layer as "layer name@band" in double quotes (band numbers start at 1), for example "dem@1" > 100 (a 0/1 mask of cells above 100), ("nir@1" - "red@1") / ("nir@1" + "red@1"), or "slope@1" < 15 AND "landcover@1" = 2. Allowed: numbers, + - * / ^, comparisons (< > = != <= >=), AND, OR, brackets and the functions sqrt sin cos tan asin acos atan ln log10 abs min max. Anything else is refused before QGIS runs. The first layer named sets the output extent and cell size by default. Adds a NEW raster layer (default name 'raster_calc'); no input layer is changed. Cells where any input is NoData stay NoData.

Parameter	Type	Required	Description
expression	string	yes	Raster expression, layers written as "layer name@band".
new_layer_name	string	no	Name for the result layer (default 'raster_calc').

raster_change_tool

calculate_change_matrix

From-to change matrix between two CLASS rasters (for example land cover in two years): how many cells, hectares and percent moved from each class to each other class, plus per-class persistence, loss, gain and net change. 'What changed between these two land-cover rasters', 'how much forest was lost to cropland'. Give raster_a (before) and raster_b (after), and optionally classes naming the values ({"10": "Tree cover", "40": "Cropland"}). Class values must be whole numbers (a continuous raster must be reclassified first; at most 50 classes). Cells that are NoData in either raster are left out. Hectares come from the CRS: exact for a projected raster, approximate (sphere, row by row) for a geographic one. Adds two table layers (the transitions and a per-class summary) and a bar chart of the net change per class. The rasters must share one pixel grid (or pass align_to_first, which resamples with nearest neighbour).

Parameter	Type	Required	Description
raster_a	string	yes	The earlier class raster (layer name, or 'layer name@band').
raster_b	string	yes	The later class raster.
classes	object	no	Optional names: {value: name}, for example {"1": "Forest"}.
output_name	string	no	Name of the transitions table (default change_matrix); the summary is _summary.
chart	boolean	no	Also make the bar chart (default true).
align_to_first	boolean	no	If the rasters are not on one grid, warp raster_b onto raster_a's grid with nearest-neighbour resampling.
resampling	string	no	With align_to_first: 'nearest' (default, right for classes), 'bilinear' or 'cubic' (they blend classes; not advised).

raster_inspect_tools

build_pyramids

Build pyramids (overviews) for a raster layer so a big raster draws fast when zoomed out: smaller copies are written to a sidecar .ovr file NEXT TO the raster, which itself is never rewritten. levels is a list such as [2, 4, 8] (default: halving while the smaller side stays at least 256 cells; a raster under 512 cells needs none); method is average (default, for continuous data), nearest, gauss, cubic or mode (for classified rasters). If an .ovr file already exists a preview asks before it is replaced. The number of levels is read back.

Parameter	Type	Required	Description
layer_name	string	yes	The raster layer (a local file).
levels	array[integer]	no	Overview factors, increasing, each 2 or more (default: chosen from the raster's size).
method	string	no	Resampling: average (default), nearest, gauss, cubic or mode.

get_raster_value

Read the value of a raster layer at a coordinate: every band (or only band) and the column and row of the cell it falls in. x and y are in crs (default: the project CRS). A point outside the raster is reported, and a NoData cell comes back as null. Read-only. To look at vector layers and rasters together at a point use identify_at_point.

Parameter	Type	Required	Description
layer_name	string	yes	The raster layer.
x	number	yes	X (longitude or easting) in crs.
y	number	yes	Y (latitude or northing) in crs.
band	integer	no	One band number, 1-based (default: all bands).
crs	string	no	The CRS of x and y, for example EPSG:4326 (default: the project CRS).

raster_attribute_table

Read the attribute table of a classified raster (value, class name, colour, pixel count and so on), the table QGIS shows under Layer Properties > Attribute Table. Many rasters have none and the reply says so. At most 200 rows are returned and the reply says when there are more. Read-only.

Parameter	Type	Required	Description
layer_name	string	yes	The raster layer (a file).
band	integer	no	The band, 1-based (default 1).

raster_series_tool

raster_time_series_stats

Per-pixel statistics over a time series of rasters already in the project: 'mean' (average of the valid values), 'trend' (straight-line slope in value units per YEAR, for example NDVI change per year; needs times, one per raster, and at least 3 rasters) or 'anomaly' (z-score of one raster against the mean and standard deviation of the baseline rasters: how unusual is this month compared with the other years). rasters is an ordered list of layer names (or 'layer name@band'). For a trend give times as years, dates ('2021-06-15') or numbers of years. For an anomaly the target raster (default: the last) is compared with the baseline rasters (default: all the others, at least 3). Cells with too few valid observations are NoData. The rasters must share one pixel grid (or pass align_to_first). It reports the slope, not its statistical significance. Adds a new raster layer.

Parameter	Type	Required	Description
rasters	array[string]	yes	Raster layer names in time order (max 60).
statistic	string	no	mean, trend or anomaly (default mean).
times	array'string', 'number'	no	Trend only: the time of each raster, in the same order: a year, a date such as 2021-06-15, or a number of years.
target	string	no	Anomaly only: the raster to score (default: the last one in rasters).
baseline	array[string]	no	Anomaly only: the baseline rasters (default: all the others).
min_observations	integer	no	Fewest valid values a cell needs (defaults: 1 for mean, 3 for trend and for the baseline).
output_name	string	no	Name of the new layer (default ts_mean, ts_trend or ts_anomaly).
align_to_first	boolean	no	If the rasters are not on one pixel grid, warp the others onto the first raster's grid (its CRS, extent and cell size) instead of refusing. The result says which raster was the reference and the resampling used. Default false: refuse.
resampling	string	no	With align_to_first: 'bilinear' (default, for continuous values such as reflectance), 'nearest' (for classes or counts) or 'cubic'.

renderer_tool

set_renderer

Change HOW a layer is drawn with a special renderer: merged_features (touching lines or polygons drawn as one shape, keeping the current look), inverted_polygons (paint everything OUTSIDE the polygons, keeping the current look), embedded (use the symbol stored in each feature, as in DXF or KML data), no_symbols (draw nothing, so only labels or the selection show), 2_5d (pseudo-3D polygons; options roof_color, wall_color, shadow) or single_symbol (back to one plain symbol). The data is never touched, and the previous style is saved in the layer's style manager as 'before ' so it can be restored from the layer's Styles menu. The new renderer type is read back in the reply. Stored with the project.

Parameter	Type	Required	Description
layer_name	string	yes	The vector layer.
kind	string	yes	merged_features, inverted_polygons, embedded, no_symbols, 2_5d or single_symbol.
options	object	no	2_5d only: roof_color, wall_color (a name or #rrggbb), shadow (true / false).

representation_tools

analyze_layer_for_visualization

Analyze a layer's geometry, feature count, spatial density, overlap ratio, and attribute semantics (rates vs raw counts, nominals, temporal) to inform cartographic representation decisions.

Parameter	Type	Required	Description
layer_name	string	yes	Name of the layer in the QGIS project to analyze.

apply_recommended_representation

Apply a recommended representation candidate (e.g. 'point_cluster', 'point_displacement', 'point_heatmap', 'polygon_choropleth_rate', 'polygon_proportional_centroid') to a layer.

Parameter	Type	Required	Description
layer_name	string	yes
representation_id	string	yes	Candidate representation id to apply, e.g. 'point_cluster', 'point_heatmap', 'polygon_choropleth_rate'.
target_field	string	no	Optional attribute field if the representation requires one.

explain_current_representation

Inspect a layer's active renderer and explain whether it fits the data distribution and geometry, flagging potential cartographic issues (such as raw count choropleth distortion or dense point crowding).

Parameter	Type	Required	Description
layer_name	string	yes

recommend_map_representation

Evaluate candidate map representations for a layer based on spatial density, geometry, and analytical question (e.g. 'Where are they concentrated', 'Which are largest', 'What category'). Returns scored candidates and interactive action options.

Parameter	Type	Required	Description
layer_name	string	yes	Name of the layer to evaluate.
user_intent	string	no	The analytical question or intent, e.g. 'show density', 'compare size', 'show status category'.
target_field	string	no	Optional attribute field to style or symbolize by.

sampling_tools

design_sampling_frame

Design a household/community survey sample (e.g. for a multi-sector needs assessment): works out how many units to survey in each stratum (admin unit, camp, host community...) for a chosen confidence level and margin of error, and draws the sample as a point layer with a recorded random seed. Draws from a layer of candidate units (households, buildings, settlements) when units_layer is given, otherwise as random points inside each stratum polygon (area-based, ignores where people live). The statistical assumptions are arguments and are echoed back: expected_proportion defaults to 0.5 (most conservative) and design_effect to 1.0, which is correct ONLY for simple random sampling -- for a cluster design the survey designer must supply the design effect, so ask rather than guess. It does not choose the survey design, and the result is only as good as the frame it is drawn from.

Parameter	Type	Required	Description
strata_layer	string	yes	Polygon layer of strata (admin units, camp / host-community areas).
stratum_field	string	no	Field naming each stratum. Omit to treat each polygon as its own stratum, named by feature id.
units_layer	string	no	Optional layer of candidate units to sample from (points, or polygons such as buildings -- their centroids are used).
population_attribute	string	no	Optional numeric field on the strata layer with the number of units (e.g. households) in the stratum. If omitted and units_layer is given, the stratum size is the number of candidate units inside it; otherwise no finite-population correction is applied.
confidence	number	no	Confidence level, e.g. 0.95 (default).
margin_of_error	number	no	Margin of error as a proportion, e.g. 0.05 (default) = +/-5 percentage points.
expected_proportion	number	no	Expected proportion of the indicator, default 0.5 (most conservative).
design_effect	number	no	Design effect, default 1.0 (simple random sampling only). Must be supplied by the survey designer for cluster designs.
nonresponse_rate	number	no	Expected non-response as a proportion, default 0.
seed	integer	no	Random seed. Omit to generate one; it is returned either way so the draw can be repeated.
output_layer_name	string	no	Name of the sample point layer. Default 'survey_sample'.
plan_only	boolean	no	true: only compute sample sizes per stratum, do not draw or create a layer.

schema_contract_tools

list_schema_contracts

List the machine-readable dataset schema contracts available to validate_schema (currently health_facilities and admin2 -- see validators/contracts/*.json). Each contract declares required fields (by acceptable name aliases, since real-world admin/pcode field names vary by source), expected field types, and optional controlled-vocabulary domains.

No parameters.

validate_schema

Check a vector layer's fields -- presence, type, and any controlled-vocabulary values -- against a named schema contract (see list_schema_contracts for available names). Field matching is case-insensitive and checks a contract's full alias list, not one fixed name, so e.g. 'ADM2_PCODE' from a COD-AB download and 'admin2_pcode' from a hand-built layer both satisfy the same required field. Returns missing_fields/type_mismatches/value_violations and an overall passed flag -- never blocks anything by itself, but feeds advance_dataset_status's VALIDATED -> ANALYSIS_READY gate when a contract_name is supplied there.

Parameter	Type	Required	Description
layer_name	string	yes
contract_name	string	yes	e.g. 'health_facilities' or 'admin2'. See list_schema_contracts.

sensitivity_tools

get_layer_sensitivity

Reads a layer's current sensitivity/disclosure classification, if any was set via set_layer_sensitivity. Returns level=null if never tagged -- not the same as PUBLIC, just unclassified.

Parameter	Type	Required	Description
layer_name	string	yes

set_layer_sensitivity

Tags a layer with a sensitivity/disclosure classification -- PUBLIC, INTERNAL, RESTRICTED, or SENSITIVE. Use for a layer containing individual beneficiary locations, protection incident details, or anything else that shouldn't be shared broadly. export_layer/export_to_csv check this and add an advisory warning (not a block -- the export still completes) when exporting a RESTRICTED/SENSITIVE layer. No automated classification exists -- only what's explicitly set here is tracked. When the cloud-provider data-protection gate is on, moving a RESTRICTED/SENSITIVE layer to PUBLIC/INTERNAL needs the user's confirmation in the UI -- do not try to work around that by re-tagging.

Parameter	Type	Required	Description
layer_name	string	yes
level	string	yes	PUBLIC, INTERNAL, RESTRICTED, or SENSITIVE.
reason	string	no	Optional short reason shown in the export warning, e.g. 'contains individual beneficiary GPS coordinates'.

spatial_stats_tool

calculate_spatial_autocorrelation

Test whether a numeric field is spatially clustered (similar values near each other), alternating (high next to low) or no different from a random arrangement: global Moran's I with a permutation p-value, and with write_local=true the Local Moran's I (LISA) per feature as a NEW layer with lisa_i, lisa_p and lisa_class (HH high among high, LL low among low, HL a high outlier among low, LH a low outlier among high, or 'not significant'). weights: 'queen' or 'rook' (polygon layers, from shared boundaries), 'knn' (k nearest, pass k) or 'distance' (a distance band in layer units, projected CRS only, pass distance). Needs a number on every feature (it refuses and says how many are missing). At most 5,000 features. The input layer is never changed. Evidence of a pattern, not of its cause; the local p-values are not corrected for testing every feature.

Parameter	Type	Required	Description
layer_name	string	yes
field	string	yes	A numeric field.
weights	string	no	queen (default), rook, knn or distance.
k	integer	no	For weights='knn': how many nearest neighbours each feature counts (for example 5).
distance	number	no	For weights='distance': the band in the layer's units (projected CRS).
permutations	integer	no	Shuffles for the p-value, 99 to 9999 (default 999).
seed	integer	no	Random seed (default 1); the same seed gives the same numbers.
write_local	boolean	no	Also add a new layer with the Local Moran result per feature (default false).
alpha	number	no	Significance level for the local classes (default 0.05).
output_name	string	no	Name of the local-result layer (default '_lisa').

spectral_index_tool

calculate_spectral_index

Calculate a spectral index raster from band layers: NDVI (vegetation greenness), NDWI and MNDWI (open water), NDRE (crop chlorophyll), NDMI (vegetation moisture), NBR (burn severity), SAVI (vegetation over bare soil, with a soil factor), EVI (dense canopy, reflectance 0 to 1) and BSI (bare soil). Give index and bands: a mapping from each band role to a raster layer name, or 'layer name@3' for band 3 of a multi-band layer. Roles per index -- NDVI: nir, red; NDWI: green, nir; MNDWI: green, swir1; NDRE: nir, rededge; NDMI: nir, swir1; NBR: nir, swir2; SAVI: nir, red; EVI: nir, red, blue; BSI: blue, red, nir, swir1. Nothing guesses which band is which: Sentinel-2 B8 is nir, B4 red, B3 green, B2 blue, B5 rededge, B11 swir1, B12 swir2; Landsat 8 band 5 is nir, 4 red, 3 green, 2 blue, 6 swir1, 7 swir2. The bands must share one pixel grid (or pass align_to_first). Cells where an input is NoData or the formula divides by zero are NoData, not 0. Adds a new single-band raster named after the index (or output_name); follow up with apply_raster_stretch for a readable ramp.

Parameter	Type	Required	Description
index	string	yes	Which index to compute.
bands	object	yes	Band role -> raster layer name (or 'layer name@band'). Example for SAVI: {"nir": "B8", "red": "B4"}.
output_name	string	no	Name of the new layer (default: the index name).
soil_factor	number	no	SAVI only: the soil brightness factor L, default 0.5 (0 gives NDVI, 1 for very sparse vegetation).
align_to_first	boolean	no	If the rasters are not on one pixel grid, warp the others onto the first raster's grid (its CRS, extent and cell size) instead of refusing. The result says which raster was the reference and the resampling used. Default false: refuse.
resampling	string	no	With align_to_first: 'bilinear' (default, for continuous values such as reflectance), 'nearest' (for classes or counts) or 'cubic'.

stac_load_tool

load_stac_assets (two-phase)

Download Sentinel-2 satellite band images (Earth Search, no key) for the user's AREA ONLY and add them to the project: only the part of each band image that covers the area is downloaded, so a few megabytes instead of a whole scene. Give the area as bbox (WGS84 min_lon, min_lat, max_lon, max_lat) or layer_name (that layer's extent), a date range, and the bands in assets (blue, green, red, nir, nir08, rededge1-3, swir16, swir22, coastal, nir09, scl; at most 6). max_cloud (percent, default 20) and limit (1 to 3 scenes, default 1, newest first). A preview lists the scenes, the bands and the estimated size first; nothing is downloaded until it is confirmed, and the confirmed call fetches exactly the scenes the preview named. Each file gets a provenance record and the Copernicus Sentinel licence notice. Landsat and the elevation model are not supported (they need AWS credentials). To only LIST scenes use search_stac_satellite_imagery.

Parameter	Type	Required	Description
bbox	array[number]	no	WGS84 [min_lon, min_lat, max_lon, max_lat]; or use layer_name.
layer_name	string	no	A project layer whose extent is the area.
start_date	string	yes	YYYY-MM-DD
end_date	string	yes	YYYY-MM-DD
assets	array[string]	yes	Band names such as red, nir, swir16 (1 to 6).
max_cloud	number	no	Largest cloud cover in percent (default 20).
limit	integer	no	Number of scenes, 1 to 3 (default 1).

survey_tools

aggregate_survey_indicator

Summarise survey records into one figure per area (admin unit, camp, ...): the weighted share of respondents answering yes (kind='proportion') or the weighted mean of a numeric answer (kind='mean'), each with a confidence interval. Groups with fewer than min_n respondents (default 30) are SUPPRESSED -- no estimate is returned -- because a figure from a handful of households is unreliable and can identify people in a small community; the real threshold is the organisation's data-protection policy, so ask for it if it matters. Uses the survey's own weights as given (weight_field); intervals use Kish's effective sample size and IGNORE clustering and stratification, so for a cluster survey supply design_effect or treat the intervals as too narrow. Records with a missing answer or an invalid weight are excluded and counted, never imputed. Optionally creates a table layer of the results that can be joined to admin polygons.

Parameter	Type	Required	Description
layer_name	string	yes	Layer or table of survey records (one row per respondent/household).
group_field	string	yes	Field naming the area/stratum each record belongs to.
indicator_field	string	yes	Field with the answer: yes/no-style for a proportion, numeric for a mean.
kind	string	no	'proportion' (default) or 'mean'.
positive_values	array[string]	no	For a proportion: the answers that count as 'yes' (e.g. ['No access'] to measure lack of access). Default: the usual 1/yes/true spellings.
weight_field	string	no	Optional numeric survey-weight field; omit for unweighted.
min_n	integer	no	Minimum respondents per group, default 30. Smaller groups are suppressed.
confidence	number	no	Confidence level of the intervals, default 0.95.
design_effect	number	no	Design effect from the survey design (>= 1); divides the effective sample size. Default 1 (no clustering adjustment).
output_table_name	string	no	Optional name for a results table layer.

symbology_extra_tools

apply_saved_symbol

Give a vector layer a symbol from your personal symbol library by name. The symbol kind must fit the layer (marker for points, line for lines, fill for polygons). A layer that uses categories or graduated colours is only switched to the single symbol after confirmation.

Parameter	Type	Required	Description
layer_name	string	yes
name	string	yes

list_saved_symbols

List the symbols in your personal QGIS symbol library (name and kind: marker, line or fill).

No parameters.

save_symbol_to_library

Save a vector layer's (single) symbol into your personal QGIS symbol library under a name, optionally with tags, so it can be reused on other layers and in other projects. An existing symbol with the same name is only replaced after confirmation.

Parameter	Type	Required	Description
layer_name	string	yes
name	string	yes
tags	array[string]	no

set_label_callout

Add or change callouts (lines from a label to its feature) and a text mask (a clear halo that hides what is behind the text) on a layer that already has simple labels (apply_labels). enabled switches callouts on or off; style is simple or manhattan; color and width_mm style the line; mask and mask_size_mm control the mask.

Parameter	Type	Required	Description
layer_name	string	yes
enabled	boolean	no
style	string	no	simple or manhattan
color	string	no
width_mm	number	no
mask	boolean	no
mask_size_mm	number	no

set_layer_diagram

Draw a pie or bar diagram on every feature of a vector layer from numeric fields (kind: pie, bar or histogram; fields: 1 to 8 numeric field names; size_mm; optional colors, one per field). clear=true removes the diagrams.

Parameter	Type	Required	Description
layer_name	string	yes
kind	string	no
fields	array[string]	no
size_mm	number	no
colors	array[string]	no
clear	boolean	no

set_point_marker

Use an SVG picture or a single font character as the marker of a POINT layer. kind=svg needs svg_path (a local .svg file, or a name from QGIS's own SVG library such as arrows/Arrow_01.svg; URLs are refused); kind=font needs font_family and character. size_mm and color are optional. The layer must use a single symbol.

Parameter	Type	Required	Description
layer_name	string	yes
kind	string	yes	svg or font
svg_path	string	no
font_family	string	no
character	string	no
size_mm	number	no
color	string	no

set_raster_relief

Draw a raster (for example a DEM) as a hillshade (style=hillshade; azimuth 0-360, altitude 0-90, z_factor) or as contour lines (style=contour; interval and optional index_interval, in the raster's units). band defaults to 1. This changes how the raster is DISPLAYED, not its data: it creates no layer and no file, so these contour lines cannot be selected, measured, labelled or exported. When the user wants contour lines as data ('draw / make / create contour lines of the DEM, every 100 m') use generate_contours; use this tool for 'render / style / show the DEM as contours or hillshade'. For a hillshade FILE use the hillshade analysis tool.

Parameter	Type	Required	Description
layer_name	string	yes
style	string	yes	hillshade or contour
azimuth	number	no
altitude	number	no
z_factor	number	no
interval	number	no
index_interval	number	no
band	integer	no

set_rule_based_labels

Label a vector layer with RULES instead of one style: each rule has a field to show, an optional filter (a QGIS expression such as "population" > 10000), a font size and colour, and optional scales (min_scale = zoomed-out limit as a denominator, max_scale = zoomed-in limit). Up to 20 rules. This replaces the layer's current labels. clear=true removes the layer's labels (no rules needed). To get the previous labels back after a change, use undo_last_operation.

Parameter	Type	Required	Description
layer_name	string	yes
rules	array[object]	no
clear	boolean	no

symbology_tools

set_label_style

Style the labels already on a vector layer (add them first with apply_labels): font colour and size, bold, italic, the halo around the text (on/off, colour, size), placement (around_point, over_point, horizontal, free, curved, parallel), the scales between which labels show (visible_zoomed_out_to = the smallest scale such as 250000 for 1:250,000, visible_zoomed_in_to = the largest such as 5000), and show_labels to switch labels on or off. Give only what should change. Rule-based labeling is reported, not changed.

Parameter	Type	Required	Description
layer_name	string	yes
font_color	string	no
font_size	number	no	Points, 1 to 120.
bold	boolean	no
italic	boolean	no
halo	boolean	no	Draw a halo (buffer) round the text.
halo_color	string	no
halo_size_mm	number	no	0 to 10.
placement	string	no
visible_zoomed_out_to	number	no	Scale denominator, e.g. 250000.
visible_zoomed_in_to	number	no	Scale denominator, e.g. 5000.
show_labels	boolean	no

set_layer_symbol

Change how a vector layer's symbols are drawn beyond colour: outline colour and width, line pattern (solid, dashed, dotted, dash_dot), marker shape (circle, square, diamond, triangle, star, cross, x, pentagon, hexagon, heart, arrow) and size, fill pattern (solid, none, hatch_forward, hatch_backward, horizontal, vertical, cross, diagonal_cross, dots_dense, dots_sparse) and opacity. Give only what should change; everything else stays. Colours can be hex or plain words ('dark red'). On a categorized, graduated or rule-based layer it keeps the classification colours and sizes: fill_color and marker_size_mm are refused there (use the style tool that made the classes). Only simple symbols are changed; an SVG or font marker is reported, not overwritten.

Parameter	Type	Required	Description
layer_name	string	yes
fill_color	string	no
outline_color	string	no
outline_width_mm	number	no	0 to 20; 0.26 is a thin line, 1 a thick one.
opacity_percent	number	no	0 to 100 for the whole layer.
marker_shape	string	no
marker_size_mm	number	no	0.1 to 100.
line_style	string	no	Pattern of a line or of a polygon outline.
fill_style	string	no	Pattern of a polygon fill, for example hatch_forward.

set_raster_style

Change how a raster layer is displayed: mode='unique_values' gives one colour per distinct cell value (for land cover, classes, zones; refused above 256 distinct values), resampling (nearest keeps blocky cells, bilinear or cubic smooth them), opacity_percent, and no-data: nodata_min/nodata_max make cells in that range transparent (both ends are INCLUDED: for 'below 0' give nodata_max just under 0, such as -0.000001), clear_nodata=true restores the file's own no-data. Give only what should change. Display only; the cell values are not changed. For a continuous colour ramp use apply_raster_stretch.

Parameter	Type	Required	Description
layer_name	string	yes
mode	string	no	'unique_values'
resampling	string	no	nearest, bilinear or cubic
opacity_percent	number	no
nodata_min	number	no
nodata_max	number	no
clear_nodata	boolean	no

table_importers

import_humanitarian_table

Read a published humanitarian table from a CSV/Excel file the user supplies (typically downloaded from HDX) and validate it: kind 'ipc' (IPC area phase 1-5, population, phase 3+ population), 'inform' (INFORM Risk 0-10 scores) or 'unosat' (damage points with coordinates and damage class). Columns are matched by common names, but the layouts are UNVERIFIED against real files: the result shows the mapping used, and anything not matched or ambiguous is listed, so check it and pass an explicit mapping ({role: column}) if needed. Nothing is repaired or imputed: an invalid or missing value is reported and left empty (a missing IPC phase is not phase 1). For ipc and inform, giving layer_name and layer_key_field (P-code preferred) reports how the rows join to the admin layer and, with write_fields, writes the values to it as new numeric fields (needs confirmation); unmatched and duplicate keys are never guessed. For unosat, load the points with load_tabular_data_as_layer using the detected latitude/longitude columns. Official-source values: quote the file and its date, not this tool, as the source.

Parameter	Type	Required	Description
file_path	string	yes	Absolute path to the .csv/.xlsx/.xls file.
kind	string	yes	'ipc', 'inform' or 'unosat'.
mapping	object	no	Optional explicit {role: column}. Roles -- ipc: area_code, area_name, phase, population, phase3plus_population, period; inform: area_code, area_name, risk, hazard_exposure, vulnerability, lack_of_coping_capacity; unosat: latitude, longitude, damage_class, site_id.
sheet_name	string	no	Sheet for Excel files. Defaults to the first.
delimiter	string	no	CSV delimiter. Defaults to ','.
layer_name	string	no	Optional admin polygon layer to join to (ipc/inform).
layer_key_field	string	no	Field on that layer holding the P-code (or name when the file has no code).
write_fields	boolean	no	With layer_name: write the values to the layer as new numeric fields (ipc_phase, ipc_pop, ipc_p3plus / inf_risk, inf_haz, inf_vuln, inf_coping). Needs confirmation.

task_grid_tools

generate_mapping_task_grid

Split an area of interest into a grid of square mapping tasks for remote or crowd mapping (Tasking Manager style), so volunteers can digitise roads and buildings without overlapping. Cells are cell_size_m wide (measured in a local metric projection) and clipped to the area. Optionally ranks tasks High / Medium / Low by how many points of priority_points_layer fall in each (e.g. damage reports, existing buildings) or by the population in population_raster_layer, so the most important cells are mapped first. Creates a polygon layer and can write the tasks as GeoJSON (EPSG:4326, properties task_id, area_km2, value, priority) for import into a tasking tool; it has NOT been checked against a specific Tasking Manager instance's import rules.

Parameter	Type	Required	Description
aoi_layer	string	yes	Polygon layer with the area of interest.
cell_size_m	number	no	Task width in metres (minimum 100). Default 2000.
priority_points_layer	string	no	Optional point (or other vector) layer; the priority value is the number of its features in each cell.
population_raster_layer	string	no	Optional population raster; the priority value is the sum of its cells in each task. Ignored if priority_points_layer is given.
aoi_where	string	no	Optional QGIS expression (e.g. "ADM1_EN" = 'Aden') limiting the area to matching features of aoi_layer. Use this instead of filtering the source layer, which would hide features from the whole project.
output_layer_name	string	no	Name of the new task layer. Default 'mapping_tasks'.
export_geojson_path	string	no	Optional file path for the GeoJSON export. Use 'auto' to write into the system temp folder.

tool_discovery

find_tools

Look up which tools can do a step you were not given a tool for (for example 'contour lines', 'split a line by polygons', 'download elevation'). Returns the best matching tool names with a one-line description each, and makes them available for the rest of this request. Use it BEFORE writing a script. It only searches; it changes nothing.

Parameter	Type	Required	Description
need	string	yes	The operation you need, in plain English words, even when the user wrote in another language (tool names and descriptions are English, so an Arabic or French phrase finds nothing). Name the operation, not the goal: 'graduated colour style for polygons by a number', 'clip lines to polygons', 'count points in each polygon', 'turn a layer on and off'.

run_steps

Run several tool calls in order in ONE step instead of one model turn each. Use it only when you already know every argument of the whole chain (for example you choose the output layer names yourself). Each step is {tool, arguments}; an argument may be the whole-string reference "$2.layer_name" (field layer_name of step 2's result) or "$prev.layer_name". Steps run one at a time through the normal tool path, so confirmations and safety checks still apply; the run STOPS at the first error or the first call waiting for the user's Confirm and reports exactly which steps ran. At most 8 steps; no deleting tools; do not nest run_steps. If a later step depends on something you must look at first, make separate calls instead.

Parameter	Type	Required	Description
steps	array[object]	yes	Ordered steps.

tool_operations_tools

get_tool_operation_type

Look up which operation-type category (READ, CREATE, MODIFY, DELETE, or PUBLISH) a registered Cartogen AI tool falls into -- e.g. before deciding whether a planned call is safe to make without asking first. Returns an error if the name isn't a registered tool.

Parameter	Type	Required	Description
tool_name	string	yes	Exact registered tool name, e.g. 'remove_layer'.

list_tools_by_operation_type

List every registered tool classified under one operation-type category (READ, CREATE, MODIFY, DELETE, or PUBLISH). Use this to see, for example, every tool that can write an external file (PUBLISH) or remove/replace project state (DELETE).

Parameter	Type	Required	Description
operation_type	string	yes	One of READ, CREATE, MODIFY, DELETE, PUBLISH.

transaction_tools

get_turn_transaction_log

List every tool call made so far during THIS turn (this one user request), each tagged with its operation type and, when it added a new layer, whether it can be undone with undo_last_operation. Use this before undo_last_operation to see what's actually available to undo. Also lists undoable calls from the last few earlier messages (marked earlier_turn).

No parameters.

undo_last_operation

Reverse the most recent undoable tool call: one made this turn, or if there is none, the latest one from the last few earlier messages (the user just says 'undo that'; see get_turn_transaction_log to check what qualifies first). Call this tool for any 'undo' request instead of clearing or re-setting the thing by hand. Covers: a call that added a new layer (removes it); remove_layer (restores the removed layer and its data); field_calculator/calculate_area/calculate_length (restores the field's prior values, or deletes it if it didn't exist before); apply_categorized_style/apply_graduated_style/apply_graduated_symbol_style (restores the prior style); set_dataset_status/set_layer_sensitivity/set_layer_confidence/run_query/set_layer_filter (restores the prior value); labels, callouts, diagrams, point markers, raster relief, saved symbols, layer elevation and layer time settings (restores the prior setting); delete_features (puts the deleted features back); add_field (removes the new field again, but only while it is still empty: once it holds values undo refuses and says so). It cannot undo load_project or any other in-place edit not in that list -- a real, separate, still-open gap, not something this tool silently skips without saying so. Destructive action requiring UI confirmation.

Parameter	Type	Required	Description
confirmed	boolean	no	Set true only after the user has confirmed the undo.

trigger_tools

evaluate_forecast_trigger

Evaluate an anticipatory-action trigger rule against forecast values already in a layer's attribute table: for each area, does the forecast reach the threshold within the lead window (optionally with a minimum probability)? Returns which areas are activated, with the maximum forecast value, the number of exceeding forecast rows and the first exceedance date, plus the rule restated in words. The threshold, lead window and probability cut-off MUST come from the user's own trigger protocol -- this tool has no defaults and never invents one; if the user has not given a threshold, ask for it. It evaluates a rule; it does not fetch or generate forecasts and its answer is only as good as the forecast data in the layer. Read-only.

Parameter	Type	Required	Description
layer_name	string	yes	Layer (or table) holding forecast rows: one or more per area.
value_field	string	yes	Numeric field with the forecast value (e.g. river discharge, rainfall, wind speed).
threshold	number	yes	Trigger threshold, from the user's protocol. Required.
comparison	string	no	Default '>='.
unit_field	string	no	Field identifying the area (admin name/code, station). Omit to evaluate the whole layer as one unit.
date_field	string	no	Field with the date the forecast is valid for. Required with lead_days.
lead_days	number	no	Only count forecast rows dated from as_of to as_of + lead_days.
as_of	string	no	ISO date the lead window starts from. Default today.
probability_field	string	no	Optional numeric field with the forecast probability of the value (0-1, or 0-100 with probability_scale='percent').
min_probability	number	no	With probability_field: minimum probability for a row to count, in the same unit as the field (0-1, or 0-100 when probability_scale is 'percent', e.g. 70 for 70%).
probability_scale	string	no	'fraction' (default): probability_field and min_probability are 0-1. 'percent': both are 0-100.
min_exceedances	integer	no	Exceeding forecast rows needed to activate a unit. Default 1.

vertex_edit_tool

edit_vertices

Add, move or delete one vertex of one feature of a line or polygon layer: action 'delete' removes a vertex, 'move' moves it to x, y, 'add' puts a new vertex on the segment nearest x, y (the shape does not change). Choose the feature by feature_id and the vertex by index (0-based; a polygon ring is closed, so a square has 5 vertices and the first and last are the same corner) or by the position nearest it (near_x, near_y, optionally within tolerance). Coordinates are in the layer's CRS. Changes geometry: a preview is shown for confirmation first, the edit is one undoable step (undo_manual_edit), and a change that would make a valid geometry invalid is refused.

Parameter	Type	Required	Description
layer_name	string	yes	A line or polygon layer.
feature_id	integer	yes	The feature's id (the QGIS feature id).
action	string	yes	add, move or delete.
index	integer	no	The vertex to move or delete, 0-based over the whole geometry.
near_x	number	no	Instead of index: pick the vertex nearest this x (layer CRS).
near_y	number	no	Instead of index: pick the vertex nearest this y (layer CRS).
tolerance	number	no	With near_x/near_y: refuse if the nearest vertex is farther than this (layer units).
x	number	no	move: the new x; add: the x of the point near which the vertex is added.
y	number	no	move: the new y; add: the y of the point near which the vertex is added.

watershed_tools

delineate_watershed

Delineate the watershed upstream of an outlet point on a DEM in the project and MEASURE it: basin area, longest hydraulic flow path, H (elevation drop along it), main-channel slope and the Kirpich time of concentration. Adds the basin, flow path and outlet to the project. location is DMS ('32°01'47.39"N, 35°48'21.00"E') or 'lat, lon'. Needs an elevation raster that covers the point (fetch_dem first if none). It does NOT invent rainfall intensity or a runoff coefficient: the reply says which design inputs the user must give, then use calculate_rational_watershed_peak_flow for the peak flow.

Parameter	Type	Required	Description
location	string	no	Outlet as DMS or 'lat, lon'.
lat	number	no
lon	number	no
dem_layer	string	no	Name of the DEM raster; default: a raster in the project that covers the point.
return_period_years	number	no	Design return period, used to word the design-input request.
radius_km	number	no	Half-width of the window read around the outlet (default 8, at most 15).
snap_distance_m	number	no	How far the outlet may move onto the derived channel (default 300).
layer_prefix	string	no	Prefix for the new layers (default 'Watershed').

web_research_tools

web_research (network-only)

Search the internet and get back real results with their SOURCES: title, URL, outlet, date and snippet. kind='web' for pages, kind='news' for recent news articles (last 1 to 30 days). Use this whenever the user wants information from the internet 'with the source', news, or a fact you cannot know. The answer must cite the returned URLs and must not add facts the results do not contain. For a MAP of incidents from the news use find_incident_reports with sources=['news'] instead.

Parameter	Type	Required	Description
query	string	yes	What to look up, in a few clear words.
kind	string	no	'web' (default) or 'news'.
max_results	integer	no	How many results (default 8, at most 25).
days	integer	no	For kind='news': how many days back (1 to 30, default 7).

workflow_file_tools

export_workflow_file

Save the steps that made one or more result layers as a shareable workflow file (.cgworkflow.json) that a colleague can open, read and run on their own layers. Built only from the recorded history of the named layers: the tools used, their arguments, and the data sources. Layers the analysis started from become named roles that the colleague maps to their own layers; no data, file paths or credentials are written. A step that cannot be shared (a tool not on the shareable list, or an argument that looks like a file path) is left out and reported. The user sees the whole file and confirms before anything is written. output_path is optional: omit it to save under the project's exports/workflows folder.

Parameter	Type	Required	Description
layer_names	array[string]	yes	The result layer(s) whose history to export.
name	string	no	A short title for the workflow.
description	string	no	One or two sentences on what it does.
output_path	string	no