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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: authentication via OAuth-linked account or X-API-Key header, and the fact that a no-arg call returns a description of existing state. It stops short of disclosing log scope, volume, pagination, or time-range behavior, which matters for a log-reading tool.

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 text duplicates itself: the invocation format appears twice (the inline `whisper.agents({op:'logs'...})` string and the JSON example call), and the credential requirement is stated twice ("Requires your Whisper API key" then "OAuth or your API key in the X-API-Key header"). It leads with a tautology instead of front-loading what the operation returns, and the phrase "so the example below runs as published" adds no information.

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 described, and credentials are covered. However, for a read operation sitting among two dozen `agents.*` siblings, the description omits the one thing an agent needs: what these logs contain and how they differ from history/trace operations. That gap is significant despite the annotations covering the safety profile.

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 single nested `input` object is already documented in the schema. The description's remark that no arguments yields a description of existing state mirrors the schema text rather than extending it, and it offers no hints about what valid argument keys (filters, limits, time ranges) the nested object accepts. Baseline 3 applies when the schema carries the parameter burden.

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 logs operation on the Whisper control plane" essentially restates the tool name and title without saying what kind of logs are returned (agent activity? audit? connection history?). The only added specificity is the wire format (op:'logs'), which explains how to invoke it, not what it does. An agent still cannot distinguish this from siblings like whisper_agents_history or whisper_agents_trace.

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 notes that with no arguments it "describes what you already have," which is a weak default-behavior hint rather than when-to-use guidance. There is no statement of when to prefer this over whisper_agents_history, whisper_agents_trace, or whisper_history, nor any prerequisites beyond credentials. Usage must be inferred from the name alone.

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