whale_daily_summary

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

There are no annotations, so the description must carry the full disclosure burden. It does: the 5-minute cron upsert guarantees today's row is current, rows older than 365 days are purged, data is cached for 5 minutes, and rows are daily UTC aggregates with a chains_breakdown object.

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 content is dense and mostly front-loaded, with the core purpose stated before the return-field details. Some redundancy exists ('daily aggregated whale movement counts' repeats the opening 'daily whale movement counts' about 20 words later), but the structure is readable and every sentence contributes a fact.

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, the description thoroughly explains the returned row fields, freshness, retention, caching, look-back control, and example questions. However, the unresolved max-90-vs-max-180 contradiction and lack of stated row ordering are noticeable completeness gaps for actually relying on the tool's output.

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?

Although the single parameter has 100% schema description coverage (baseline 3), the description adds no new meaning and, worse, conflicts with the schema's own validation: the text says 'max 180' / '1–180' while the JSON Schema maximum is 90. An agent cannot tell whether 100–180 is valid, making the parameter definition misleading.

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 opens with a concrete verb and object—'Get daily whale movement counts'—and immediately specifies per-chain inflow/outflow aggregation over a look-back window. It also explicitly scopes this as trend analysis 'not individual transfers', distinguishing it from the whale_movements/whale_activity 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 establishes when to use this tool ('trend analysis', 'Which network was most active this week?') and states an exclusion ('not individual transfers'). It does not name a specific sibling alternative for the individual-transfer case, so it stops short of an explicit when-not/alternative statement.

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