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

Annotations already mark this readOnly, idempotent, and non-destructive, so the extra work is context. The description adds essential behavior: silent clamping of days/limit by tier, the Pro-only gating of AI fields, the single-number signal semantics (stronger side wins, re-scored live), the per-article fallback when no signal exists, and the explicit null-only-when-neither-path-produces-a-value rule. These are exactly the non-obvious behavioral facts an agent needs.

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 dense and highly informative, but the signal_score section is long and somewhat repetitive, with paired clarifications (the same resolver, the same fallback, the same number) that could be tightened. It is front-loaded with the core purpose and key behavior, but the later paragraphs could be trimmed without losing meaning.

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?

The output schema is present, so return-value details need not be fully spelled out; the description covers the important return semantics (status values, tier differences, signal_score behavior) and the tool's place among siblings. It omits exact output field naming for non-signal per-article fields, but the output schema plus the description's mention of title, published_at, ai_sentiment, ai_summary, and signal_score fields is sufficient for calling.

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 schema already documents all three parameters. The description adds value beyond the schema by clarifying the real-world effect of clamping (a free caller passing no limit gets 5, not 10) and by explaining signal_score fallback semantics. It doesn't repeat plain schema text; it enriches it with behavioral implications.

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 crisp verb+resource statement — 'AI-analysed news for a stock, newest first' — and immediately narrows scope to articles processed by the AI pipeline. The free/Pro tier contrast and explicit naming of fields distinguishes it clearly from siblings like get_news_feed and get_stock_research.

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?

The tier system and clamping behavior tell the agent when the tool is appropriate and what constraints apply. It references the shared signal resolver linking to get_signals()/get_stock_research(), which helps an agent choose among related tools, though it does not explicitly say 'use this instead of X when Y'.

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