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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral insight beyond that: sources are very unevenly sized (~1700 institutional-holding rows vs. two on-chain rows) and a source returning exactly `limit` rows is probably truncated — a diagnostic heuristic the annotations never convey.

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?

What the tool returns is front-loaded, followed by the source/limit mechanics; every sentence carries information. The closing sentence is long and runs across several wrapped lines, but it earns its place by explaining the truncation signal and the cheaper deep-read tactic.

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 values need no explanation. For a two-optional-parameter retrieval tool, the description covers what is fetched, how to scope it, and how to detect and work around truncation — enough for correct invocation, though it could be clearer about how this differs from the signals/rankings tools that feed its slugs.

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 both parameters, and it does: `limit` caps rows per source, `source` omitted means all sources or can be a slug drawn from a rankings/signals source list. It does not enumerate the valid slug values themselves, but it points the agent to where they come from.

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 names the resource concretely and enumerates the seven sources it covers (insider trades, congressional trades, earnings beats, dated catalysts, on-chain flows, 13F filings, AI news-beneficiary reads). An agent can tell what data comes back, but it never distinguishes itself from siblings like rayana_ai_signals or rayana_ai_rankings beyond referencing their source lists, so it falls short of a 5.

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 usage guidance: omit `source` to fetch all seven at once, or pass a slug taken from a rankings/signals row, and it recommends narrowing with `source` plus a higher `limit` for deep single-source reads. It stops short of saying when to prefer this tool over rayana_ai_signals/rayana_ai_rankings, so no alternatives are explicitly excluded.

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