Complete Tool Reference¶

This page lists all 113 tools registered on aihydro-tools v1.7.0, exactly as the agent sees them. Tools are grouped by tier (how readily they are surfaced to the agent) and domain.

• 113 tools total — 26 hot (full schema always in-context), the rest fetched on demand via describe_tool(name).
• Call list_available_tools() at runtime for the live count on your installation; community plugins add more.

Tier 1 — Core (always in-context)¶

Claims & Provenance¶

add_assumption · hot¶

Record a scientific assumption or caveat in the session ledger.

add_assumption(session_id='01646500', assumption_id='...', statement='...', risk='...', risk_rationale='...', affects=[])

add_claim · hot¶

Add a scoped scientific claim to the session ledger.

add_claim(session_id='01646500', claim_id='...', statement='...', claim_type='...', status='...', confidence='...', confidence_rationale='...', basins=[], period='...')

draft_claim_from_run · hot¶

Draft a claim pre-bound to evidence from a Tier 1 run. Reads session._run_log[run_id], returns a template with evidence_spans filled in. Agent authors only the 'statement' and 'confidence_rationale'. run_id: from a Tier 1 tool's _run_id field. metric_ref: e.g. kge, runoff_ratio, baseflow_index.

draft_claim_from_run(session_id='01646500', run_id='...', metric_ref='...')

promote_claim_to_registry · hot¶

Promote a session claim to the global knowledge registry. Requires researcher approval and passes through a strict validation gate.

promote_claim_to_registry(session_id='01646500', claim_id='...')

Modelling¶

get_model_results · hot¶

Return cached training results: NSE, KGE, RMSE, model_dir. job_id reads from the job artifact dir; otherwise from session.model. session_id : str | None (optional from Wave 3) — auto-resolved from chat context.

get_model_results(session_id='01646500', job_id='...')

train_hydro_model · hot¶

Kick off a model training job (detached subprocess). Returns {job_id} immediately — poll with get_training_status (≤1× per minute). Requires watershed+forcing (HBV) or watershed+streamflow+forcing (LSTM). framework: hbv (HBV-light, default) | neuralhydrology (LSTM, needs pip install neuralhydrology). model (NH only): cudalstm | ealstm | transformer. Typical runtime: 2-15 min (HBV), 15-60 min (LSTM).

train_hydro_model(session_id='01646500', workspace_dir='...')

Streamflow¶

extract_hydrological_signatures · hot¶

Extract 17 CAMELS-style hydrological signatures (flow stats, BFI, runoff ratio, elasticity, high/low flow events, FDC slope, timing). Requires delineate_watershed first. Defaults to CAMELS analysis period 1989-10-01 to 2009-09-30.

extract_hydrological_signatures(session_id='01646500', start_date='1989-10-01')

separate_baseflow · hot¶

Separate baseflow from streamflow via digital filter. Writes daily series + BFI to session.baseflow. Requires fetch_streamflow_data first.

separate_baseflow(session_id='01646500', method='lyne_hollick')

Consistency Validators¶

check_temporal_alignment · hot¶

Check if two time-series slots share the same temporal range.

check_temporal_alignment(session_id='01646500', slot_a='...', slot_b='...')

check_unit_consistency · hot¶

Check if a session slot uses the expected scientific units.

check_unit_consistency(session_id='01646500', slot='...', expected_units='...')

check_water_balance_consistency · hot¶

Check if annual runoff is less than or equal to annual precipitation.

check_water_balance_consistency(session_id='01646500')

Watershed & Terrain¶

compute_twi · hot¶

Topographic Wetness Index TWI = ln(a / tan(beta)). Used for soil moisture mapping, saturated zone ID, runoff generation. Works globally: USGS 3DEP inside CONUS, Copernicus GLO-30 everywhere else. Requires delineate_watershed or delineate_watershed_from_point first. Saves GeoTIFF + PNG + HTML map when workspace_dir is set and create_map=True.

compute_twi(session_id='01646500', resolution=30)

create_cn_grid · hot¶

NRCS Curve Number grid: NLCD land cover × Polaris soil → distributed CN. Currently CONUS only (NLCD + POLARIS coverage). Global CN grid (ESA WorldCover + SoilGrids) is planned for a future release. Requires delineate_watershed first. Returns CN stats, zone percentages, LULC + soil breakdowns. Saves GeoTIFF / NetCDF / PNG / HTML. year: NLCD year (default 2019).

create_cn_grid(session_id='01646500', year=2019)

delineate_watershed · hot¶

Delineate USGS gauge watershed via NLDI + NWIS metadata.

delineate_watershed(gauge_id='01646500', session_id='01646500')

delineate_watershed_from_point · hot¶

Delineate a watershed from a pour point (lat/lon, EPSG:4326). Tiered: NLDI in CONUS, MERIT Hydro via GEE + pyflwdir globally, local MERIT rasters if requested, then raw DEM fallback / MERIT-Basins expert tiers.

delineate_watershed_from_point(lat=28.22, lon=76.77)

extract_geomorphic_parameters · hot¶

Extract 28 geomorphic parameters (morphometry, relief, drainage network, shape indices) from a 30m DEM. Works globally: uses USGS 3DEP inside CONUS and Copernicus GLO-30 via aihydro-data everywhere else. Requires delineate_watershed or delineate_watershed_from_point first. Returns DA_km2, Lp_km, Lb_km, shape indices, hypsometric integral, drainage density, stream-order metrics, etc.

extract_geomorphic_parameters(session_id='01646500', dem_resolution=30)

Tier 2 — Extended¶

Analysis¶

compute_spectral_index · hot¶

Compute a spectral index (NDWI, NDVI, NDBI, NBR, MNDWI, …) for the current study watershed.

compute_spectral_index(index_name='NDWI')

CAMELS Attributes¶

fetch_camels_us · hot¶

CAMELS-US static catchment attributes (671 minimally-disturbed CONUS gauges). Single gauge via gauge_id (cached in session) OR bulk via gauge_ids (list, [] = all 671; saved to workspace). Returns ~60 attributes grouped by topography/climate/hydrology/soil/ vegetation/geology. Citation: Addor et al. (2017), HESS 21. session_id : str | None (optional from Wave 3) — auto-resolved from chat context.

fetch_camels_us(session_id='01646500', gauge_id='01646500')

Citations & Literature¶

index_literature¶

Scan a folder of papers (.txt, .md, .pdf via pypdf) and build a text-only searchable index (literature_index.md with first ~800 chars per doc). Re-run when papers are added. folder_path defaults to ~/.aihydro/projects/<name>/literature/.

index_literature(project_name='...')

lookup_citation¶

Look up a citation (free text or DOI). Cascade: CrossRef → Semantic Scholar → DataCite. Cached at ~/.aihydro/citations/ (30 day TTL).

lookup_citation(query='...')

search_literature¶

Query the literature index. Text match on filenames + excerpts, no vector DB. return_full_content=True returns full text of matched docs for the LLM to synthesise (can be large).

search_literature(project_name='...', query='...')

Claims & Provenance¶

update_claim_status¶

Update the status and confidence of an existing claim.

update_claim_status(session_id='01646500', claim_id='...', status='...', confidence='...', rationale='...')

Course / Teaching¶

course_navigate¶

Push the HTML Preview panel to open a specific course module.

course_navigate(module_id='...')

course_scaffold¶

Scaffold a course on disk: course.json + one styled module.html per module (AI-Hydro design + edit-mode markers). Load the course-authoring skill first for the full workflow.

course_scaffold(title='...', out_dir='...', modules=[])

course_set_progress¶

Mutate progress for the active course. Requires explicit user agreement.

course_set_progress(module_id='...')

Data Fetch (aihydro-data)¶

data_batch_fetch¶

Parallel fetch over N geometries (e.g. a set of watersheds or gauges).

data_batch_fetch(variable='...', geometries=[], start='2020-01-01', end='2020-12-31')

data_describe_product¶

Return the full ProductSpec for a single product, including citation, BibTeX, and agent-facing next_steps.

data_describe_product(product_id='...')

data_fetch · hot¶

Fetch a single hydrology variable for one geometry / time window.

data_fetch(variable='...', geometry='...', start='2020-01-01', end='2020-12-31')

data_list_products¶

Discover available data products, optionally filtered.

data_list_products(variable='...', region='...')

data_validate_request¶

Pre-flight dry-run — validate a request without hitting any backend.

data_validate_request(variable='...', geometry='...', start='2020-01-01', end='2020-12-31')

Execution¶

run_python · hot¶

Execute a Python snippet in a sandboxed subprocess inside workspace_dir.

run_python(script='...', workspace_dir='...')

General¶

get_citation_by_doi¶

Resolve a citation by exact DOI (uses cache when fresh). Same schema as lookup_citation.

get_citation_by_doi(doi='...')

write_research_interpretation¶

Phase 2 of interpretation: persist LLM-authored scientific synthesis to research.md + session so it's auto-injected into every future conversation. interpretation: 3-6 sentences of flowing prose (no bullets). site_name: short descriptive slug for display + exports.

write_research_interpretation(session_id='01646500', site_name='')

Research Ledger¶

add_journal_entry¶

Add a timestamped entry to the project's experiment journal (persistent across conversations; searchable via search_experiments). Use for findings, decisions, hypotheses, anomalies, lit-synthesis conclusions.

add_journal_entry(project_name='...', entry='...')

search_experiments¶

Full-text search across all sessions in a project (case-insensitive over every computed slot's JSON). Use for "find basins with NSE > 0.7", "which gauges have high BFI". compare_sessions=True adds a side-by-side metrics table.

search_experiments(project_name='...', query='...')

Map Panel¶

gee.extract_timeseries¶

Extract basin time series from a GEE ImageCollection and save CSV.

gee.extract_timeseries(session_id='01646500', project_id='...')

gee.preview_layer¶

Create a GEE tile layer and add it to the AI-Hydro map panel.

gee.preview_layer(session_id='01646500', project_id='...')

map_apply_symbology¶

Apply graduated (choropleth) symbology to an existing vector layer on the map.

map_apply_symbology(layer_id='...', attribute='...')

map_save_roi¶

Save the host map session active ROI to workspace roi/<slug>.geojson and update roi/active.json. Requires an active ROI on the map session file.

map_save_roi(session_id='01646500', name='...')

map_set_roi¶

Set the active map ROI (study basin polygon). The map panel updates via the host command watcher. Pass GeoJSON Feature, FeatureCollection, or JSON string.

map_set_roi(session_id='01646500', geojson='...')

map_set_working_geometry¶

Set which workspace GeoJSON file is the active study geometry for this session (used by current_map_basin / GEE). Path is relative to workspace, e.g. vectors/my_basin.geojson or watershed_01031500.geojson.

map_set_working_geometry(session_id='01646500', workspace_path='...')

map_update_layer¶

Update layer style/visibility in-place (don't rewrite GeoJSON for styling). For choropleth, set graduated_attribute (+ method/classes/ramp).

map_update_layer(layer_id='...')

Researcher Persona¶

log_researcher_observation¶

Log a meaningful observation about the researcher (memory-style; for durable inferences not captured by structured profile fields). Skip trivial confirmations or temporary preferences.

log_researcher_observation(observation='...')

HTML Preview¶

preview_address_comment¶

Address a user comment. new_text (optional) proposes replacement text for the commented selection — user sees a diff. Omit to just resolve.

preview_address_comment(module_id='...', comment_id='...')

preview_revise_section¶

Propose a revised HTML section (well-formed snippet, no <html>/<body>). User sees a diff to accept/reject. Used in the edit-mode comment flow.

preview_revise_section(module_id='...', section_id='...', new_html='...')

Session Management¶

add_note¶

Append a researcher annotation (hypothesis, anomaly, decision) to the session.

add_note(session_id='01646500', note='')

export_session¶

Export the session. format='capsule' (default) writes a reproducible research folder (README.md + methods.md + citations.bib + environment.yml + session.json + data/figures/model/); 'bibtex' or 'json' write a single file. capsule_path: override default location.

export_session(session_id='01646500', capsule_path='...')

Watershed & Terrain¶

merit_add_map_layers¶

Build MERIT vector layers for the map viewport and optionally push to the map panel.

merit_add_map_layers(lat=28.22, lon=76.77)

merit_ensure_basin¶

Ensure MERIT-Hydro vectors exist for the Pfaf basin at (lat, lon) WGS84. Auto-downloads if AIHYDRO_MERIT_BASE_URL is set. Returns readiness flags.

merit_ensure_basin(lat=28.22, lon=76.77)

merit_ensure_basins_region¶

Check or stage regional MERIT-Basins vector/topology assets for hybrid routing.

merit_ensure_basins_region(pfaf_region='...')

merit_ensure_region¶

Ensure MERIT river vectors for all Pfaf basins in a named region preset.

merit_ensure_region(preset='...')

merit_ensure_routing_region¶

Check or stage flowdir-first regional MERIT routing assets.

merit_ensure_routing_region(lat=28.22, lon=76.77)

Tier 3 — Specialist¶

Analysis¶

list_spectral_indices¶

List all available spectral indices, their required bands, colormaps, citations, and recommended use cases.

No parameters.

list_spectral_indices()

Claims & Provenance¶

list_assumptions¶

List all assumptions in the session.

list_assumptions(session_id='01646500')

list_claims¶

List all scientific claims in the session.

list_claims(session_id='01646500')

Course / Teaching¶

course_get_curriculum¶

Full manifest + prerequisite_graph for a course. Use when you need the structure (not just progress). course_id_or_path: courseId of the active course OR absolute path to course.json. Defaults to active course.

course_get_curriculum(course_id_or_path='...')

course_get_state¶

Snapshot of the active course: current module, completion %, locked modules, next_recommended id. Call at the start of any course conversation. Returns {active: false} if no course is open.

No parameters.

course_get_state()

Data Fetch (aihydro-data)¶

data_doctor¶

Environment health check — probes each backend, auth state, cache size, and version compatibility. Agents call this when something goes wrong to figure out what is wrong before guessing.

No parameters.

data_doctor()

data_get_cache_status¶

Return a summary of the disk cache at ~/.aihydro/cache/data/.

No parameters.

data_get_cache_status()

data_help¶

Guided onboarding and topic reference for aihydro-data.

data_help(topic='...')

data_invalidate_cache¶

Remove a specific entry from the disk cache.

data_invalidate_cache(cache_key='...')

Discovery¶

aihydro_describe_capability · hot¶

Return a focused 1-line-per-tool summary of tools relevant to a domain.

aihydro_describe_capability(domain='...')

describe_tool · hot¶

Fetch the FULL parameter schema for a single tool, plus a worked example.

describe_tool(name='...')

describe_tools · hot¶

Fetch full parameter schemas for several tools at once (batch describe_tool).

describe_tools(names=[])

list_available_tools · hot¶

List all registered MCP tools (built-in + community plugins via the aihydro.tools entry point). For token-efficient discovery, prefer aihydro_describe_capability(domain) over this full dump.

No parameters.

list_available_tools()

Execution¶

get_library_reference¶

Look up field-name gotchas, API quirks, and copy-paste patterns for a Python library used in hydrological workflows.

get_library_reference(library='...')

list_relevant_clis¶

List installed AI-Hydro-aware CLIs (registered via aihydro.clis entry-point, plus aihydro-mcp). Use before driving any domain CLI from a shell.

No parameters.

list_relevant_clis()

Meteorological Forcing¶

fetch_forcing_data¶

[DEPRECATED — prefer data_fetch] Basin-averaged daily forcing data. Globally aware: - CONUS: GridMET (pr, tmmx, tmmn, srad, vs, rmax, rmin, pet, erc). - Global: CHIRPS precipitation + ERA5-Land temperature via aihydro-data.

fetch_forcing_data(start_date='2020-01-01', end_date='2020-12-31')

General¶

aihydro_chat_status¶

Show what study (if any) is currently bound to this chat.

aihydro_chat_status(chat_id='...')

aihydro_rebind_chat¶

Rebind the current chat to a specific existing study.

aihydro_rebind_chat(study_id='...')

list_cached_citations¶

List cached DOIs in ~/.aihydro/citations/. No API calls.

No parameters.

list_cached_citations()

Knowledge & Reference¶

get_dataset_info¶

Return metadata and limitations for a hydrological dataset (e.g. USGS NWIS, gridMET).

get_dataset_info(dataset_id='...')

get_equation_definition¶

Return the definition, formula, and assumptions for a scientific equation.

get_equation_definition(equation_id='...')

get_metric_definition¶

Return the structured definition of a model evaluation metric (e.g. KGE, NSE).

get_metric_definition(metric_id='...')

get_variable_definition¶

Return the canonical definition of a hydrological variable.

get_variable_definition(variable_id='...')

list_known_datasets¶

Return all known datasets, optionally filtered by domain.

list_known_datasets(domain='...', workspace_dir='...')

list_known_metrics¶

Return all known metrics, optionally filtered by domain.

list_known_metrics(domain='...', workspace_dir='...')

list_known_variables¶

Return a summary of all known hydrological variables.

list_known_variables(workspace_dir='...')

Map Panel¶

gee.status¶

Check Earth Engine availability/authentication status.

gee.status(project_id='...')

map_fit_extent¶

Ask the map to fit the viewport to the active ROI or visible layers.

No parameters.

map_fit_extent()

map_fit_layer¶

Zoom the map viewport to a layer's extent.

map_fit_layer(layer_id='...')

map_get_state¶

Map session snapshot from ~/.aihydro/map_session.json: basemap, view, visible layers, workspace root, active ROI, recent events.

map_get_state(session_id='01646500', event_limit=10)

map_list_layers¶

List map layer ids and catalog entries from the host (~/.aihydro/map_layer_catalog.json).

No parameters.

map_list_layers()

map_remove_layer¶

Remove a layer from the map by id.

map_remove_layer(layer_id='...')

map_set_basemap¶

Set the map basemap (e.g. esri-imagery, usgs-topo).

map_set_basemap(basemap_id='...')

map_show¶

Open the AI-Hydro map panel if it is not already visible.

No parameters.

map_show()

show_on_map¶

Push any GeoJSON geometry directly onto the AI-Hydro map panel.

show_on_map(geojson='...')

Modelling¶

get_training_status¶

Poll the status of a training job started by train_hydro_model.

get_training_status(job_id='...')

Researcher Persona¶

get_researcher_profile¶

Persistent researcher profile (domain, tools, preferences, focus). Built up over time from interactions; editable via update_researcher_profile. Returns fields + a formatted context_string for injection.

No parameters.

get_researcher_profile()

update_researcher_profile¶

Update the researcher profile. Strings replace; list fields (expertise, preferred_models) append; dict fields (tools_familiarity) merge. Call when the user states or you infer something durable about them.

update_researcher_profile(name='...', institution='...')

HTML Preview¶

preview_focus_cell¶

Scroll the HTML Preview to a specific cell and highlight it.

preview_focus_cell(module_id='...', cell_id='...')

preview_get_pending_changes¶

Return the batched queue of pending user comments + text edits for a module (from ~/.aihydro/comments/<id>.json). Process them in one turn, then preview_address_comment each. status: open (default) | awaiting_review | addressed | all.

preview_get_pending_changes(module_id='...')

preview_get_state¶

HTML Preview session snapshot: manifest, cell registry (IDs + last-run status), recent_errors. module_id defaults to most-recently-updated.

preview_get_state(module_id='...')

preview_list_modules¶

List the module IDs that currently have an open preview session.

No parameters.

preview_list_modules()

preview_recent_events¶

Recent PreviewEvent records (cell runs/errors, user comments, iframe interactions). Poll with since_seq for new-only. kind_filter examples: cell.error | user.comment | cell.run.completed. limit cap 200.

preview_recent_events(module_id='...', since_seq=0)

show_html_preview¶

Open an HTML file in the AI-Hydro HTML Preview panel (executes any .aihydro-cell Python cells inline). Use after writing a module via the interactive-module-builder skill. file_path must be absolute.

show_html_preview(file_path='...')

Projects¶

add_session_to_project¶

Link a session to a project. Session need not exist yet (pre-registration OK). Returns the updated session list.

add_session_to_project(project_name='...', session_id='01646500')

get_project_summary¶

Overview of a project: metadata, session summaries (with computed/pending slots), recent journal entries, literature index status.

get_project_summary(project_name='...')

start_project¶

Create or resume a named research project — top-level unit spanning multiple sessions + a literature folder + experiment journal. Idempotent. name: directory-safe slug (no spaces). Sets the project as active in the researcher profile.

start_project(name='...')

Session Management¶

archive_session¶

Freeze the session: move current interpretations + notes to a 'Historical' section in research.md. Use when concluding a study phase. Archived sessions stay readable and exportable.

archive_session(session_id='01646500')

clear_session¶

Clear cached results to force recompute. Notes/workspace_dir/site_name/ interpretation are always preserved. slots: subset of [watershed, streamflow, signatures, geomorphic, camels, forcing, twi, cn, model] (omit for all data slots).

clear_session(session_id='01646500', slots='...')

get_session_health¶

Audit a session for identity drift, workspace problems, and consistency gaps. Returns warnings keyed by code so the agent can fix issues before they propagate into research.md, exports, or downstream tools.

get_session_health(session_id='01646500')

get_session_raw_state¶

Phase 1 of interpretation: return raw computed state for the LLM to read (large arrays summarised). Follow with write_research_interpretation to author + persist the prose synthesis.

get_session_raw_state(session_id='01646500')

get_session_summary · hot¶

Return computed/pending slots for the session + notes + interpretation. session_id is optional — auto-resolved from the active chat when omitted.

get_session_summary(session_id='01646500')

merge_session_shards¶

Consolidate sub-agent shard files into the main session (notes, citations, slots). Shard files are deleted after merge. shard_ids: subset or omit to merge all available shards.

merge_session_shards(session_id='01646500', shard_ids='...')

start_session · hot¶

Start or resume a research session (persistent memory for a study). session_id: any string (slug, USGS gauge id, UUID); auto-generated if omitted. workspace_dir: pass once, remembered for all future calls — enables auto-save of tool outputs there. shard_id: for sub-agent forks.

start_session(session_id='01646500', shard_id='...')

Skills¶

list_skills¶

List installed workflow skills (playbooks). See SKILL DISCOVERY in the system prompt for the mandatory pre-flight protocol. domain filters to one of: frequency-analysis, baseflow, modelling, interpretation, composition, teaching, general.

list_skills(domain='...', workspace_dir='...')

load_skill¶

Load a skill's full SKILL.md (frontmatter + body). The skill's steps and format contracts are binding — see SKILL DISCOVERY in the system prompt. name: exact match from list_skills().

load_skill(name='...')

save_skill¶

Persist a new SKILL.md (Agent Skills open format) to ~/.aihydro/skills/agent-created/. Use after completing a novel workflow worth reusing. name will be slugified; content is the markdown body.

save_skill(name='...', description='...', content='...')

Streamflow¶

fetch_streamflow_data¶

[DEPRECATED — prefer data_fetch] Fetch USGS streamflow time series (NWIS).

fetch_streamflow_data(session_id='01646500', gauge_id='01646500')

Watershed & Terrain¶

delineation_doctor¶

Check runtime readiness for global MERIT Hydro watershed delineation.

delineation_doctor(project_id='...')

Workflows¶

get_workflow_manifest¶

Return the detailed steps, tool dependencies, and recommended validators for a specific scientific workflow.

get_workflow_manifest(workflow_id='...')

list_available_workflows¶

List all available scientific workflows (e.g. rainfall-runoff benchmarking).

list_available_workflows(workspace_dir='...')