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

Annotations already declare readOnly/idempotent/closed-world, so the description adds genuine extra context: it names the candidate universe (whole-market hot list), the computed metrics, and that each call is billed once — billing cost is not captured anywhere in structured fields. It does not describe pagination or what happens near window boundaries, but that is minor given annotation coverage.

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?

Three compact clauses: what the ranking is, how it is computed/sorted, and the billing note. Front-loaded with purpose, zero filler.

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 does mention the returned fields are statistical metrics (heat_chg_1d/3d, heat_z20) and that they are suitable for factor pipelines, which is enough to set expectations. A little more on the ranking output shape (e.g. symbol + metric values) would make it fully complete.

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 100%, with enums for order, market and window already fully documented, so the baseline is 3. The description adds only that metrics are computed on the candidate pool and that output fields are pure statistics; it says nothing about how limit/order/window/min_mentions interact beyond the schema.

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?

States a specific verb+resource in both title and text: it ranks stocks by heat acceleration (heat_chg_1d / 3d / z20) descending, computed over the whole-market hot-list candidate pool. This is clearly distinguishable in spirit from sibling 'hot list' tools like get_market_hot_stocks, though no sibling is named explicitly.

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 by 'who is suddenly getting hot' and the mention of quant factors and monitoring, which tells an agent the intended scenario. There is no explicit when-to-use versus when-to-use-alternatives guidance (e.g. vs get_market_hot_stocks or get_weighted_hot_stocks), so routing still requires inference.

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