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

Annotations only provide readOnlyHint and openWorldHint, so the description carries the behavioral burden. It adds substantial context: results are deduplicated, grouped under situations, relevance ordered, bounded to top matches, paginated via cursor, each page counts against a cap, and sign-in or API key is required.

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 description is dense but well organized: it opens with the core action, defines key domain terms, lists result contents, gives the intended use case, names downstream tools, explains pagination and cap behavior, and closes with auth and citation guidance. Every sentence contributes information an agent needs.

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?

Without an output schema, the description adequately explains what the result looks like: situations, one-line summaries, significance scores, source counts, and canonical URLs. It also covers pagination, rate cap implications, auth requirements, and how to proceed to sibling tools, making it safe and complete to call.

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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that results are grouped under situations so limit may produce fewer headings, and by framing query as a topic, entity, company, country, or event. Cursor semantics are also reinforced.

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 and resource: search the news by topic to find situations and events. It further distinguishes the tool by explaining that a situation is a storyline and an event is a deduplicated cluster, making it clear how search_situations differs from the sibling tools.

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 description gives clear use context: use it to answer 'what is happening around X' for a topic, company, country, or event. It also routes to get_situation_timeline for history and get_cluster for event detail, though it does not explicitly contrast with get_top_situations.

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