utilpeek: search recent news articles (GDELT): title, link, source, time, optional headline sentiment

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description adds substantial behavior: headlines/links only with no article text, a GDELT index refreshed every 15 minutes retaining 14 days, typical latency under 1 s, cost (USD 0.003, 10 free calls/IP/UTC-day), and the untrusted-content warning. This is rare, high-value disclosure beyond structured fields.

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?

Front-loaded with purpose and alternatives, then return shape, then operational constraints - a sensible ordering with almost no filler. The only wasted text is the trailing 'on-chain strings' clause, which is boilerplate carried over from crypto tools and irrelevant to a news search, slightly diluting focus on an otherwise dense paragraph.

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 an output schema present the description needn't enumerate return values, yet it still summarizes the returned fields, both error paths, freshness/latency, and pricing. For a 7-parameter paid lookup tool, an agent has everything needed to call it, interpret empty results, and handle failures.

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 100%, so the schema already documents lang, limit, since, tsimespan, domain, and sentiment in detail. The description mentions only that sentiment is optional and that results are newest-first, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource ('Search recent news articles by keyword') and identifies the backing index (GDELT) plus the scope ('newest first'). It goes further by naming what it is NOT for, pointing at web_search and get_crypto_news_headlines, so an agent can distinguish it from near-neighbors without opening any 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?

Explicitly routes the agent: 'For the web at large use web_search; for crypto stories use get_crypto_news_headlines.' It also tells the agent how to read non-results ('No match is count 0, not charged') and which error codes map to which condition (422 bad input, 503 stale/missing index), removing guesswork about when and how to call it.

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