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

Annotations already declare readOnly, idempotent, and non-destructive. The description goes well beyond by explaining how signal_score is computed (live signal vs per-article magnitude), the per-article resolution, the 'stronger of two sides' behavior, and the cost attached to the AI pipeline. It also clarifies that there is deliberately no separate news_score field, a nuance an agent needs to interpret results correctly.

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 well-structured: purpose first, then use cases, then parameters, then deep signal_score explanation. It is verbose but every paragraph adds necessary context (cost, pro-tier, behavioral details). The use of bullet points and section headers aids scanning. It could be tightened, but it is not padded; complexity justifies the length.

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?

Despite having an output schema (which presumably lists fields), the description explicitly enumerates per-article fields (symbol, title, published_at, ai_sentiment, ai_summary, signal_score, band) and explains all behavioral aspects an agent would need to call it correctly: selection logic, ordering, cost implications, and constraints. Nothing important is omitted; the tool is fully self-contained.

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 100%, so the baseline is 3. The description adds meaningful depth for min_signal_score, explaining that it is resolved per-article (live signal preferred) and that the server-side selection uses Python filtering rather than a naive $gte. This helps an agent understand the exact ranking and filtering semantics beyond the schema's terse wording. Days and limit are straightforward but still given bounded defaults in the description.

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 opens with a specific verb and scope: "Top AI-flagged news across all tracked stocks — the market-wide news briefing." It immediately contrasts with get_stock_news (per-symbol), making the distinction explicit. No ambiguity about what this tool does or how it differs from siblings.

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?

Lists exact use cases (morning briefing, catalyst scanning, event monitoring) and explicitly contrasts with get_stock_news. It also states the tool is Pro-tier only and for informational purposes — clear constraints on when to use it. No exclusions are left implicit.

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