event_history

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

readOnlyHint=true already establishes the non-mutating profile, and the description adds little beyond it: it hints that results include source evidence but doesn't say how events and evidence are paired or ordered. The "not a scan watermark or a duplicate veto" clause gestures at statefulness the agent may need to know about (does calling this advance anything?) without resolving it.

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?

Two short sentences with the positive statement front-loaded, so it is not bloated. However, the second sentence spends its length on two unexplained terms that add ambiguity rather than clarity, so the brevity is partly achieved by under-specification.

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?

The tool is simple (two optional bounded parameters), has an output schema so return values need no explanation, and readOnlyHint covers safety, so the definition is not far from sufficient. What is missing is the meaning of "qualified" and any routing signal against history or pending_news, which matters for a tool whose whole value is which events it selects.

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 hours and limit both documented in the schema with defaults and bounds, so the description can legitimately leave them to structured data. It does not add any interaction semantics, such as whether limit caps events before or after evidence attachment, so it stays at the baseline.

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?

"Read qualified current events and source evidence" gives a verb and a resource, so the general shape is clear, but "qualified" and "source evidence" are undefined jargon and the description never explains what qualifies an event. The second sentence distinguishes it only from things named "scan watermark" and "duplicate veto", which are not obviously any of the listed siblings, so an agent cannot cleanly separate it from tools like history or pending_news.

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 only guidance is negative — "not a scan watermark or a duplicate veto" — which tells the agent what the tool is not but never when to reach for it. There is no condition selecting it over the sibling history tool, no mention of the lookback window being a starting point versus exhaustive coverage, and no stated prerequisites.

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