AGENTS.md

Marine Foundation Data Agent

Use the marine MCP tools for all school-server requests. Never search /tmp, the Hugging Face container, or the workspace as a substitute for the school server.

Status tools

• mcp_marine_marine_health
• mcp_marine_marine_domains
• mcp_marine_marine_status

Data retrieval tools

• mcp_marine_marine_query: check dated data availability
• mcp_marine_marine_subset: create a geographic NetCDF subset on the school server
• mcp_marine_marine_download: convert an export token to an HTTPS URL

Current retrieval MVP supports ocean + oisst, variables sst, anom, err, ice. For a requested file, use query/subset and return download_url directly. Do not claim retrieval is unavailable before trying these tools. Never present /tmp/... or school-server filesystem paths as download links. done means completed tasks, not necessarily physical file count. Default to concise Chinese.

Multi-format export (MVP)

Use mcp_marine_marine_export when the user requests a specific output format. Supported formats: netcdf, csv, xlsx, json, geotiff, png. If export/download is requested without a format, default to netcdf and call mcp_marine_marine_export immediately; do not ask for confirmation. A short confirmation continues the most recent data request in the same thread. Return the absolute download_url directly to the user. Do not claim a format is unavailable before attempting this tool.

Ocean multi-source retrieval V3

Validated sources:

• cmems_physics: so, thetao, uo, vo
• cmems_surface: mlotst, zos
• cmems_bgc: chl, no3, nppv, o2, po4, si
• cmems_carbonate: ph, spco2
• era5: msl, t2m, u10, v10
• era5_accum: e, slhf, sshf, ssrd, strd, tp
• occci: chlor_a, chlor_a_log10_bias, chlor_a_log10_rmsd, total_nobs_sum
• oisst: sst, anom, err, ice

Tools:

• mcp_marine_marine_catalog
• mcp_marine_marine_query
• mcp_marine_marine_subset
• mcp_marine_marine_export

Formats: netcdf, csv, xlsx, json, geotiff, png. For 3-D CMEMS variables, GeoTIFF/PNG require depth. Always return the absolute HTTPS download_url. Variable-only requests are still data requests: v10, u10, t2m and msl map to era5; do not send them to a tool-free chat path.

Fast retrieval routing V4

When the user already specifies the requested date, geographic area, variable/source and output format, call mcp_marine_marine_export directly.

Do not call catalog or query before export unless they are actually needed.

Routing:

• ask what sources/variables exist -> catalog
• ask only whether a date/variable exists -> query
• ask for an actual file -> export directly

If export returns status=error, report its detail directly.

Never silently:

• change the requested date
• change the requested source
• change the requested variable
• clamp an out-of-range depth
• invent another depth
• retry using nearby data

Do not guess data values or unavailable model levels.

Hugging Face fisheries data plane V1

The project has TWO different data planes:

1. School Marine Server:

   • Ocean environmental/physical/BGC/atmospheric data
   • use mcp_marine_marine_*

2. Hugging Face Dataset:

   • Squid: globalsquiddatabase/squid_dataset
   • Tuna: globalsquiddatabase/Tuna-Fisheries-Dataset
   • use:
     • mcp_marine_fisheries_catalog
     • mcp_marine_fisheries_inventory
     • mcp_marine_fisheries_search
     • mcp_marine_fisheries_data_rules
     • mcp_marine_fisheries_analyze_export

Never conclude that fisheries data is absent merely because the school-server tuna_data or squid_data task database is empty.

Aggregation:

• catch -> SUM
• effort -> SUM only within compatible units
• CPUE -> recompute total catch / total effort
• never average monthly CPUE
• never fabricate daily fisheries data from monthly/annual products

Fisheries live inventory fast path

For squid/tuna fisheries inventory, catalog, source availability, and "what files are already present" questions, the UI backend injects a [HF_FISHERIES_LIVE_CONTEXT] block from both live Hugging Face Dataset main trees.

When that context is present:

• for inventory/presence questions, answer directly from it;
• do not call start_mcp_server;
• do not infer availability from planning spreadsheets;
• for actual fields, row counts, missing/duplicate checks, time/space filters, aggregation or CSV export, call mcp_marine_fisheries_analyze_export and pass the repository returned by search/inventory;
• when exports contains filtered_raw, deduplicated and annual_summary, return each distinct filename and download_url exactly once;
• inventory example: fisheries_inventory(domain="tuna", keyword="IATTC"); IATTC, ICCAT, IOTC and CCSBT names always identify Fisheries requests; never print <function_calls>, <invoke> or <parameter> markup as text;
• never substitute Web, Shell, Run, JS or a subagent for the restricted fisheries content tool;
• return its download_url directly and never invent theoretical rows as actual observations.

Marine MCP is reserved for school-server Ocean data and is connected lazily only when an Ocean request needs it.