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

Annotations already declare readOnly/idempotent/openWorld, and the description goes well beyond them: it discloses the required api:read scope and that results reflect only the caller's own source choices (an important authorization/scope nuance). It also documents the polling vs paging semantics of the cursors, which no annotation covers.

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?

A single dense paragraph with the identity front-loaded and each view labeled in call order, so scanning is fast. It is longer than typical but nearly every clause carries new information; the framing phrases ('the call for ...') are slight padding.

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 7 optional parameters, no output schema, and an openWorld hint, the description supplies return-value concepts for each view (newest posts newest-first, source list with include flag, related Today's Market cards) plus auth and pagination behavior. It stops short of describing the actual response envelope, which matters somewhat given no output schema exists.

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 coverage is already 86%, but the description adds genuine meaning: each view's behavior is explained, item_id is framed as the item's numeric id for related_opportunities, and critically it states that before + before_id (or since + since_id) must be passed as 'both halves of the last row's cursor' — a pairing rule the schema does not express.

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?

Opens with a specific identity ('YOUR curated news feed') and enumerates three distinct views with their exact contents, immediately separating it from get_news_headlines (raw headlines) and manage_news_sources (mutation). An agent knows what resource this is and what modes it exposes without opening the schema.

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?

Maps natural-language intents ('news on my holdings', 'what's in my feed') to the correct view and explicitly excludes writes with 'changing them stays in the app'. What's missing is naming the sibling that performs that change (manage_news_sources), so routing for the write case is inferred rather than stated.

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