neon-mcp

Overview Schema Source Related Servers Score Discussions Admin

List NEON data files

neon_list_files

Read-onlyIdempotent

List NEON data files for a product across sites and months, including file metadata, sizes, MD5s, and signed URLs. Filter by file kind, table, or name, and get summary counts or availability.

Instructions

Data files for a product at sites over months (NEON API token required): names, kinds, tables, HOR/VER/TMI, sizes, MD5s and signed URLs (~7 days), plus package ZIP links for a single site-month. detail='summary' or 'site_months' sizes a pull without listing files. Next: call neon_download_files with the same selectors (stdio), or use the URLs.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`hor`	No	Horizontal index, e.g. 000.
`tmi`	No	Temporal index in minutes, e.g. 030.
`ver`	No	Vertical index, e.g. 010.
`kind`	No	data, variables, readme, sensor_positions, eml, ... or package.
`limit`	No
`table`	No	Table name, e.g. 2DWSD_30min or brd_countdata.
`detail`	No	files (default), site_months (one row per site-month), summary (totals only).	files
`offset`	No
`package`	No	basic (default) or expanded.	basic
`product`	Yes	Product code or name.
`release`	No	Only files in this release (default: latest per month).
`filename`	No	One exact NEON file name (single site and month): its URL.
`end_month`	No	Last month (YYYY-MM); defaults to start_month.
`site_codes`	Yes	Site codes or names (up to 30).
`start_month`	Yes	First month (YYYY-MM).
`include_urls`	No	Include signed URLs (valid ~7 days; they dominate result size).
`name_contains`	No	Substring the file name must contain.
`include_provisional`	No	Include PROVISIONAL (unreleased) months.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`page`	No
`files`	No
`notes`	No
`detail`	Yes
`source`	No
`window`	Yes
`package`	Yes
`release`	No
`summary`	Yes
`curlHint`	No
`packages`	No
`resolved`	No
`nextSteps`	No
`siteCodes`	Yes
`siteMonths`	No
`urlsElided`	No
`productCode`	Yes
`externalData`	No
`urlExpiresAt`	No
`includeProvisional`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 10, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnly/idempotent annotations, it discloses that a NEON API token is required, that signed URLs are valid for about 7 days, and that package ZIP links are only for a single site-month. It also reveals response-shaping behavior through the detail parameter, which is valuable non-obvious context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences convey scope, output contents, authentication, URL expiry, response-size alternatives, and the downstream download tool. There is no filler, and the core purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 18-parameter tool with a rich output schema and readOnly/idempotent annotations, the description provides the essential missing context: token requirement, URL behavior, detail modes, and the recommended follow-up tool. Nothing critical is left unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 89%, so the schema already documents most parameters. The description adds extra meaning for detail ('sizes a pull without listing files'), include_urls ('signed URLs ~7 days'), and package ZIP links, going beyond what the parameter descriptions alone convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: listing NEON data files for a product across sites and months, and enumerates the returned fields (names, kinds, tables, HOR/VER/TMI, sizes, MD5s, signed URLs, ZIP links). It is clearly distinct from the 'download' sibling and from site/product metadata lookup tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear workflow context: list first, then either call neon_download_files with the same selectors or use the returned URLs. It also explains when to use detail='summary' or 'site_months' to size a pull. It stops short of naming when this tool should not be used versus other siblings, so it is not a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.