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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description correctly focuses on additional context: scores are deterministic, reproducible, auditable, UUID-stable, and read from article_fact_profile using the currently activated pipeline version. This adds genuinely useful behavioral nuance beyond the annotations, with no contradiction.

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 first paragraph is tight and front-loaded, and the Args/Returns sections are clearly structured and scannable. The five example queries add useful context but are somewhat redundant, and one is misleading, so the description is good but not maximally concise.

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?

Given the tool's complexity — seven score types, multiple filters, nested input, and a rich output shape — the description covers the score set, filtering semantics, quality flags, lookback window, limit, and full JSON return format. The main gaps are the omitted api_key parameter and the misleading intersection example, but overall the description is largely complete for a read-only tool with rich schema and annotations.

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?

With schema_description_coverage reported as 0%, the description must carry parameter meaning, and it does explain score_type, min_score, since_days, quality flags, and limit in plain language. However, it omits the api_key parameter entirely and does not state defaults for limit, score_type, or the exclude_* booleans, leaving the agent dependent on the schema for those details.

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 clearly states what the tool does: it computes seven deterministic 0–100 signal scores per article and filters articles by a chosen score_type and minimum value. The 'computed without LLM / Reproducible / Auditable' framing helps distinguish it from siblings like news_search and news_trending, even though it never explicitly names an alternative.

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 example queries provide concrete usage contexts: regulation signals, risk above 80, CFO cost briefings, CTO operational awareness. However, it never says when not to use it or which sibling tool to prefer, and the third example ('both high regulation_relevance AND high business_relevance… intersection') implies a multi-score AND capability that the Args section contradicts by requiring a single score_type.

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