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

With no annotations provided, the description carries the full burden of behavior disclosure. It effectively discloses rate limits ('30/IP/day'), authentication needs ('Bearer ogs_…'), production requirements ('store the PNG on your CDN — do not hotlink the free GET URL'), and monetization ('Buy credits'). This goes well beyond a minimal statement and gives the agent actionable operational constraints.

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 main purpose is front-loaded in the first sentence, and the following sentences each add relevant operational details: supported options, free-tier limits, production guidance, and use-case positioning. It is not overly long for 12 parameters and includes practical instructions, though the pricing link could be considered tangential.

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 tool with 12 parameters, no annotations, and no output schema, the description is quite complete: it explains what the tool returns (a 1200x630 PNG URL), how to use it in production, rate limits, and an external alternative. The only notable gap is not mentioning the sibling og_image_from_url or explaining when to choose that tool instead, which would fully round out the contextual picture.

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 the parameters are already well documented in the schema. The description summarizes key parameter families (title, subtitle, badge, theme, logo_url, hex colors) but does not add meaningful detail beyond what the schema already states. It does reinforce the HTTPS requirement for logo_url and the hex expectation for colors, but that is also present in the schema descriptions.

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 opens with a specific verb and resource: 'Build a 1200x630 Open Graph PNG URL.' It also lists supported inputs such as title, subtitle, badge, theme, and hex colors, making the tool's purpose clear. It does not explicitly differentiate from the sibling og_image_from_url, though the broader context ('Not a template studio; for title-based branded cards') helps position it.

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 description gives explicit usage context: free light use with a 30/IP/day limit, and production usage requiring a POST to https://ogstamp.com/api/og with a Bearer token while discouraging hotlinking. It also states when this tool is appropriate ('for title-based branded cards when you do not want to self-host @vercel/og') and what it is not ('Not a template studio').

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