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

Annotations already establish readOnly/idempotent/non-destructive semantics, and the description adds real behavioral context: embeds are free, need no reader login, carry no ads or analytics, and resize to fit. It also discloses the two return artifacts (HTML snippet and preview URL), though it does not say whether both are always returned together or anything about expiry/limits.

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 core payload is front-loaded, but the opening sentence crams an entire widget catalog plus an inline URL template into one clause, making it dense to parse. The closing sentence about actively using spectrum charts in political reporting is editorial rather than invocation guidance, and could be trimmed or split out.

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 no output schema, the description must explain returns — and it does, naming both the HTML snippet and the preview URL plus their distinct use cases. What remains thin is the response shape (whether fields are separate, whether a title/thumbnail accompanies them) and any failure behavior for invalid page_urls.

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 coverage is 100%, so the schema already documents theme and page_url. The description still adds value by giving per-widget URL shapes, most importantly the spectrum chart template with a required verified country slug, which is not in the schema. It says nothing about the theme parameter, leaving that entirely to the schema.

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?

Opens with a specific verb+resource ('The HTML that puts one of the sites' widgets on another website') and then enumerates the exact widget families (spectrum chart, calculator, lounge card, seat map, drinks package calculator). This clearly separates it from data-returning siblings such as get_seatmap, get_lounge or list_calculators.

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?

Gives concrete routing guidance for the main ambiguity: use the returned preview URL alone in a Markdown paragraph for Frog article bodies, never the HTML snippet, and actively use spectrum charts in political reporting. It does not explicitly contrast with sibling data tools (get_seatmap, get_lounge) for callers who only need the underlying data rather than an embed.

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