panel_run

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

Well beyond the annotations, it discloses external API calls and quota cost, a concrete disk write path (<config>/snapshots/<panel>/<iso>.json), and the credential prerequisite (at least one engine API key, same as am_i_cited). The annotations already establish the write/openWorld/non-destructive profile, so this is additive rather than redundant. Minor nuance: appending a fresh timestamped file each run sits in mild tension with idempotentHint=true, but the tool's panel state is unchanged, so it is not a true contradiction.

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?

Four sentences, each carrying distinct payload (action, side effects, credentials, return shape, routing), with the core purpose front-loaded before the caveats. No filler or restated title text.

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?

With an output schema present, the description needn't detail return structure, yet it still summarizes 'per-query citation presence and a citation_rate summary.' Combined with annotations and a fully documented 3-param schema, an agent has everything needed to call this correctly and cheaply.

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 name, domain override, and the engine enum (including the serp restriction) are already documented in the schema; the description adds nothing parameter-specific. This is the expected baseline when the schema does the heavy lifting.

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 opening sentence gives a specific verb and resource ('Run a saved panel through am_i_cited and append a timestamped snapshot'), immediately separating it from audit_* tools and from panel_track, which only creates panels. An agent can identify the operation and its scope without opening the 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 explicitly routes the agent: 'Use panel_track to create a panel first; use citations_trend to read the accumulated trend after multiple runs,' naming both prerequisites and the downstream alternative. The engine note also states when serp engines are appropriate and that am_i_cited will refuse them.

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