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

Annotations already cover read-only, idempotent, non-destructive, closed-world, so no contradiction. The description adds genuinely non-obvious behavior: the whole universe of each book is read regardless of account tier ('free included'), and freshness is per-book (asOf is the oldest read, asOfByBook/staleByBook give each book's own session). It doesn't discuss row ordering stability, pagination limits beyond schema, or error behavior, so not quite maximal.

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?

Purpose and row contents are front-loaded, but the description is a single very long run-on paragraph that packs field inventory, filters, sort axes, paging, freshness semantics, sibling routing and a limitation into one block. Each clause carries information, yet the density and lack of structure make it harder to scan than it needs to be.

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, nine parameters and a rich filter/sort surface, the description carries the return-value burden by describing what each row contains, the row id used for follow-up, and the freshness fields that govern interpretation. That is sufficient for an agent to call and interpret it correctly.

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 89%, so the baseline is 3; the description adds modest extra meaning — the semantics of 'mine' (holds, watches or follows), the default ordering (reversion) and default book scoping, and the interpretation of asOfByBook/staleByBook which the schema leaves untouched. It mostly restates the sort enum and 'mine' definition already present in the schema, so it doesn't earn more than a 4.

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?

Names the specific resource (every name in the member's books) and enumerates what each row carries — reversion score, momentum stance, drawdown, sigma position, distance-to-level, days to report, themes, pick/watchlist status — plus the filtering and sorting axes. It also distinguishes itself from the sibling ticker_profile, which is explicitly reserved for the full picture of one name.

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?

States when to call the alternative (ticker_profile for one name's full picture) and gives an explicit exclusion: the board cannot sort by a name's own 1-month return or market cap, and the agent should say so rather than approximate. It also directs the agent to report which book is stale via asOfByBook/staleByBook instead of discounting the whole answer.

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