Write Report And Open HTML

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

Annotations declare openWorldHint=true and destructiveHint=false, but the description adds real side-effect context the annotations don't: this writes files to disk, renders an HTML artifact, and opens a browser. It does not cover overwrite behavior or how out_dir is resolved, keeping it below 5.

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, front-loaded with the flow position and core action, then a compact input enumeration. The parameter list in sentence two is dense but each item earns its place by mapping to a distinct argument.

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?

For a 9-parameter tool with nested objects and no output schema, the description covers the primary inputs and the terminal write/render/open behavior well. It omits explanation of out_dir, account_id, and call_context, which is a notable but not crippling gap given schema coverage and the absence of an output schema.

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?

At 67% schema description coverage, the description usefully labels several parameters in prose (canonical topics, optional per-call table, reviewed agents with current instructions, recommendations Markdown, suggested rewritten prompt, browser open). It leaves out_dir, account_id, and call_context unmentioned, so it doesn't fully compensate for the gap.

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 multi-step action (writes analysis to files, renders self-contained HTML, opens browser) and situates it precisely as 'Step 6 of the review flow.' This clearly separates it from every sibling, which are auth, list, and read tools rather than a report terminal step.

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 'Step 6 of the review flow' framing gives strong sequencing context, and the second sentence enumerates exactly which inputs to pass. It does not name a when-not-to-use condition or an alternative tool, so it falls short of a 5.

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