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

The description discloses critical behavior not visible from annotations: the tool does NOT fail when the collector is down, reachable:false with ok:false is a valid answer, and generated_at advancing is the correct health signal rather than row count. This goes well beyond the readOnlyHint annotation and prevents serious misinterpretation.

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 dense but every clause earns its place. The key purpose and metrics are front-loaded, and the outage/false-failure nuance is delivered in a compact, structured way. No filler or repetition.

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 no output schema, the description does the necessary work: it names the returned fields, explains the failure mode, gives interpretation guidance, and tells the agent when to call it. Nothing needed to use this tool correctly is missing.

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?

There are zero parameters and the schema is empty, so the baseline is 4. The description adds no parameter syntax needs, but it compensates by explaining the meaning of the output fields, which is the relevant semantics for this parameterless tool.

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 identifies the tool as a feed health/freshness check and enumerates the specific metrics it exposes (ok, reachable, generated_at, sequence, seconds since last tick, board size). This is a distinct resource-level purpose that is easily separated from the sibling fixture/data tools.

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 explicit call conditions: before describing any price as current and after an outage. It also clarifies how to distinguish a real outage from a data tool's isError state. It does not explicitly name an alternative tool for comparison, but the context is clear enough to guide selection.

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