get_model_forecast

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.