watchlist_report

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true, and the description resolves the non-obvious part of that profile by stating 'Every run stores a reading per term' and that it measures 'two requests each'. This explains the persistence side effect behind readOnlyHint=false and the external calls behind openWorldHint, adding real value beyond the annotations. It does not describe failure modes or rate limits, keeping it short of a 5.

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 core purpose is front-loaded in the first sentence, followed by the persistence note and the pagination mechanics, with no filler. Three short sentences and a parenthetical keep it tight, though the 'was stable, now rising' illustration is slightly decorative rather than load-bearing.

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?

An output schema exists, so return-value detail is appropriately omitted. The description covers the report's content, the side effect, and pagination, which is what an agent needs to call it. The only real gap is the undocumented geo parameter for this openWorld tool.

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 carry the parameter burden, and it explains limit ('terms per call') and offset ('to continue') with a clear pagination model. However, the geo parameter is never mentioned, so a third of the parameters 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 gives a specific verb and resource: it reports the watchlist's measured direction, change since last report, and trending status per term. That clearly distinguishes it from siblings like watchlist_add, watchlist_remove, and trending_now. It stops short of naming an alternative for overlapping use cases, so it is clear but not fully differentiated.

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?

Usage is implied rather than stated: you run it to get a watchlist report, and the pagination sentence ('limit terms per call, offset to continue') gives a partial workflow. There is no explicit when-to-use guidance, no exclusions, and no pointer to an alternative tool for a similar need.

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