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

With no annotations, the description carries the behavioral burden and does add valuable context: it discloses that the tool returns insufficient_data until enough snapshots exist. It also scopes results to hard metrics and excludes community attitude, giving the agent meaningful expectations beyond what the schema shows.

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 three short sentences with no filler. The core purpose is front-loaded, followed by the exclusion/alternative and the edge-case note, so every sentence earns its place.

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?

The output schema covers return values, and the description covers purpose, an alternative, and an important edge case. However, it leaves the source parameter and window format undefined, and with no annotations this creates a noticeable gap for an agent trying to make a well-formed call.

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 the bare parameter names. It only restates 'entity' and 'time window' in natural language, never explains the optional source parameter, and gives no format guidance for window beyond the schema default. This is minimal compensation for missing parameter documentation.

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 defines the tool as returning a hard-metric trend for an entity over a time window, which is a specific operation and resource. It also distinguishes itself from community-attitude tools by explicitly stating that community attitude is not included, making its purpose unambiguous even among many sibling 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?

It gives explicit when-not-to-use guidance by stating community attitude is excluded and directing the agent to community_signal / hn_attitude instead. It does not cover every possible alternative such as compare_entity_trends, but the singular-entity scope and the named alternatives provide adequate usage direction.

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