get_observations

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 discloses the 7-day limit, which is useful, but doesn't describe pagination behavior, rate limiting, what happens with large intervals, whether data is ordered, or the nature of the raw observations returned. With zero annotation coverage and an output schema present, more behavioral context would be valuable.

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 brief and front-loaded with the core purpose in the first sentence. The second line about include_quality is relevant but could be clearer about whether it's optional or default behavior. Slightly minimal but no wasted words.

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 9 parameters at 0% schema coverage, no annotations, and multiple sibling tools with overlapping functionality (aggregate_observations, compare_soil_depths), the description is significantly under-specified. The output schema exists but doesn't reduce the need for parameter guidance. A moderate-complexity tool like this needs more than two short lines.

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 9 parameters. Only include_quality is explained ('add upstream quality codes and labels per observation'). The meaning of data_ext, depth_cm, data_type, metric, limit, and the date formats of start/end are all undocumented in both schema and description.

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 raw observations for an explicit interval of at most 7 days,' which is a specific verb+resource+scope. It distinguishes from siblings like aggregate_observations (raw vs aggregated) and inspect_coverage/inspect functionality. However, it doesn't explicitly differentiate from all siblings, and 'raw observations' could be slightly clearer about what kind of data is returned.

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 7-day max interval is a useful usage constraint, but there's no guidance on when to use this vs. aggregate_observations or other sibling tools. No exclusions or alternatives are named. The 'explicit interval' phrasing implies it requires explicit start/end dates, but this is not fully developed.

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