news_sentiment

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: source index (GDELT, Hacker News), a 7-day recency window, a 25-article cap, the fact that scoring is done by Claude Haiku 5.5 from headlines and snippets only (a meaningful limitation), the billing rule (free when fewer than 2 articles are found), the cost ($0.006 USDC per call) and p99 latency of 12000ms. These are exactly the operational facts an agent needs before invoking a paid, potentially slow call.

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 definition is a single dense paragraph that front-loads the purpose and then layers scope, output shape, audience and operational facts, so every clause carries information. It is long and somewhat wall-of-text, but there is little genuine padding to cut.

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?

No output schema exists, so the description must describe the return value — and it enumerates the full payload: overall label, -1 to 1 score, positive/neutral/negative counts, 3-5 themes, a two-sentence summary, and per-article sentiment, title, source, date and URL. Combined with the source/recency/cost/latency details, an agent has everything required to call this 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 only 33% (topic is documented, limit and category are not), so the description should compensate but only partly does. It explains the upper bound of the limit ('up to 25 recent articles') but not the default of 15 or the minimum of 5, and it says nothing about what the category enum selects. The 25 cap is the only real parameter insight added.

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 states a specific verb (analyze/rate) and resource (news sentiment for a company, token, person or topic) and fully describes the pipeline: finds up to 25 recent articles from its own GDELT/Hacker News index over the last 7 days and rates how coverage reflects on the topic. This is clearly distinguishable from sibling search tools like news_search, crypto_news and discussion_search, which return articles but do not score sentiment. An agent can tell exactly what this returns 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?

It gives clear usage context — 'For trading signals, brand monitoring and research agents' — which tells the agent which kinds of tasks this fits. However, it names no alternatives and states no when-not condition, so an agent choosing between this and news_search or crypto_news must infer the difference itself.

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