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

No annotations are provided, so the description carries the full behavioral disclosure burden. It adds useful temporal context (the week-long window, the '3am' scenario), but it does not disclose return format, how the six filters combine, result ordering, or any caveats. The 'up to a week' claim duplicates the schema's 'Max 7d' rather than adding new behavioral information.

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 sentences with zero filler: purpose and scope first, then the sibling differentiator. Every clause earns its place, and the most decision-relevant information (the time window and the competing tools' limitation) is front-loaded.

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 has meaningful complexity — six optional filters, correlation tracing, topic prefix matching — and no output schema. The description handles tool selection well but is thin on usage depth: it does not clarify what the response looks like, how filters interact, or the behavior when no filters are given. Adequate for choosing the tool, but an agent would still rely entirely on the schema to use it correctly.

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 every one of the six parameters already documented in detail (level enum, limit default/cap, since formats and max window, topic prefix rules, trace across streams, contains semantics). The description adds only marginal temporal framing around the 'since' parameter and does not materially enhance what the schema already states, 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 the cloud journal') plus an explicit scope ('hours or days of history, up to a week'). It distinguishes itself from siblings by naming tail_logs and search_logs and their one-hour limitation, so an agent can select it correctly without opening schemas. The 'what happened at 3am' example reinforces the use case.

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 names the two competing siblings (tail_logs, search_logs) and the condition that selects them over this tool ('only see the last hour'), which is exactly the when-not-to-use guidance. The temporal differentiator is front and center, leaving no ambiguity about when search_history is the right choice.

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