Web Search (Tanod)

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

Annotations already cover read-only/idempotent/open-world, yet the description goes well beyond them: index is not exhaustive, headlines-only with no article text, newest-first ordering, exact return fields, non-charging on empty/stale results, latency under 1s, price and free-tier limits, and an untrusted-data warning. That is a materially richer safety and cost profile than the annotations alone.

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, then alternatives, then behavior and costs—well ordered. There is some boilerplate waste: the untrusted-data warning is stated twice, and "on-chain strings" is copied from a generic template and is irrelevant to a news tool.

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?

Covers what the tool does, when to prefer siblings, what the response contains, cost and rate limits, and error behavior. With an output schema present it correctly stops short of detailing the response payload, and nothing needed to call it correctly is missing.

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 explains query, lang, limit, since, domain, timespan, sentiment, and match_mode. The description adds only marginal parameter meaning—the returned field list and the note that queries are never broadened (relevant to match_mode)—but gives no examples or interaction rules such as since overriding timespan. Baseline 3 is appropriate.

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") plus the data source (GDELT index) and scope (recent, newest first). It explicitly distances itself from two named siblings, web_search and get_crypto_news_headlines, so the agent can pick it without opening a 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?

Names both alternatives and the condition that selects each: web_search for the web at large, get_crypto_news_headlines for crypto stories. It also tells the agent what to expect on failure (empty results explain the searched window and what to try next; 422 vs 503 semantics) and that queries are never broadened automatically.

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

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

Goes far beyond the annotations: 20,000-char cap per page with a truncated flag, per-page errors, a shared 20 s bound across pages, a failed page still being charged, 503 on failed search (not charged), typical 2-20 s latency, USD 0.025 price, 3 free searches per IP per UTC day, and an untrusted-data/prompt-injection warning. For a metered, latency-variable network tool this is exactly the disclosure 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?

Purpose is front-loaded in the first sentence, and every subsequent sentence carries distinct information (routing, limits, errors, price, safety). The middle section is dense and semicolon-heavy, packing many clauses into long sentences, which slightly hurts scanability but wastes nothing.

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?

For a paid, rate-limited, open-world tool with a non-trivial failure model, the description covers cost, free tier, timing, error semantics, content limits, and safety guidance. An output schema exists, yet the description still states the shape of the return, and no decision-relevant fact is missing.

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 baseline is 3; the description adds behavioral meaning to n by tying it to the 20,000-character-per-page fetch and truncation flag, which explains the cost/latency tradeoff of raising it. q is left entirely to the schema, but that is adequate for a plain-text query.

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+resource ('Search the web and get the Markdown of the top results in one call') and immediately differentiates itself from the closest sibling, web_search, which returns links only. An agent can tell exactly what it gets back (title, url, snippet plus page Markdown) 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?

Gives one explicit routing rule ('For links only use web_search') and an implicit when-not via 'Static fetch only, no JavaScript', which steers JS-dependent targets toward rendering siblings. It stops short of naming alternatives like fetch_page_contents or render_page, so coverage of the alternative space is partial rather than exhaustive.

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

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

Annotations only declare read-only/idempotent/open-world; the description adds materially more: typical latency 0.3-2 s, price USD 0.005 per call, a free tier of 3 searches per IP per UTC day, and an explicit prompt-injection warning to treat results as untrusted data. These are exactly the operational facts an agent needs before spending money.

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?

Purpose is front-loaded, followed by sibling routing, then cost/latency/quota, then the safety caveat. Every sentence carries distinct information; nothing is repeated from the title or schema.

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?

An output schema exists, so return values need no prose explanation, and the description still covers pricing, quota, latency, and trust posture. Nothing an agent needs in order to invoke this correctly is missing.

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%, with count, query, country, and freshness all documented including ranges and examples. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies; 'ranked results (title, url, snippet)' describes output, not inputs.

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 the web for a query), the exact return shape (ranked title, url, snippet), and the underlying index (Mojeek), which distinguishes it from a generic aggregator. An agent can tell it apart from search_with_contents and news_search 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?

Names two explicit alternatives with the condition that selects each: search_with_contents when page text is needed in the same call, news_search for news. No exclusions are left to inference.

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