Embed a web page or raw HTML

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

Annotations already declare non-read-only, non-idempotent, open-world, non-destructive, so the safety profile is covered. The description's real contribution is placement behavior: content is inserted after the currently selected section, and the last section is selected by default so content lands at the end. That is useful non-obvious state behavior, but it omits what is required beforehand (a site open, a section selected) and whether the insert point can be changed via gsites_set_insert_point.

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 compact sentences with the core action and the exclusivity constraint front-loaded, then placement behavior, then the reorder escape hatch. The middle clause about default last-section selection is slightly convoluted but carries real information; nothing is filler.

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 two-parameter, no-output-schema insertion tool with annotations covering the safety profile, this is close to complete: it explains both input modes, the exclusivity rule, and where the content lands. The remaining gap is session preconditions (an open site/page and the meaning of 'currently selected section') which the agent must infer from sibling tools.

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 baseline is 3, but the description adds information the schema does not encode: the two properties are mutually exclusive and exactly one must be given (the schema has no oneOf and zero required fields). That mutual-exclusivity constraint materially changes how an agent fills the parameters.

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 description gives a specific verb and resource ('Embed external content') and enumerates the two accepted forms, a public url (iframe) or raw html (widget, <iframe>, <style>+<div>). This clearly separates it from specialized siblings like gsites_add_image, gsites_add_youtube, or gsites_add_map, though it never names those siblings explicitly.

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 states a hard selection rule ('Provide exactly one of url / html') and points to gsites_move_section for the follow-up reorder case, which is genuine routing guidance. It does not say what happens if both or neither are supplied, nor what prerequisites (open site/page) must hold.

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