Tool reference¶

Generated from the tool registry by scripts/gen_tools_reference.py; do not edit by hand. 12 tools are registered; amf_download_data, amf_list_files, amf_preview_data, amf_read_bif are offered only over stdio. Inputs are snake_case and outputs camelCase. Every result also carries resolved, notes, nextSteps and source (whose backend says what answered: the AmeriFlux API, its file server, or nothing upstream), and failures return structuredContent.error with a stable code. Tools still to come are on the roadmap.

Tool	Title	Family	Download identity
`amf_describe_variables`	Describe variable names: grammar, units, QC and sites	variables	no
`amf_download_data`	Download AmeriFlux data (with consent)	data	required
`amf_get_availability`	Get data availability per site and product	availability	no
`amf_get_badm`	Get a site's BADM metadata	metadata	no
`amf_get_citation`	Get citations and acknowledgments for sites	citation	no
`amf_get_site`	Get one AmeriFlux or FLUXNET site	discovery	no
`amf_list_files`	List local AmeriFlux and FLUXNET files	local	no
`amf_ping`	Check ameriflux-mcp status	core	no
`amf_preview_data`	Preview a local AmeriFlux or FLUXNET data file	local	no
`amf_read_bif`	Read a local BADM (BIF) file	local	no
`amf_search_sites`	Search AmeriFlux and FLUXNET sites	discovery	no
`amf_search_variables`	Search the FP Standard and FLUXNET variable dictionaries	variables	no

amf_describe_variables¶

Describe variable names: grammar, units, QC and sites. Decode up to 20 variable names from BASE or FLUXNET files: base name and FP Standard definition with QA/QC range, qualifiers (_PI, _QC, _F, _IU), position (_H_V_R, _H_V_A, _#), FLUXNET processing tokens (MDS, VUT/CUT, NT/DT, REF, percentiles), units and QC meaning per resolution, sign conventions. With site: whether the site measures it, sensor heights and instruments, yearly coverage. Next: call amf_get_availability for the site's years.


Surface	`variables`
Download identity	not needed
Transports	http, stdio
Annotations	readOnly=true, destructive=false, idempotent=true, openWorld=true
Upstream endpoints	`GET amfcdn.lbl.gov/api/v1/fp_var`

Inputs

Name	Type	Required	Description
`names`	array of string	yes	Variable names as in file headers: TA_F_1_1_1, FC_PI_F_1_1_A, GPP_NT_VUT_REF, NEE_VUT_05, TS_F_MDS_2_QC … (min items 1; max items 20)
`resolution`	string \	null	null
`site`	string \	null	null

Result fields (besides the common envelope)

Field	Type	Description
`variables`	array of VariableDescription
`page`	Page

amf_download_data¶

Download AmeriFlux data (with consent). Download AmeriFlux BASE-BADM, FLUXNET (FULLSET) or bulk BADM (BIF: AA-Flx/AA-Net) through AmeriFlux's logged route; stdio only. confirm=false (default) returns a plan: the exact text sent to the site PIs and the download log, eligible sites and the data policy; nothing is sent. Only after the user approves it, call again with confirm=true and accept_data_policy set to the plan's policy. Files are verified (size, ETag, zip CRC; sha256 sidecar). Next: amf_preview_data on a downloaded file.


Surface	`data`
Download identity	required (stdio only)
Transports	stdio
Annotations	readOnly=false, destructive=false, idempotent=false, openWorld=true
Upstream endpoints	`POST amfcdn.lbl.gov/api/v1/data_download` `HEAD ftp.fluxdata.org/.ameriflux_downloads/{product}/{file}` `GET ftp.fluxdata.org/.ameriflux_downloads/{product}/{file}` `GET amfcdn.lbl.gov/api/v1/data_availability/AmeriFlux/{product}/{policy}` `GET amfcdn.lbl.gov/api/v1/DOI/{site}/{product}`

Inputs

Name	Type	Required	Default	Description
`sites`	array of string	yes		Site IDs, NEON codes or names (up to 20); for product='BIF', AA-Flx (sites with flux data) or AA-Net (all sites). (min items 1; max items 20)
`product`	string		`"BASE-BADM"`	BASE-BADM, FLUXNET (FLUXNET-1F, FULLSET) or BIF (bulk BADM). FLUXNET2015 and FLUXNET-CH4 come from fluxnet.org (ameriflux://guide/fluxnet2015-access).
`policy`	string \	null		null
`profile`	string		`"default"`	Name of the configured identity profile (intended use and description). (pattern `^[A-Za-z0-9_.-]{1,64}$`)
`accept_data_policy`	string \	null		null
`confirm`	boolean		false	false: return the plan only. true: send the request, only after the user approved the plan.
`if_exists`	`skip` \	`replace`		`"skip"`

Result fields (besides the common envelope)

Field	Type	Description
`mode`	`plan` \	`download`
`product`	string
`dataProduct`	string	The product AmeriFlux receives (BIF goes as BASE-BADM).
`policy`	PolicyOut
`eligible`	array of SiteChoice
`ineligible`	array of IneligibleSite
`disclosure`	DisclosureOut
`identity`	IdentityOut
`ready`	boolean	Whether confirm=true would send the request now.
`blockers`	array of string	What must change first.
`localCopies`	array of LocalCopy
`downloadDir`	string
`files`	array of FileOut
`skipped`	array of SkippedLink
`manifest`	ManifestOut \	null
`piContactCount`	integer \	null
`citations`	array of CitationRef
`totals`	Totals \	null

amf_get_availability¶

Get data availability per site and product. Published years per site for AmeriFlux BASE-BADM and FLUXNET (FLUXNET-1F), FLUXNET2015 and FLUXNET-CH4, and BADM (BIF) membership, each labelled with the data policy it is shared under (CC-BY-4.0, Legacy, Tier Two). Lists requested sites without data and why, and the policy the selection must follow with its obligations. Invalid product/policy pairs fail before any request. Next: call amf_get_citation for these sites.


Surface	`availability`
Download identity	not needed
Transports	http, stdio
Annotations	readOnly=true, destructive=false, idempotent=true, openWorld=true
Upstream endpoints	`GET amfcdn.lbl.gov/api/v1/data_availability/{network}/{product}/{policy}` `GET amfcdn.lbl.gov/api/v1/site_availability` `GET amfcdn.lbl.gov/api/v2/site_info_display/AmeriFlux`

Inputs

Name	Type	Required	Default	Description
`sites`	array of string \	null		null
`products`	array of string \	null		null
`policy`	string \	null		null
`years`	string \	null		null
`limit`	integer		`50`	>= 1; <= 200
`offset`	integer		`0`	>= 0

Result fields (besides the common envelope)

Field	Type	Description
`rows`	array of AvailabilityRow
`emptySites`	array of EmptySite	Requested sites without data for a product, and why.
`policyVerdict`	array of PolicyVerdict	The policy the requested sites must follow, per product, with obligations.
`combinedObligations`	array of ObligationOut	Every obligation once, across all collections.
`summary`	AvailabilitySummary
`page`	Page

amf_get_badm¶

Get a site's BADM metadata. A site's Biological, Ancillary, Disturbance and Metadata as the API exposes it, by group: location, IGBP and climate, tower dates, team (no emails by default), disturbance and management, funding sponsors and organizations (needed to acknowledge Legacy sites), reference papers, and instruments with measurement heights. The full BADM ships as the BIF file in BASE-BADM downloads. Next: call amf_get_citation to cite the site.


Surface	`metadata`
Download identity	not needed
Transports	http, stdio
Annotations	readOnly=true, destructive=false, idempotent=true, openWorld=true
Upstream endpoints	`GET amfcdn.lbl.gov/api/v2/site_info_display/AmeriFlux` `GET amfcdn.lbl.gov/api/v1/site_display/FLUXNET/FLUXNET2015` `GET amfcdn.lbl.gov/api/v1/site_display/FLUXNET/FLUXNET-CH4` `GET amfcdn.lbl.gov/api/v1/DOI/{site}/{product}`

Inputs

Name	Type	Required	Default	Description
`site`	string	yes		Site ID (any case), NEON code, FLUXNET2015 old ID or name. (max length 200)
`include`	array of `site` \	`team` \	`disturbance` \	`funding` \
`variables`	array of string \	null		null
`references_limit`	integer		`20`	Reference papers per page. (>= 1; <= 200)
`references_offset`	integer		`0`	>= 0
`include_contacts`	boolean		false	Team emails, if the server allows it (privacy.allow_contact_emails).

Result fields (besides the common envelope)

Field	Type	Description
`siteId`	string
`name`	string
`policy`	string \	null
`site`	SiteGroup \	null
`team`	array of TeamEntry \	null
`disturbance`	array of string \	null
`fluxMeasurements`	array of string \	null
`funding`	FundingGroup \	null
`references`	ReferencesGroup \	null
`instruments`	InstrumentsGroup \	null

amf_get_citation¶

Get citations and acknowledgments for sites. Citations for up to 50 sites and one product (BASE-BADM, BIF, FLUXNET, FLUXNET2015): AmeriFlux's own versioned text per site DOI (e.g. 'Ver. 28-5'), the policy the selection must follow with its obligations (mixing CC-BY and Legacy means Legacy; mixing tiers means Tier Two), verbatim acknowledgments, Legacy site funding, the data-availability sentence and processing papers. Optional BibTeX. Next: cite every site in the reference list and follow the obligations.


Surface	`citation`
Download identity	not needed
Transports	http, stdio
Annotations	readOnly=true, destructive=false, idempotent=true, openWorld=true
Upstream endpoints	`GET amfcdn.lbl.gov/api/v1/DOI/{site}/{product}`

Inputs

Name	Type	Required	Default	Description
`sites`	array of string	yes		Site IDs (any case), NEON codes, FLUXNET2015 old IDs or names. (min items 1; max items 50)
`product`	string		`"BASE-BADM"`	BASE-BADM, BIF (cited with the BASE DOI), FLUXNET (FLUXNET-1F) or FLUXNET2015. FLUXNET-CH4 citations arrive in v0.2.
`include_bibtex`	boolean		false	Add a BibTeX @misc entry per citation.

Result fields (besides the common envelope)

Field	Type	Description
`product`	string
`citations`	array of CitationOut
`missing`	array of MissingCitation	Requested sites without a citation, and why.
`effectivePolicy`	EffectivePolicyOut
`acknowledgments`	array of AcknowledgmentOut
`siteFunding`	array of SiteFunding	Legacy policy: acknowledge each site's funding (DOI record sponsors).
`dataAvailability`	DataAvailabilityOut \	null
`processingReferences`	array of ReferenceOut
`bibtexElided`	boolean \	null
`page`	Page

amf_get_site¶

Get one AmeriFlux or FLUXNET site. One site by ID (any case), NEON code, FLUXNET2015 old ID or name: location, IGBP and Köppen with AmeriFlux's descriptions, data policy and what it means, DOIs, years per product (BASE, FLUXNET, FLUXNET2015, FLUXNET-CH4), member networks, links to NEON and to LTER data in EDI, team (no emails by default), measured BASE variables. Next: call amf_get_availability for exact years or amf_get_citation to cite it.


Surface	`discovery`
Download identity	not needed
Transports	http, stdio
Annotations	readOnly=true, destructive=false, idempotent=true, openWorld=true
Upstream endpoints	`GET amfcdn.lbl.gov/api/v2/site_info_display/AmeriFlux` `GET amfcdn.lbl.gov/api/v1/site_display/FLUXNET/FLUXNET2015` `GET amfcdn.lbl.gov/api/v1/site_display/FLUXNET/FLUXNET-CH4`

Inputs

Name	Type	Required	Default	Description
`site`	string	yes		Site ID (US-Ha1, any case), NEON code (SRER), FLUXNET2015 old ID (DK-ZaF) or site name. (max length 200)
`include`	array of `description` \	`team` \	`variables` \	`disturbance` \
`include_contacts`	boolean		false	Include team emails, if the server allows it (privacy.allow_contact_emails).

Result fields (besides the common envelope)

Field	Type	Description
`siteId`	string
`name`	string
`collections`	array of string
`status`	string \	null
`tower`	Tower
`location`	Location
`ecosystem`	Ecosystem
`policy`	PolicyInfo
`dois`	Dois
`products`	SiteProducts
`networks`	array of string
`crosslinks`	Crosslinks
`gasSpecies`	array of string
`description`	string \	null
`disturbance`	array of string \	null
`team`	array of TeamEntry \	null
`teamTotal`	integer \	null
`baseVariables`	array of string \	null
`baseVariablesTotal`	integer \	null

amf_list_files¶

List local AmeriFlux and FLUXNET files. Find the AmeriFlux and FLUXNET files already on this computer, in the download directory and configured local roots: BASE and BASE-BADM zips, BIF files, AmeriFlux FLUXNET (ONEFlux) and FLUXNET2015 archives, with each archive's members classified by kind (data, ERA, BIFVARINFO, BIF, aux tables), site, resolution, years and version. Unsafe members are flagged. stdio only. Next: call amf_preview_data(file=...) on one.


Surface	`local`
Download identity	not needed
Transports	stdio
Annotations	readOnly=true, destructive=false, idempotent=true, openWorld=false
Upstream endpoints	none

Inputs

Name	Type	Required	Default	Description
`path`	string \	null		null
`family`	array of `base` \	`bif` \	`fluxnet` \	`fluxnet2015` \
`site`	string \	null		null
`include_members`	boolean		true	Classify the members of each archive.
`limit`	integer		`50`	>= 1; <= 200
`offset`	integer		`0`	>= 0

Result fields (besides the common envelope)

Field	Type	Description
`roots`	array of string
`files`	array of FileEntry
`facets`	ListFacets
`unrecognized`	integer	Files skipped because their names are not ours.
`membersElided`	boolean \	null
`page`	Page

amf_ping¶

Check ameriflux-mcp status. Liveness and capability report: server version, protocol and transport; whether a download identity is configured (booleans and profile names only, never the values) and which tools need it; whether downloads are enabled and where files go. With check_api=true it also makes one small request to the AmeriFlux API to confirm connectivity. Next: read ameriflux://guide/identity to set up downloads.


Surface	`core`
Download identity	not needed
Transports	http, stdio
Annotations	readOnly=true, destructive=false, idempotent=true, openWorld=true
Upstream endpoints	`GET amfcdn.lbl.gov/api/v1/fp_var`

Inputs

Name	Type	Required	Default	Description
`check_api`	boolean		false	Also make one small request to the AmeriFlux API (the FP Standard variable list) to confirm connectivity.

Result fields (besides the common envelope)

Field	Type	Description
`pong`	`ok`
`version`	string
`protocolVersion`	string
`transport`	`stdio` \	`http`
`identity`	IdentityReport
`identityRequiredTools`	array of string	Registered tools that need the download identity (auth_required without it).
`downloadsEnabled`	boolean
`downloadDir`	string \	null
`localRoots`	array of string \	null
`endpoints`	Endpoints
`cache`	CacheReport
`upstream`	UpstreamCheck \	null

amf_preview_data¶

Preview a local AmeriFlux or FLUXNET data file. Summarize or page through a local BASE, AmeriFlux FLUXNET or FLUXNET2015 CSV, in place or inside its zip: time step and range, per-column count, missing (-9999), min, max, mean and out-of-range counts, units per resolution, a time window, a QC filter, UTC timestamps from the site's BIF, a SUBSET column view, and aux tables. Stops within a byte and time budget. stdio only. Next: call amf_describe_variables on columns to decode.


Surface	`local`
Download identity	not needed
Transports	stdio
Annotations	readOnly=true, destructive=false, idempotent=true, openWorld=false
Upstream endpoints	none

Inputs

Name	Type	Required	Default	Description
`file`	string \	null		null
`site`	string \	null		null
`product`	string \	null		null
`resolution`	`HH` \	`HR` \	`DD` \	`WW` \
`columns`	array of string \	null		null
`start`	string \	null		null
`end`	string \	null		null
`mode`	`summary` \	`rows`		`"summary"`
`max_rows`	integer		`100`	Rows per page (capped by the server). (>= 1; <= 5000)
`offset`	integer		`0`	Rows to skip within the time window. (>= 0)
`qc_max`	integer \	null		null
`qc_min_fraction`	number \	null		null
`to_utc`	boolean		false	Add UTC timestamps (offset from the site's BIF).
`view`	`full` \	`subset`		`"full"`

Result fields (besides the common envelope)

Field	Type	Description
`fileInfo`	FileInfo
`columns`	array of ColumnSummary
`rowColumns`	array of string \	null
`rows`	array of array of number \	string \
`scan`	ScanInfo
`page`	Page \	null

amf_read_bif¶

Read a local BADM (BIF) file. Read a local BADM Interchange Format file, the site metadata shipped in BASE-BADM (xlsx) and AmeriFlux FLUXNET (CSV) downloads, also from inside the zip: entries by group (location, IGBP, team, instruments, disturbance …), UTC offsets with their start dates, the DOI and citation recorded for that version, and funding acknowledgments. Emails and addresses are withheld by default. stdio only. Next: call amf_get_citation for the current citation.


Surface	`local`
Download identity	not needed
Transports	stdio
Annotations	readOnly=true, destructive=false, idempotent=true, openWorld=false
Upstream endpoints	none

Inputs

Name	Type	Required	Default	Description
`file`	string \	null		null
`site`	string \	null		null
`groups`	array of string \	null		null
`site_id`	string \	null		null
`include_contacts`	boolean		false	Emails and addresses, if the server allows it (privacy settings).
`limit`	integer		`100`	>= 1; <= 500
`offset`	integer		`0`	>= 0

Result fields (besides the common envelope)

Field	Type	Description
`fileInfo`	BifFileInfo
`entries`	array of BifEntryOut
`utcOffsets`	array of UtcOffsetOut
`citations`	array of BifCitation
`acknowledgments`	array of BifAcknowledgment
`withheld`	integer	Personal values withheld (emails, addresses, land owners).
`page`	Page

amf_search_sites¶

Search AmeriFlux and FLUXNET sites. Find flux tower sites in the AmeriFlux (856), FLUXNET2015 (212) and FLUXNET-CH4 (81) catalogs by words, place (bbox or near a point), IGBP ecosystem, Köppen climate, country/state, status, member network (NEON, LTER, ...), data product and policy, years with data, measured variables or gas species. Returns compact site summaries with years per product, facets over all matches, and paging. Next: call amf_get_site for one site or amf_get_availability for exact years.


Surface	`discovery`
Download identity	not needed
Transports	http, stdio
Annotations	readOnly=true, destructive=false, idempotent=true, openWorld=true
Upstream endpoints	`GET amfcdn.lbl.gov/api/v2/site_info_display/AmeriFlux` `GET amfcdn.lbl.gov/api/v1/site_display/FLUXNET/FLUXNET2015` `GET amfcdn.lbl.gov/api/v1/site_display/FLUXNET/FLUXNET-CH4`

Inputs

Name	Type	Required	Default	Description
`query`	string \	null		null
`collection`	`ameriflux` \	`fluxnet2015` \	`fluxnet_ch4` \	`all`
`product`	string \	null		null
`policy`	string \	null		null
`igbp`	array of string \	null		null
`koeppen`	array of string \	null		null
`country`	array of string \	null		null
`state`	array of string \	null		null
`status`	`active` \	`inactive` \	`any`
`network`	array of string \	null		null
`bbox`	array of number \	null		null
`near`	Near \	null		null
`years`	string \	null		null
`min_years`	integer \	null		null
`base_variable`	array of string \	null		null
`gas`	array of string \	null		null
`sort`	`site_id` \	`name` \	`years` \	`distance` \
`limit`	integer		`25`	>= 1; <= 200
`offset`	integer		`0`	>= 0

Result fields (besides the common envelope)

Field	Type	Description
`sites`	array of SiteSummary
`facets`	Facets	Counts over every match, not just this page.
`page`	Page

amf_search_variables¶

Search the FP Standard and FLUXNET variable dictionaries. Find variable names in the FP Standard list (AmeriFlux BASE, live, with QA/QC ranges) and the FLUXNET dictionaries (AmeriFlux FLUXNET from ONEFlux v1.3; FLUXNET2015 FULLSET and SUBSET), by words, category or resolution. FLUXNET units change with resolution (NEE is umol m-2 s-1 at HH, gC m-2 d-1 at DD), so each result lists units per resolution and SUBSET membership. Next: call amf_describe_variables on the names.


Surface	`variables`
Download identity	not needed
Transports	http, stdio
Annotations	readOnly=true, destructive=false, idempotent=true, openWorld=true
Upstream endpoints	`GET amfcdn.lbl.gov/api/v1/fp_var`

Inputs

Name	Type	Required	Default	Description
`query`	string \	null		null
`dictionary`	`fp` \	`fluxnet` \	`fluxnet_fullset` \	`fluxnet_subset` \
`category`	string \	null		null
`resolution`	string \	null		null
`limit`	integer		`25`	>= 1; <= 200
`offset`	integer		`0`	>= 0

Result fields (besides the common envelope)

Field	Type	Description
`variables`	array of VariableSummary
`facets`	VariableFacets
`page`	Page