Гидрологические данные для ИИ-агентов. Уровень реки, расход воды, прогнозы наводнений, качество воды, водосборные бассейны и спутниковая высота водной поверхности — из USGS, NOAA и SWOT. Каждое значение несёт свою единицу измерения, датум, от которого оно отсчитано, часовой пояс и пометку о том, является ли запись предварительной или утверждённой.
mcp-name: io.github.Adeniyikayodee/gagelink
Пре-альфа. API будет меняться.
{
"mcpServers": {
"gagelink": {
"command": "uvx",
"args": ["--from", "gagelink", "gagelink-mcp"]
}
}
}Для запуска аккаунт не нужен. Бесплатный ключ с api.waterdata.usgs.gov/signup повышает лимит с 50 запросов в час до 1000; задайте его как GAGELINK_API_KEY.
Или как библиотека:
pip install gagelinkRelated MCP server: mcp-usgs-water-data
Насколько высок уровень реки на гидропосту и как это соотносится с уровнем затопления?
Каков запас высоты между водой и обследованным гребнем дамбы?
Каков расход сейчас и какую долю от рекордного пика он составляет?
Каков прогноз на ближайшие дни и пересекает ли он категорию наводнения?
Что находится выше или ниже по течению от этой точки вдоль реки?
Насколько велик бассейн, стекающий к этой точке?
Что записала эта станция за диапазон дат и была ли эта запись пересмотрена с тех пор?
Какова высота водной поверхности реки, на которой нет гидропоста?
Является ли показание предварительным или утверждённым и насколько оно свежее?
Высота гидропоста измеряется от собственного датума станции, а не от уровня моря. Вычитание одной из обследованной высоты даёт число, которое выглядит как запас высоты, но ошибочно на десятки футов, причём в сторону признания дамбы безопасной. Обе величины — длины в футах, поэтому ничто размерное их не разделяет, и ни одна библиотека единиц не поймает эту ошибку.
Этот пакет отказывается от такого вычитания, а не отвечает на него, и describe_location возвращает смещение, которое делает операцию корректной. То же самое относится к спутниковым высотам, которые отсчитываются от геоида, и к модельным расходам, за которыми может не стоять никаких измерений.
Водные сервисы уже публикуют всё необходимое для корректного использования своих данных. Расход указывает свою единицу, уровень — датум, от которого он измерен, показание — предварительное оно или утверждённое, а временная метка — своё смещение. Клиенты обычно извлекают число и отбрасывают остальное, и ошибки следуют из этого.
Сбой измерим. В бенчмарке из 4 288 прогонов на одиннадцати моделях quantity-guard обнаружил, что каждая модель, дошедшая до вычислительного инструмента, отправляла расход, опубликованный в кубических футах в секунду, в параметр, объявленный в кубических метрах в секунду, без пересчёта, почти в каждом прогоне, давая ответ в 35,3 раза больше, и ничто в выводе не указывало на это. Семь из одиннадцати вычитали уровень на локальном датуме гидропоста из высоты на NAVD88 и сообщали результат как запас высоты.
gagelink извлекает данные с сохранёнными метаданными и использует quantity-guard для их соблюдения при вызовах инструментов агента.
from gagelink import Service
service = Service(api_key="...") # free key, see below
page, retrieval = service.items(
"latest-continuous",
monitoring_location_id="USGS-07374000",
parameter_code="00060",
)
retrieval.record() # what a replay needs: url, params, time, status, sha256
retrieval.quota # Quota(limit=1000, remaining=999)items возвращает разобранную страницу и запись о её получении вместе, а не только страницу, потому что число, дошедшее до ответа без запроса, который его породил, невозможно воспроизвести, а связывание их в единственной точке входа дешевле, чем помнить о записи.
Полезные нагрузки становятся величинами, несущими собственные системы отсчёта:
from gagelink import location_from, readings_from
page, _ = service.items("monitoring-locations", id="USGS-06730500")
station = location_from(page["features"][0])
station.register() # its datum, and the offset where one is published
observations, _ = service.items("latest-continuous", monitoring_location_id=station.id)
readings = {r.parameter_code: r for r in readings_from(observations, station)}
readings["00060"].value # Q(1.35 ft³/s (provisional))
readings["00065"].value # Q(9.11 ft (GAGE:06730500, provisional))
readings["00065"].value.to_datum("NGVD29") # Q(4869.11 ft (NGVD29, provisional))
readings["00065"].value.to_datum("NAVD88") # DatumConversionUnavailableПоследняя строка и есть суть. Boulder Creek публикует свою высоту на NGVD29, поэтому уровень там разрешается на NGVD29 и отказывается от NAVD88, поскольку смещение между ними меняется в зависимости от местоположения и здесь не публикуется. Предполагать современный датум только потому, что он современный, — это ошибка запаса высоты на один шаг раньше той, которую все ищут.
altitude и drainage_area возвращаются как голые числа, и схема коллекции не указывает единицу ни для одного из них, поэтому соглашения USGS о футах и квадратных милях применяются в normalise.py, где они видны, а не предполагаются дальше по конвейеру.
Единица без сопоставления отвергается, а не угадывается. Единица, которую pint может разобрать, но для которой в этом пакете нет записи, пропускается с предупреждением, потому что разбираемость — не то же самое, что понимание: ppt для pint читается как частей на триллион, а для USGS означает частей на тысячу, что даёт коэффициент 10^9 между двумя размерно идентичными показаниями.
Отсутствующее значение здесь — null, а не -999999, который публикует WaterServices, и оно остаётся отсутствующим. Квалификатор объясняет причину: ["EQUIP"] — для сбоя оборудования.
Утверждение приходит как Provisional или Approved, а не как P или A, и коды состояния оцениваются ниже их статуса проверки, поэтому утверждённая запись измерения, подверженного льду, оценивается как непроверенная, а не как утверждённая.
Часовой пояс станции определяется из аббревиатуры вместе с флагом перехода на летнее время, поскольку MST без летнего времени — это Аризона, а MST с ним — Колорадо, и они различаются на час в течение восьми месяцев в году.
Сессия хранит состояние для одного вопроса и запись о том, что на него ответило. Инструменты возвращают результат, а не вызывают исключение, потому что сбой, несущий исправление, удерживает модель в разговоре, где она может себя поправить, а выброшенное исключение завершает ход.
from gagelink import Session, Toolkit
with Session(question="How high is the Potomac at Little Falls?") as work:
kit = Toolkit(work)
kit.describe_location("USGS-01646500")
kit.get_latest("USGS-01646500", parameters=["00060", "00065"], max_age_hours=6)
work.audit("The gage height is 3.02 ft and the discharge is 2960 ft3/s.")
work.manifest()Каждое значение уходит со своей привязкой, и каждое заносится в журнал, так что ответ можно проверить по тому, что было фактически получено:
[ok] 3.02 ft from get_latest.00065
[ok] 2960 ft3/s from get_latest.00060
[UNSOURCED] 116000 ft3/s no tool output produced this valueТретья строка — это проверка, оправдывающая своё существование. Цифра — правдоподобный расход для этой реки, она неверна, и ничто в предложении, содержащем её, не указывает на это.
Ряд возвращается как дескриптор с сводкой и выборкой из двадцати точек, а не сами точки, поскольку год 15-минутных записей — это 35 000 значений. Дескриптор выводится из запроса, который его породил, так что повторное воспроизведение той же сессии даёт тот же дескриптор. Результаты ограничены бюджетом, и всё, что отброшено для соблюдения бюджета, указывается в результате, поскольку молчаливое усечение читается как полнота покрытия.
инструмент | назначение |
| поиск по штату, округу, гидрологическому участку, типу объекта или ограничивающей рамке |
| метаданные, датум, часовой пояс и смещение, необходимое для уровня |
| самое свежее значение по параметру, с возрастом и качеством |
| диапазон дат, как дескриптор плюс сводка |
| сузить сохранённый ряд без повторного запроса |
| ежегодный рекорд пиковых расходов |
| наблюдаемый и прогнозируемый уровень, с порогами затопления |
| пункты мониторинга выше или ниже по течению вдоль реки |
| площадь, стекающая к точке |
| разрешить код параметра, поскольку показания не несут названия |
export GAGELINK_API_KEY=... # free, see below
gagelink-mcp{"mcpServers": {"gagelink": {"command": "gagelink-mcp"}}}Одиннадцать инструментов, не больше. Модель деградирует по мере роста списка инструментов, поэтому поверхность организована по глаголам, а выбор того, какой сервис отвечает, делает сервер, а не возлагается на вызывающего.
Описания инструментов — часть продукта, а не документация к нему. В оценке quantity-guard объявление физических метаданных в схеме без их соблюдения всё равно восстановило треть прогонов, которые провалились на исходном уровне, так что то, что описание говорит о датумах, единицах и предварительных записях, работает до запуска любой проверки.
Сбой инструмента возвращается как контент, помеченный как ошибка, а не как протокольный сбой, что удерживает исправление перед моделью вместо завершения хода. Сессия сбрасывается при initialize, поэтому величины одного разговора не могут появиться в манифесте другого.
python demo/freeboard.py запускает всё это офлайн на записанных ответах:
stage 3.02 ft (GAGE:01646500)
crest 41 ft (NAVD88)
The two are both lengths, so nothing dimensional separates them:
refused: cannot difference an elevation on NAVD88 against one on GAGE:01646500
The gage's zero is at 37.04 ft NAVD88, so the stage is 40.06 ft (NAVD88).
freeboard = 0.94 ft
Ignoring the datum gives 37.98 ft of margin where 0.94 ft is correct,
overstating it by a factor of 40.Уровень и обследованная высота — обе длины в футах, и вычитание одной из другой даёт число, которое выглядит как запас высоты. Ошибка молчалива, она действует в сторону сообщения о дамбе как безопасной, и никакая библиотека единиц её не предотвращает, потому что с единицами всё в порядке.
Пороги затопления берутся из NOAA National Water Prediction Service, поскольку уровень ничего не значит, пока его не сопоставят с уровнем, при котором река выходит из берегов. В этой полезной нагрузке есть три вещи, требующие обработки, и ни одна не обозначена:
Расход появляется как cfs в категориях затопления и как kcfs в блоке статуса того же ответа, поэтому вызывающий, читающий оба и относящийся к ним одинаково, ошибается в тысячу раз.
Пороги, которые никогда не были установлены, публикуются как -9999, а не опускаются. Это размерно допустимо, правдоподобно по знаку и проходит все проверки ниже по конвейеру, поэтому оно читается как sentinel, которым и является.
Уровни отсчитываются от собственного датума гидропоста, а не от национального. Наблюдаемый уровень, опубликованный там, точно совпадает с параметром USGS 00065 на той же станции и в то же время, что является доказательством этого чтения, и именно поэтому уровень затопления вычитается из высоты гидропоста, но не из обследованной высоты.
Навигация идёт вдоль реки, а не в пределах радиуса, и это различие делает ответ полезным: гидропост в двух милях на соседнем водосборе не является выше по течению ни для чего здесь. Направления — слова, а не двухбуквенные коды индекса, поэтому upstream включает притоки, а upstream_main следует только по главному руслу.
Бассейн приходит как полигон из пары тысяч пар координат. Это ответ на картографический вопрос и неправильный ответ на любой вопрос, который задаёт агент, поэтому полигон сохраняется, а его площадь, протяжённость и количество вершин сообщаются. Площадь вычисляется из полигона по линейно-интегральной форме сферической площади, которая не требует проекции и поэтому не имеет зоны, которую нужно выбирать или в которой можно ошибиться. Она согласуется с площадью водосбора, публикуемой USGS для единственной станции, где обе цифры существуют, с точностью до 0,06%, и результат говорит, что она вычислена, а не опубликована, поэтому её не цитируют против обследованной цифры, как будто они одинаковы.
Гидрология воспроизводится на 1,6% в протестированной литературе. Обычное объяснение — что данные и код не были опубликованы, и оно скрывает более интересный сбой: опубликованный конвейер против живого сервиса тоже не воспроизводится, потому что сервис пересмотрел запись под ним. Предварительный расход становится утверждённым, и число меняется.
Сессия сохраняет пакет из своего манифеста и тел ответов, которые она видела. Его воспроизведение работает в трёх режимах, и различие между ними и есть суть.
режим | процедура | изолирует |
| пересчёт из архивных тел | изменения кода и библиотек |
| повторный запрос, требование идентичных ответов | любой дрейф вообще |
| повторный запрос, сравнение, запрос к сервису объяснить каждое различие | пересмотр данных |
with Session(question="what was the discharge in mid May 2021?") as work:
Toolkit(work).get_series("USGS-02344872", "00060", "2021-05-16", "2021-05-20")
work.save("bundle.json")gagelink-replay bundle.json --mode strict
gagelink-replay bundle.json --mode revision_awareТот же пакет, тот же повторный запрос и два разных вердикта:
strict replay: changed
changed daily
[changed] USGS-02344872 00060 at 2021-05-16: 702.1 -> 826.0 ft^3/s
revision_aware replay: reproduced
changed daily
[revised] USGS-02344872 00060 at 2021-05-16: 702.1 -> 826.0 ft^3/s,
Revisions: Discharge for the period May 16, 2021 to Oct. 27, 2021,
was revised on Aug. 16, 2024, based on changes to the estimated discharge.Результат, который изменился, потому что агентство пересмотрело 400 предварительных значений, — это иной факт о науке, чем тот, который изменился, потому что изменился код, и в остальном они неразличимы. Запись о пересмотре берётся из собственной коллекции time-series-revisions сервиса и соединяется по идентификатору временного ряда, который уже несёт в себе чтение, так что атрибуция — это поиск, а не догадка. Различие без опубликованной записи о пересмотре остаётся в отчёте как необъяснённое — именно это не даёт проверке стать пустой.
Тела проверяются по их хэшам, прежде чем что-либо сравнивается. Пакет, чей архив не совпадает, отклоняется, а не воспроизводится, поскольку каждый вердикт опирается на то, что архив — это именно то, что видел сеанс.
bench/ — это бенчмарк, измеряющий, чего стоит инструментарий для модели, на девяти задачах на одной станции, охватывающих девять опасностей, каждая из которых наблюдалась в live-нагрузке сервиса, пока пакет собирался.
Три условия сравниваются на идентичных данных, различаясь только интерфейсом между моделью и байтами:
условие | что получает модель |
| один fetch-инструмент, возвращающий собственный JSON сервиса — то, что есть у разработчика сегодня |
| одиннадцать инструментов с результатами, урезанными до голых величин, и без примечаний |
| инструменты как есть, с единицами, датумами, качеством, устареванием и примечаниями |
Среднее условие — это то, что делает измерение значимым. Без него различие между первым и последним показало бы лишь, что структурированное извлечение бьёт сырой JSON, в чём никто не сомневается. Разница между последними двумя — это то, чего стоит сама метаданные.
python -m bench --dry-run # no provider, no spend
python -m bench --model anthropic/claude-opus-5 --replicates 4Каждый ожидаемый ответ выводится из тех же записанных ответов, которые обслуживает сервис, а tests/test_bench.py решает каждую задачу на основе этих ответов и сверяет результат с заявленным ответом. Задача, к ответу которой так не подобраться, — это сломанная задача, и это видно сразу. Каждая задача также фиксирует basis — указание, откуда взята её цифра, чтобы читатель мог проверить её, не полагаясь на слово проекта.
Задача о запасе над водой проверяется по собственной арифметике агентства: USGS публикует отметку водной поверхности как параметр 63160, на высоте 40.07 фута над NAVD88, что равно высоте водомерного поста 3.03 фута плюс датумная поправка станции 37.04 фута.
Оценка записывается до любого прогона и хранится в системе контроля версий, так что правило нельзя подогнать после того, как увидел результат, который ему не угоден.
gpt-oss-120b, девять задач, три условия, восемь повторов, 216 прогонов, $0.09.
условие | верно |
| 61/72 |
| 63/72 |
| 70/72 |
Правильность учитывает каждый прогон, включая те восемь, что завершились без ответа вовсе. Семь из них относятся к http_only на двух задачах, чья сырая запись достигает 42 000 и 50 000 токенов в запросе, где модель вырождается в повторение числа вместо ответа. Эти сбои вызваны условием, так что, исключив их, мы зачли бы сырому JSON то, что разрушил его собственный размер нагрузки.
Набор сидит на потолке в шести задачах из девяти — и это вывод о самом наборе. Где он разделяет:
задача |
|
|
|
| 3/8 | 8/8 | 8/8 |
| 6/8 | 8/8 | 8/8 |
| 8/8 | 1/8 | 7/8 |
На двух задачах с длинной записью медианный запрос составлял 49 864 и 42 006 токенов через сырой JSON против 5 384 и 2 384 через инструментарий. На задаче с непрозрачной единицей, сняв опорные кадры, модель отправила семь из восьми прогонов в записанную ловушку, ответив расходом USGS 3010 ft³/s вместо прогнозных 2.95 kcfs.
Инструментарий не бьёт сырой JSON по точности в целом. Разрыв почти полностью обусловлен двумя задачами, где сырая нагрузка не помещается. Восемь из 27 ячеек разделены по повторам, так что различия менее чем в два прогона из восьми не разделяются этой схемой, и одна модель — это одна модель.
Сервис разрешает 50 запросов на IP в час без аутентификации и 1000 в час с ключом, который бесплатен на api.waterdata.usgs.gov/signup. Один вопрос агента, сравнивающий условия на пяти станциях, обходится примерно в 15–25 запросов, так что кэширование — это несущая нагрузка, а не оптимизация, и ответы кэшируются на время жизни процесса по умолчанию.
Оставшийся лимит читается из заголовка X-RateLimit-Remaining в каждом ответе и переносится в запрос, так что агенту видно, сколько у него осталось, а не приходится обнаруживать предел, провалившись.
Ключ передаётся в заголовке X-Api-Key и никогда не появляется в записанном URL, поскольку манифест должен оставаться публикуемым.
USGS выводит из эксплуатации семейство API WaterServices, с плановым отключением в первом квартале 2027 года и возможной деградацией со второй половины 2026-го. gagelink нацелен только на замену — api.waterdata.usgs.gov/ogcapi/v0. Одно из следствий, которое стоит назвать, — коллекция time-series-revisions, публикующая изменения и удаления в утверждённой записи; именно она позволит воспроизвести, изменился ли ответ из-за того, что агентство пересмотрело измерение, или из-за того, что изменился код.
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytestСетевой доступ идёт через заменяемый fetch, так что набор запускается на записанных ответах, и ни одному тесту не нужна сеть.
MIT
Metadata for one monitoring location: its name, position, drainage area, timezone, and the vertical datum its stage readings are measured from. Call this before comparing any stage against an elevation, because the answer depends on the offset it returns.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the returned offset is critical for comparisons, which is a useful behavioral note. However, it does not mention other aspects like whether the operation is read-only (though implied) or any error conditions. Given the context, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, the first lists the output fields and the second gives a use case. No filler or repetition; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no output schema, and no annotations, the description covers the core purpose and a key dependency (offset). It omits specifics about the identifier parameter, but overall it is reasonably complete for the tool's simplicity, earning a 4.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'identifier' with 0% coverage in the description. The description implies 'identifier' selects a location but does not explain its format, how to obtain it, or any constraints. Since the schema provides no detail, the description should compensate, but it does not go beyond a vague implication, warranting a score of 2.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns metadata for a monitoring location, enumerating the specific fields (name, position, drainage area, timezone, vertical datum). This distinguishes it from sibling tools like get_series or get_forecast, which focus on data retrieval rather than metadata. The verb 'describe' is implicit but well-understood.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises calling this before comparing stage against elevation, providing a concrete use case. It does not mention when not to use it or alternatives, but the guidance is specific and actionable, earning a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The record of this session: every request made, every quantity returned, and the library versions. Enough to re-run the work and check the numbers. Call it last when the answer needs to be reproducible.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It details what is included (requests, results, library versions) and that it enables re-running, but it does not clarify whether the tool is read-only, destructive, or if any side effects occur. For a simple export, it could be more explicit about being safe to call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with clear, front-loaded purpose and a separate usage instruction. No filler. The second sentence could be tightened but is still compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description adequately explains its purpose and when to use it. It does not explain return format, but that's less critical since the tool is about creating a manifest and the description states what the manifest includes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so no parameter details are needed. The description's content is consistent with the schema, and the baseline for 0 params is 4. It implies expecting no arguments by not mentioning any.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a manifest of the session (requests, quantities, library versions) and explains it enables re-running and checking numbers. This distinguishes it from the sibling data-access tools, which focus on specific data retrieval rather than session metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Call it last when the answer needs to be reproducible', giving precise guidance on when to use this tool (at the end, for reproducibility) and implicitly when not to use it. This is direct and actionable for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search USGS monitoring locations by state, county, hydrologic unit, site type, or bounding box. At least one filter is required. Returns identifiers of the form USGS-01646500, which every other tool takes.
| Name | Required | Description | Default |
|---|---|---|---|
| bbox | No | west,south,east,north in decimal degrees | |
| limit | No | ||
| state | No | Full state name, as in Maryland | |
| county | No | Full county name | |
| site_type | No | As in Stream, Lake, Well | |
| hydrologic_unit_code | No | HUC, any level |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It reveals a key constraint ('At least one filter is required') and explains the output format ('Returns identifiers of the form USGS-01646500, which every other tool takes'). It does not mention the limit parameter or potential errors, but the key behaviors are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long. The first sentence is front-loaded with the verb and resource, listing criteria. The second sentence highlights a key constraint and the output format. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, no output schema, no annotations), the description is fairly complete. It specifies the search dimensions, the required-filter rule, and the form of returned identifiers. It does not describe the full response structure (e.g., whether additional metadata is returned), but for a search tool this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for 5 of 6 parameters (83% coverage), so the baseline is 3. The description reinforces those same filters and adds the crucial constraint that at least one filter is required. However, it does not explain the 'limit' parameter beyond the schema's default, and it adds little semantic information beyond what the schema already contains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Search USGS monitoring locations by state, county, hydrologic unit, site type, or bounding box.' This includes a specific verb and resource, and the variety of search criteria distinguishes it from sibling tools like describe_location or get_series.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'At least one filter is required' provides a clear constraint for usage. The statement 'Returns identifiers of the form USGS-01646500, which every other tool takes' implies this is the entry point for other tools, giving context on when to use it. It does not explicitly list alternative tools for different search needs, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The area draining to a point. The area is computed from the delineated boundary rather than published; where a site record also states a drainage area, that figure is surveyed and is the one to quote.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It does reveal that the area is computed from a delineated boundary rather than published, and that in cases where a surveyed figure exists, that is the one to quote. This is useful nuance that helps the agent interpret results but does not cover other behaviors like output format or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences and 36 words, which is appropriately brief. However, the first sentence is more of a definition than a functional explanation, and the second sentence could be clearer. Still, no filler words are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having a single parameter and no output schema, the description is insufficient. It does not explain what 'identifier' refers to, what the returned data looks like, or how this ties into the hydrological domain. Sibling tools suggest a complex system, but this tool's description leaves out critical details an agent would need to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'identifier' with no description, and schema description coverage is 0%. The description does not mention the parameter at all, leaving the agent without any clue about what value to supply (e.g., a station ID? coordinates?). This is a critical gap that the description needed to address.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'The area draining to a point' defines a watershed but does not clearly state the tool's action (e.g., 'get' or 'retrieve'). It fails to specify that the tool returns the basin for a given identifier, leaving the purpose ambiguous. The second sentence adds detail about computation but not what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus siblings like get_latest or get_series. The description does not mention prerequisites, typical use cases, or alternatives. The only context is a note about 'where a site record also states a drainage area,' but it stops short of explaining when to call this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Observed and forecast stage from the NOAA National Water Prediction Service, with the flood thresholds that give them meaning. Stages and thresholds here are on the gage's own datum, so they can be differenced against each other and against a gage height, but not against a surveyed elevation without the offset from describe_location. Takes the USGS identifier or the NWS location id.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses a critical non-obvious behavior: stages are on the gage's own datum and cannot be compared to surveyed elevations without the describe_location offset. This is valuable context beyond what the schema or annotations provide, though it stops short of describing output structure or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with the core purpose first, followed by the datum caveat and identifier types. Every sentence adds necessary information without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description covers the data source, datum semantics, accepted identifiers, and relationship to describe_location. It could be slightly stronger by indicating whether the result is a time series or single current values, but overall it is sufficient for tool selection and basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only specifies 'identifier' as required string with no description. The description adds meaning by explaining it accepts either a USGS identifier or an NWS location id, which is essential for correct invocation. It doesn't provide format examples or constraints, but the clarification is significant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns 'Observed and forecast stage from the NOAA National Water Prediction Service, with the flood thresholds that give them meaning.' This specific verb and resource, plus the mention of thresholds, distinguishes it from siblings like get_model_forecast or get_latest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need stage data on the gage's own datum) and references describe_location for surveyed elevation offsets, but it does not explicitly contrast this tool with get_model_forecast or other alternatives. No clear 'use this instead of X' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The most recent value the service holds for each parameter at a location. Latest is not the same as current: the service returns the last value it has for each parameter independently, so one response can carry a discharge from this morning beside a turbidity from years ago. Pass max_age_hours to drop the stale ones. Values arrive with their unit, datum, and whether the record is provisional or approved.
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes | ||
| parameters | No | Parameter codes, as in 00060 for discharge | |
| max_age_hours | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels: it reveals that the response is per-parameter independent snapshots, warns about the non-uniform timestamp issue with a concrete example, discloses that values include unit, datum, and provisional/approved status, and explains the effect of max_age_hours. This is far beyond what the schema alone indicates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each earning its place: the first states the core function, the second disambiguates the trickiest semantic trap, the third tells the agent how to control behavior, and the fourth describes the output envelope. The most critical caveat is front-loaded, and there is zero redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple three-parameter tool with no output schema or annotations, the description covers the key behavior dimensions: what values mean, how freshness is handled, and what extra fields come back. It could be more complete on what 'location' and 'identifier' mean and what happens if a parameter is not found, but those are minor for the described use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only 'parameters' has a schema description), so the description must compensate. It meaningfully clarifies max_age_hours ('drop the stale ones') and implies 'identifier' maps to a location, but it never elaborates on the 'identifier' parameter format or what codes 'parameters' takes beyond a passing example in the schema. It's adequate but leaves the two most important parameters under-specified in prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Uses a specific verb ('returns'), names the resource ('the most recent value the service holds for each parameter at a location'), and immediately distinguishes itself from a sibling concept ('Latest is not the same as current'), which clearly differentiates it from tools like get_series or get_model_forecast. The opening sentence alone fully answers what the tool does and scopes it to location/parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use the tool (when the latest per-parameter values are needed, not an aligned current-time view) and hints at when to use alternatives by warning that values can be non-contemporaneous ('a discharge from this morning beside a turbidity from years ago'). It names the 'max_age_hours' mechanism for handling staleness, which directs the agent toward appropriate invocation. However, it doesn't explicitly name an alternative sibling tool or give an explicit 'don't use if...' condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
National Water Model streamflow for the reach a monitoring location sits on. These are modelled values, not measurements: the model covers reaches with no gauge on them, so a figure here may have nothing observed behind it, and it carries no record-quality grade. Series are analysis_assimilation, which looks back, and short_range, medium_range, medium_range_blend, and long_range, which look forward. Not every reach publishes every series.
| Name | Required | Description | Default |
|---|---|---|---|
| series | No | short_range | |
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It discloses that data is modelled, may lack actual observations, carries no record-quality grade, explains the temporal direction of each series, and notes inconsistent availability. This is transparent and goes well beyond minimal requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-load the purpose, then provide essential caveats and series information. Every sentence adds value; no fluff or repetition. The structure is logical and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 simple parameters, no output schema), the description is remarkably complete: it covers data provenance, quality limitations, series types, and availability variability. It does not explain return format, but without an output schema, the description still gives enough for an agent to understand expected data. The rich context makes it self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the series parameter values with their look-back/forward nature, which adds meaning beyond the enum list. The identifier is implicitly linked to 'monitoring location', but no format or retrieval details are given. This partial compensation merits a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves National Water Model streamflow for a reach associated with a monitoring location. It emphasizes these are modelled values, contrasting with measurements, and lists the specific series types. This distinguishes it from generic forecast tools, though it does not explicitly name siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly indicates when to use the tool (for modelled streamflow forecast data) and provides important caveats ('modelled values, not measurements', 'not every reach publishes every series'). However, it does not explicitly name alternative sibling tools or provide direct 'when not to use' guidance, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Annual peak flow record for a location, largest first. A water year can carry more than one peak, so the count of peaks is not the count of years.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It adds behavioral insight by noting that a water year can have multiple peaks and that records are sorted largest first, which prevents misinterpretation. However, it does not disclose whether the operation is read-only, any side effects, or data freshness, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the main purpose and a key clarifying note. Every word adds value, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description must explain core behavior. It conveys the record type and sorting but omits details on output format, pagination, or parameter constraints. For a simple tool with two parameters, this is adequate but not rich enough to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It implies 'identifier' is a location but gives no detail on 'limit' or its default value (10). The description only hints at the required parameter, leaving the optional limit under-specified, which is insufficient for an agent to use the tool effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns an annual peak flow record for a location, sorted largest first. It distinguishes itself from sibling tools like get_series (time series) and get_latest (latest value) by specifying the peak flow nature and ordering, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for peak flow data but does not explicitly state when to use this tool over alternatives such as get_latest or get_series. No exclusions or comparisons are provided, so the guidance is implicit rather than clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Water surface elevation measured from orbit by the SWOT mission, for a river reach. Covers reaches no gauge stands on. Elevations are referenced to the EGM2008 geoid, not to a national datum and not to any gage datum, so they cannot be differenced against a stage or a surveyed elevation. A reach identifier is a SWORD river reach id and is not a USGS station number.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | ISO date | |
| start | Yes | ISO date | |
| feature_id | Yes | SWORD reach id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With NO annotations provided, the description carries full behavioral burden and exceeds expectations. It discloses the datum reference ('referenced to the EGM2008 geoid, not to a national datum and not to any gage datum'), issues a critical warning against misuse ('cannot be differenced against a stage or a surveyed elevation'), and clarifies identifier semantics ('SWORD river reach id and is not a US station number'). This prevents a whole class of subtle analysis errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, each earning its place: definition, coverage scope, and two critical caveats. No fluff or filler; every clause carries semantic weight. Could be marginally tightened but is well within the 'appropriately sized and front-loaded' bar.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only 3 simple parameters, no output schema, and no annotations, the description is remarkably complete. It covers purpose, coverage scope, datum references, cross-referencing caveats, and identifier format—addressing the highest-risk failure modes an agent could encounter when invoking this tool. Nothing material is left unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, establishing a baseline of 3. The description adds genuine value by elaborating on feature_id ('is a SWORD river reach id and is not a US station number'), preventing an easy mix-up. The start/end parameters are self-explanatory ISO date strings, so the datum caveat—not parameter elaboration—is where the description's energy is best spent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific resource ('Water surface elevation measured from orbit by the SWOT mission, for a river reach') and differentiates from sibling gauge-based tools by noting 'Covers reaches no gauge stands on.' This clearly distinguishes it from the gauge-data siblings like get_series and get_latest, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Covers reaches no gauge stands on' gives explicit situational context for when to choose this tool over alternatives (i.e., when the reach is ungauged). It doesn't name sibling tools explicitly like the calibration HIGH example, but the implication is strong and unambiguous in context of available siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A date range of record, returned as a handle with a summary and a small sample rather than as its points, since a year of 15-minute record is 35,000 values. Use slice_series on the handle to narrow it. Resolution is daily or continuous.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | ||
| start | Yes | ISO date, as in 2026-08-01 | |
| parameter | Yes | ||
| identifier | Yes | ||
| resolution | No | daily |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It reveals the behavior of returning a handle with a summary and sample, and mentions the 'resolution' option, which is helpful. However, it does not explain what happens with invalid identifiers or whether the handle expires, or any side effects. It also doesn't specify how the sample is selected or the exact format of the summary, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose, explains the handle behavior, gives a concrete example of data size, and points to a sibling tool. Every clause earns its place with no fluff, making it efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, no output schema), the description does a decent job of explaining the return type (handle) and the reason for it. However, it lacks details on error handling, pagination or limit of the sample, and how to use the handle with slice_series (e.g., passing it as an argument). Also, no mention of what happens if resolution is not specified, though the schema provides a default. These gaps are minor but could affect a smooth agent interaction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only start is described as ISO date), so the description must compensate. It adds meaning by explaining the 'resolution' parameter (daily or continuous) though not explicitly in the text, and the phrase 'a date range of record' implies start/end usage. It explains the high-level purpose of each parameter indirectly: identifier, parameter, start, end are standard, but it doesn't detail formats for identifier and parameter. The mention of 'resolution' via the tool's function is sparse, but the overall context helps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a date range of records, but returns a handle with a summary and sample rather than raw points. It distinguishes itself from siblings like slice_series and get_peaks by noting the handle usage, though it could be more explicit about the resource (series) and the verb (get). It is specific enough to understand the core purpose, but lacks a clear contrast with get_series versus other retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear when-to-use hint: use this for large date ranges to avoid overwhelming data, and explicitly mentions using slice_series on the handle to narrow it, which guides the agent toward the next step. However, it does not explicitly state when NOT to use it (e.g., for small ranges) or mention alternatives like get_latest for recent data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a parameter code to what it measures, or find a code by name. Readings carry a code and no name, so this is how 00065 becomes gage height.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that it can resolve in two directions (code to name, name to code) but does not mention any limitations, such as partial matches, case sensitivity, or whether it returns multiple results. There is no mention of output format or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary action, and includes a concrete example. Every word contributes value; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no enums, no output schema). The description covers the essential purpose and usage. However, it lacks details about the return type (e.g., list of matches, a single name) and any edge cases. Given the simplicity and lack of annotations, it is minimally complete but could be richer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the 'query' parameter. It does: 'Resolve a parameter code to what it measures, or find a code by name' implies that 'query' accepts either a code or a name. This adds meaning beyond the schema, but it lacks specifics like format (e.g., '00065' vs 'gage height') or case sensitivity. Given one parameter and some elaboration, a 3 is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: to resolve a parameter code to its measurement name or find a code by name. It uses a concrete example (00065 becomes gage height) and distinguishes it from other tools by focusing on parameter codes, not locations or series.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool: when you have a parameter code that lacks a name. It implies that other tools may return codes without names, but it does not explicitly contrast with sibling tools or state when not to use it. Still, the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Narrow a series already fetched under a handle and summarise what remains. Costs no request against the hourly allowance.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| start | No | ||
| handle | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It discloses an important behavioral fact: 'Costs no request against the hourly allowance.' It also indicates local handling by mentioning 'already fetched under a handle,' but it remains vague about whether it mutates the stored series and what shape the summary takes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences communicate purpose, precondition, and quota behavior with no filler. The first sentence front-loads the core verb and resource, and the second adds a concise behavioral guarantee.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with three parameters and no output schema, but the description still leaves ambiguity around the slice window (start/end) and the exact nature of the summary. It is adequate for basic orientation but not fully self-sufficient for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for start, end, and handle. It only explains that the series was retrieved under a handle, which gives some semantic weight to 'handle,' but says nothing about start/end roles, formats, or whether they are required. This is insufficient for a three-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific operation: narrow an already-fetched series under a handle and summarize what remains. The phrase 'already fetched under a handle' distinguishes it from sibling tools like get_series, which fetch new data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The precondition is clear: use it on a series already fetched under a handle rather than to fetch new data. The sentence 'Costs no request against the hourly allowance' gives a concrete reason for choosing it over network-fetching tools. It does not explicitly name alternatives, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0describe_locationexport_manifestfind_locationsget_basinget_forecastget_latestget_model_forecastget_peaksget_satellite_passesget_serieslookup_parameternavigate_networkslice_seriesScored across 13 tools
Most tools have clearly distinct resource/action boundaries, and the descriptions are specific. The main confusable pair is get_forecast and get_model_forecast, both involving forecasts, though their sources and outputs differ. At most one or two tools could cause a misselection here.
All names follow a consistent verb_noun snake_case pattern. get_* is used for retrieval-style operations, and describe_, find_, slice_, navigate_, lookup_, and export_ clearly mark other action types. The overlap in name between get_forecast and get_model_forecast is a semantic concern, not a naming-pattern violation.
Thirteen tools is a well-scoped size for a water-data domain. Each tool covers a distinct part of the workflow—searching, metadata, observations, series, peaks, forecasts, satellite data, network traversal, basin geometry, parameter lookup, and export——so no tool feels redundant or missing from the count perspective.
The set covers the main observational lifecycle well: discover locations, describe metadata, get latest values, get and slice time series, get peaks, get forecasts, navigate upstream/downstream, and resolve parameter codes. The main gap is that get_satellite_passes requires a SWORD reach identifier, but the toolkit has no way to discover or translate a USGS location into that identifier, leaving that tool somewhat isolated.
Real-time water levels and flow rates from USGS stream gauges
US weather & geo for AI agents: forecasts, alerts, earthquakes, elevation, geocoding. No keys.
US weather & geo for AI agents: forecasts, alerts, earthquakes, elevation, geocoding. No keys.
River levels & flood alerts: USGS gauges. $0.01/query. Register in-session — free testnet funds.