Get degree-days for a location

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

No annotations are provided, so the description carries full behavioral burden. It discloses the computation methodology (ERA5 daily mean temp, 30-year rolling window, NWS/EIA/WMO method) and pricing, but does not describe what the response contains, whether it's a read-only operation, rate limits beyond first-call-free, or error behavior. The pricing disclosure is helpful but the safety/behavioral profile of a query tool is not explicitly stated.

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 reasonably concise with one purpose sentence followed by pricing and docs info. The opening line is front-loaded with the purpose and use cases. Pricing and docs are appropriately placed at the end. Slight bloat in listing all three degree-day types in prose, but this is informative rather than wasteful.

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 6 params, 17% schema coverage, no output schema, and no annotations, this description has significant gaps. It doesn't explain parameter semantics for kind/base/from/to, doesn't describe return format, and doesn't cover pagination, limits, or error cases. The computation methodology disclosure is a strength, but for a 6-param API point tool with no structured docs, the description should provide substantially more guidance to an agent.

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 17%, so the description must compensate significantly. The description adds the era5 rolling-window method context and pricing but does not explain the key parameters: what 'kind' values are acceptable (HDD/CDD/GDD are mentioned in prose but not mapped to the kind param), what format 'from'/'to' should take, or what 'base' means. The lat description in schema handles latitude/city aliasing well, but the other five params remain 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 clearly states the verb+resource: 'Get degree-days for a location', and elaborates that HDD/CDD/GDD are computed from ERA5 data for any GPS point or city over a date range. It distinguishes from siblings like climate_indices, climate_anomaly, and weather_forecast by specifying degree-day computations specifically. It doesn't explicitly name alternatives, but the specific metric (degree-days) is clearly different from 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?

The description gives clear context on when to use it ('Before your agent sizes heating or cooling demand, settles an energy contract or models crop growth: heating, cooling and growing degree-days'). This frames the use case well. It doesn't explicitly state when NOT to use it or name alternative tools, but the open-hand context of use is well established.

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