Metis · News Radar — Scan Library

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

With no annotations, the description carries the full burden and does disclose real side effects: rows are written to `new_publications`, duplicates are suppressed by URL, and the output is deliberately kept off the News surface. It stops short of prerequisites (network/config, credentials) and failure behavior when a feed is unreachable.

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 the verb and action in the first sentence, followed by scope and then the sibling contrast. The parenthetical feed roster is somewhat long and ends in an ellipsis, but it earns its place by showing how broad the scan is.

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 not be explained, and the description still covers destination, dedup, and surface isolation. The main gap is operational context — whether it needs network access, how long it takes, and what happens on partial feed failure.

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?

The tool takes zero parameters and the schema is empty, so there is nothing for the description to clarify. Baseline 4 applies; it correctly avoids inventing inputs the caller might expect, such as a feed list or date range.

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 ('Fetch the literature feeds and add new papers to the Library'), enumerates the actual sources, and names the destination table `new_publications`. It explicitly contrasts with the nearest sibling `scan_news`, so an agent can choose between them without opening either 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 clearly sets the boundary against `scan_news` and explains why the split exists ('builds a scientific background rather than reporting what happened'). However, the sibling list is dense with other scanning/sync tools — `scan_literature`, `full_scan`, `scan_pubmed_alerts`, `scan_openalex`, `sync_zotero_library`, `check_news_feeds` — and none of those are disambiguated.

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