USGS NWIS — Annual Streamflow Statistics

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds context beyond that: data availability ('records going back to 1900s'), typical record length (60–90 years), unit (ft3/s), and access policy ('No auth — USGS public domain, unlimited calls').

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?

At four sentences, the description is compact and front-loaded: the core action and output unit appear first. The remaining sentences add use-case and data-availability context without fluff.

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 a single parameter that is fully documented in the schema, rich annotations, and an existing output schema, the description covers all necessary calling context: what data is returned, unit, temporal coverage, authentication/rate limits, and how to find station IDs. Nothing essential is missing.

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 100%, so the schema fully documents site_no with format and example. The description reinforces the lookup workflow through water.sites but adds no new parameter-level semantics beyond the schema, so the baseline of 3 is appropriate.

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 states 'Get year-by-year annual mean streamflow statistics for a USGS gauge station' with a specific verb and resource, and distinguishes from sibling tools like nwis.streamflow.daily_values by emphasizing annual water-year aggregation. It also specifies the return unit (ft3/s) and the data's temporal span, leaving no ambiguity about 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?

The description gives clear context for when to use this tool: long-term hydrologic trend analysis, climate change assessment, and water resource planning, which implies annual statistics rather than daily or realtime data. It also provides a prerequisite lookup step: 'Use water.sites to look up station numbers by state or bounding box.' It does not explicitly name alternative streamflow tools or state when not to use it, hence 4.

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