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

With no annotations, the description does the work: it discloses that the tool fetches the page, extracts title/description/favicon/theme-color, and returns a stable image URL suitable for og:image. It does not cover failure behavior or caching, but for a generation tool these are secondary; the main behavioral facts are present.

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 definition is tightly structured: purpose, mechanism, output, and customization rule each occupy one short sentence, with no filler or repeated schema content. The key usage scope ('existing public page with no fields to fill in') is front-loaded.

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?

The output contract is stated (stable image URL) and the automatic behavior is explained, so a simple URL-based call is well supported. But the optional parameters are left vague, the meaning of 'any field can be overridden' is not mapped to the schema, and the relationship with render_og_image is unaddressed, leaving gaps for a tool with 5 parameters and no 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?

Schema coverage is only 20% (only url has a description), and the description does not explain font, size, theme, or layout beyond the generic 'Any field can be overridden.' The enum names are self-evident, but the description fails to compensate for the missing parameter-level guidance, so the agent must infer meanings from the values.

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 names a concrete action ('Build an Open Graph card') and a clear resource ('an existing public page'), and states it derives content automatically from page metadata. It distinguishes the tool by the 'no fields to fill in' scope, but it never explicitly contrasts this with the sibling render_og_image, so it stops short of full sibling differentiation.

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 phrase 'for an existing public page with no fields to fill in' supplies the main use condition and the 'Any field can be overridden' note hints at customization. However, no alternative tools are named and there is no guidance about when not to use this tool, leaving the agent to infer the boundary with render_og_image.

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