AI 에이전트를 위한 수문 데이터. 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회 요청 한도를 1,000회로 올려 줍니다. GAGELINK_API_KEY로 설정하세요.
또는 라이브러리로 사용:
pip install gagelinkRelated MCP server: mcp-usgs-water-data
수위표에서 강의 수위는 얼마이며, 홍수위와 어떻게 비교됩니까?
수면과 측량된 제방 정상 사이의 여유고는 얼마입니까?
지금 유량은 얼마이며, 기록상 최대 유량의 몇 분율입니까?
향후 며칠 동안의 예보는 어떠하며, 홍수 등급을 넘어섭니까?
이 지점의 상류 또는 하류에는 강을 따라 무엇이 있습니까?
이 지점으로 배수되는 유역의 크기는 얼마입니까?
이 관측소는 특정 날짜 범위 동안 무엇을 기록했으며, 그 기록이 이후에 수정되었습니까?
수위표가 없는 강의 수면 표고는 얼마입니까?
측정값이 잠정인지 승인된 것인지, 그리고 얼마나 오래된 것입니까?
수위표 높이는 해수면이 아니라 관측소 자체의 기준면에서 측정됩니다. 측량된 표고에서 이를 빼면 여유고처럼 보이는 숫자가 나오지만, 수십 피트만큼 틀리며 제방이 안전하다고 판단하는 방향으로 틀립니다. 두 값 모두 피트 단위의 길이이므로 차원적으로 구분되지 않아 어떤 단위 라이브러리도 이를 잡아내지 못합니다.
이 패키지는 그 뺄셈에 답하는 대신 거부하며, describe_location은 그 뺄셈을 잘 정의되게 만드는 오프셋을 반환합니다. 지오이드 기준인 위성 표고와 그 뒤에 측정값이 없을 수 있는 모의 유량에도 동일하게 적용됩니다.
수문 서비스는 데이터를 올바르게 사용하는 데 필요한 모든 것을 이미 공개합니다. 유량은 단위를 명시하고, 수위는 측정 기준면을 명시하며, 측정값은 잠정인지 승인인지 명시하고, 타임스탬프는 오프셋을 명시합니다. 클라이언트는 보통 숫자만 파싱하고 나머지는 버리며, 오류는 그로부터 발생합니다.
실패는 측정 가능합니다. 11개 모델에 걸친 4,288회 실행 벤치마크에서 quantity-guard는 컴퓨팅 도구에 도달한 모든 모델이 거의 모든 실행에서 초당 입방피트로 공개된 유량을 초당 입방미터로 선언된 매개변수에 변환 없이 보냈고, 출력에 이를 나타내는 아무것도 없이 35.3배나 큰 답을 냈다는 것을 발견했습니다. 11개 중 7개는 로컬 수위표 기준면의 수위를 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 배 차이입니다.
누락된 값은 WaterServices가 공개한 -999999 대신 여기서는 null이며, 누락된 상태로 유지됩니다. 한정자는 이유를 말해 주며, 장비 중단의 경우 ["EQUIP"]입니다.
승인 상태는 P 또는 A가 아니라 Provisional 또는 Approved로 제공되며, 조건 코드는 검토 상태보다 낮은 등급을 매기므로, 얼음의 영향을 받은 측정값의 승인된 기록은 승인됨이 아니라 미검증으로 등급이 매겨집니다.
관측소 시간대는 약어와 함께 일광 절약 시간 플래그로 결정됩니다. 일광 절약 시간이 없는 MST는 애리조나이고, 일광 절약 시간이 있는 MST는 콜로라도이며, 두 지역은 일 년 중 8개월 동안 한 시간 차이가 나기 때문입니다.
세션은 하나의 질문에 대한 상태와 그에 답한 기록을 보관합니다. 도구는 예외를 발생시키는 대신 결과를 반환합니다. 수정 방법을 담은 실패는 모델이 스스로 수정할 수 있는 대화에 머물게 하지만, 발생된 예외는 턴을 끝내기 때문입니다.
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세 번째 줄이 그 자리를 차지한 검증입니다. 그 수치는 그 강에 대해 그럴듯한 유량이며, 틀렸고, 그것을 포함한 문장에는 그 사실을 나타내는 아무것도 없습니다.
시계열은 포인트 자체가 아니라 요약과 20개 포인트 샘플이 포함된 핸들로 반환됩니다. 15분 간격 기록 1년은 35,000개 값이기 때문입니다. 핸들은 그것을 생성한 쿼리에서 파생되므로 동일한 세션을 재생하면 동일한 핸들이 생성됩니다. 결과에는 예산이 책정되며, 예산 안에 머물기 위해 버려진 모든 것은 결과에 명시됩니다. 조용한 절단은 완전한 커버리지로 읽히기 때문입니다.
도구 | 목적 |
| 주, 카운티, 수문 단위, 사이트 유형 또는 경계 상자로 검색 |
| 메타데이터, 기준면, 시간대, 수위에 필요한 오프셋 |
| 매개변수별 최신 값, 기간 및 품질 포함 |
| 날짜 범위, 핸들 및 요약으로 |
| 다시 가져오지 않고 저장된 시계열 좁히기 |
| 연간 최대 유량 기록 |
| 관측 및 예보 수위, 홍수 임계값 포함 |
| 강을 따라 상류 또는 하류의 모니터링 지점 |
| 한 지점으로 배수되는 면적 |
| 매개변수 코드 해석, 측정값에는 이름이 없으므로 |
export GAGELINK_API_KEY=... # free, see below
gagelink-mcp{"mcpServers": {"gagelink": {"command": "gagelink-mcp"}}}도구는 열한 개, 그 이상은 없습니다. 모델은 도구 목록이 길어질수록 성능이 저하되므로, API 표면은 동사별로 구성되며 어떤 서비스가 답할지의 선택은 호출자에게 맡겨지지 않고 서버가 결정합니다.
도구 설명은 제품의 문서가 아니라 제품의 일부입니다. quantity-guard 평가에서 스키마에 물리적 메타데이터를 선언하기만 하고 강제하지 않았을 때도 기준선에서 실패한 실행의 3분의 1이 회복되었습니다. 따라서 설명이 기준면, 단위, 잠정 기록에 대해 말하는 내용은 어떤 검증이 실행되기 전에 실제로 효과가 있습니다.
도구 실패는 프로토콜 오류가 아니라 오류로 표시된 콘텐츠로 반환되며, 이는 턴을 끝내는 대신 수정 방법을 모델 앞에 유지합니다. 세션은 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로 공개됩니다. 이는 차원적으로 유효하고 부호만 그럴듯하며 이후의 모든 검사를 통과하므로, 그것이 바로 센티널로 읽힙니다.
수위는 국가 기준면이 아니라 수위표 자체의 기준면에 있습니다. 거기에 공개된 관측 수위는 같은 관측소와 시간의 USGS 매개변수 00065와 정확히 일치하며, 이것이 그 측정값의 증거이고, 홍수위가 측량된 표고가 아니라 수위표 높이와 차분되는 이유입니다.
탐색은 반경 내가 아니라 강을 따라 이루어지며, 이 구분이 답을 유용하게 만듭니다. 다음 유역에 2마일 떨어진 수위표는 여기서 아무것도 상류에 있지 않습니다. 방향은 인덱스의 두 글자 코드가 아니라 단어이므로, 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/는 이 툴킷이 모델에게 얼마나 가치가 있는지 측정하는 벤치마크로, 한 관측소의 아홉 가지 작업을 다루며, 그 각각은 패키지가 빌드되는 동안 라이브 서비스 페이로드에서 관측된 아홉 가지 위험을 다룬다.
세 가지 조건이 동일한 데이터에서 비교되며, 모델과 바이트 사이의 인터페이스에서만 차이가 있다:
조건 | 모델이 받는 것 |
| 서비스 자체 JSON을 반환하는 하나의 가져오기 도구. 오늘날 개발자가 가진 것이다. |
| 결과가 단순한 크기로 축소되고 메모가 제거된 11개의 도구 |
| 단위, 기준면, 품질, 오래됨, 메모가 포함된 그대로의 도구 |
가운데 조건이 측정을 가치 있게 만드는 이유이다. 그것이 없으면 첫 번째와 마지막의 차이는 구조화된 검색이 원시 JSON을 이긴다는 것만 보여줄 뿐인데, 이는 누구도 의심하지 않는다. 마지막 두 개의 차이가 메타데이터가 그 자체로 얼마나 가치 있는지 보여준다.
python -m bench --dry-run # no provider, no spend
python -m bench --model anthropic/claude-opus-5 --replicates 4모든 기대 정답은 도구가 제공하는 것과 동일한 기록된 응답에서 파생되며, tests/test_bench.py는 그 응답들로 각 작업을 풀고 결과를 선언된 정답과 대조한다. 그렇게 도달할 수 없는 작업은 잘못된 작업이며, 그것이 드러나는 곳이다. 각 작업은 또한 수치가 어디서 왔는지 알려주는 근거를 기록하므로, 독자는 이 프로젝트의 말을 믿지 않고도 확인할 수 있다.
여유고(freeboard) 작업은 기관 자체의 산술로 확인할 수 있다. USGS는 수표고(water surface elevation)를 매개변수 63160으로 게시하며, 이는 40.07ft NAVD88로, 수위표 높이 3.03ft에 관측소의 기준면 오프셋 37.04ft를 더한 값이다.
점수 산정은 어떤 스윕이 실행되기 전에 작성되어 버전 관리에 있으므로, 불리한 결과를 본 후에 규칙을 조정할 수 없다.
gpt-oss-120b, 9개 작업, 3개 조건, 8회 반복, 216회 실행, $0.09.
조건 | 정답 |
| 61/72 |
| 63/72 |
| 70/72 |
정확도는 모든 실행을 세며, 전혀 답을 내지 못한 8개도 포함한다. 그중 7개는 원시 레코드가 42,000개와 50,000개의 프롬프트 토큰에 달하는 두 작업에서 http_only에 속하는데, 모델이 답하는 대신 숫자를 반복하는 것으로 퇴화한다. 이러한 실패는 조건 때문에 발생하므로, 이를 제외하면 자체 페이로드 크기로 인해 망가진 실행에 대해 원시 JSON을 인정하는 셈이다.
이 스위트는 9개 작업 중 6개에서 상한에 도달하는데, 이는 스위트 자체에 대한 발견이다. 차이가 나는 부분은 다음과 같다:
작업 |
|
|
|
| 3/8 | 8/8 | 8/8 |
| 6/8 | 8/8 | 8/8 |
| 8/8 | 1/8 | 7/8 |
두 개의 긴 레코드 작업에서 중앙값 프롬프트는 원시 JSON을 통해서는 49,864개와 42,006개 토큰이었지만, 툴킷을 통해서는 5,462개와 2,384개였다. 불투명한 단위 작업에서는 기준 프레임을 제거하자 8번의 실행 중 7번이 기록된 함정에 빠져 예보 서비스의 2.95kcfs 대신 USGS 유량인 3010ft³/s로 답했다.
툴킷은 일반적으로 정확도에서 원시 JSON을 이기지 못한다. 그 격차는 거의 전적으로 원시 페이로드가 들어맞지 않는 두 작업에 의해 주도된다. 27개 셀 중 8개가 반복으로 나뉘므로, 8회 중 약 2회 미만의 차이는 이 설계로 구분되지 않으며, 한 모델은 하나의 모델일 뿐이다.
이 서비스는 인증 없이 IP당 시간당 50개의 요청을 허용하고, 키를 사용하면 시간당 1,000개를 허용하며, 이는 api.waterdata.usgs.gov/signup에서 무료로 제공된다. 5개 지점의 조건을 비교하는 단일 에이전트 질문은 약 15~25개의 요청이 필요하므로, 캐싱은 최적화라기보다는 부하를 견디는 역할을 하며, 응답은 기본적으로 프로세스 수명 동안 캐시된다.
남은 허용량은 모든 응답의 X-RateLimit-Remaining에서 읽혀 검색에 전달되므로, 에이전트는 실패함으로써 한계를 발견하기보다는 남은 양을 알 수 있다.
키는 X-Api-Key 헤더로 전달되며 기록된 URL에는 절대 나타나지 않는데, 매니페스트는 게시 가능하도록 설계되었기 때문이다.
USGS는 WaterServices API 제품군을 폐지하고 있으며, 2027년 1분기에 폐지가 예정되어 있고 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.