betterimage.io

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

Annotations cover readOnly, openWorld, and idempotent traits. The description adds valuable behavior beyond those flags: it fetches the page like a crawler, performs one fetch plus one render per call, returns a watermarked free inline image, makes a Jev design decision in about 100 ms, and has a preset fallback. No contradiction exists between the description and the annotations.

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 description is front-loaded with the core action and dense with useful detail. Every sentence contributes relevant behavioral or usage information, though a few details (preset, size) are also present in the schema, making it slightly redundant rather than perfectly lean.

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 no output schema but a rich input schema, the description provides the key invocation context: one-call flow, no API key, page fetching behavior, override semantics, default size behavior, and fallback design. An agent has enough context to select and invoke this tool correctly without missing critical information.

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?

The schema already describes every parameter comprehensively, so the baseline is 3. The description adds extra semantic value by stating that 'any field you pass overrides what the page says' and that preset lets the caller choose the design instead of relying on Jev. This clarifies parameter precedence and intent beyond 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?

The description states a specific action and resource: 'Make a social card for a page that already exists, in one call.' It also clarifies the crawler-like gathering of page metadata and names the sibling list_presets where relevant, so an agent can distinguish this from render_card and og_image_url.

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 explicitly says 'Use this first when the user gives a URL' and gives a concrete user utterance ('make an OG image for my latest post'). It also mentions preset and size as optional choices, but it does not explicitly rule out or contrast with sibling tools like render_card or og_image_url, so exclusions are left implied.

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

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

Beyond readOnlyHint, the description discloses the tool fetches external pages, limits fetches to one page and two images, and requires no API key. It also specifies the exact behavior of checking how crawlers see the page. No contradiction with annotations.

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 description is concise, with a clear structure: what it does, when to use, constraints. Every sentence adds value, front-loaded with the primary purpose.

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 without an output schema, the description lists the exact information returned (title, description, image per platform, og:image details, problems with fixes) and all constraints (public http(s), fetch limits). No missing information for an agent to decide to call it.

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 covers the only parameter (url) at 100%. The description does not add meaning beyond the schema; it only references the URL in context. Baseline 3 is appropriate.

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 clearly states the tool's function: fetching a page as social crawlers do and reporting the effective title, description, and image per platform, plus image details and problems. It distinguishes from siblings like preview_card or og_image_url by focusing on cross-platform preview analysis.

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?

Provides explicit usage context ('when a user asks why their link looks wrong when shared, or before publishing') and constraints (http(s), public, fetch limits). Does not mention alternatives or when-not-to-use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond that: it returns HTML plus diagnostic notes, and it explicitly states that nothing is fetched and no API key is needed. It doesn't detail what happens with invalid inputs, but the annotations plus the 'nothing is fetched' note cover the main behavioral risks.

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?

Three sentences, each earning its place: what it builds, what it returns, and when to use it. The most important information (output and usage) is front-loaded, and there is no filler or repetition of schema content.

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 10-parameter tool with 100% schema coverage and no output schema, the description covers the key context: what the output looks like (HTML plus notes), when to use it, and that it makes no network calls. It doesn't mention the return format in detail, but the description's mention of 'Returns HTML to paste plus notes' is sufficient for an agent to know what to expect. The only minor gap is not explaining how the diagnostic notes are structured, but that's not essential for invoking the tool.

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 schema already documents all 10 parameters. The description adds a little extra meaning by mentioning og:image width/height and the diagnostic notes, but it doesn't add significant semantics beyond the schema. Baseline 3 is appropriate.

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 states a specific verb ('Build') and resource ('the complete <head> block for a page'), enumerating the exact tag types produced. It clearly distinguishes itself from sibling tools like check_link_preview and render_card by focusing on HTML tag generation rather than previews or image rendering.

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 explicitly says when to use it: 'Use after check_link_preview, or whenever a user needs the tags for a new page.' It also states a non-requirement ('No API key needed; nothing is fetched'), which helps an agent decide this is a pure generation tool and not a network call.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds value beyond that by specifying the authentication requirement ('Needs an API key') and detailing the output content (plan, watermark, quota used/remaining/reset date), which is essential since there is no output schema. This goes beyond the annotations.

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?

Three crisp sentences with no filler. The first line front-loads the output information, the second covers authentication, and the third gives usage guidance. Every sentence earns its place, making it efficient for an agent to parse.

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 zero-parameter read-only tool with no output schema, the description fully covers what the agent needs: the data returned (plan, watermark, quota used/remaining/reset date), the requirement for an API key, and when to invoke it. There are no missing details that would hinder correct usage.

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?

The input schema has zero parameters, so there is nothing for the description to explain. The description still adds the helpful context that an API key is required, which is not a parameter but a prerequisite. With no parameters, the baseline is 4, and the description meets that without needing to compensate for schema gaps.

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 states exactly what the tool returns: the API key's plan, watermark status, and monthly quota details (used, remaining, reset date). This is a specific resource (usage/quota) and is clearly distinct from sibling tools that deal with card rendering or meta tags, so an agent can easily identify its purpose.

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 scenarios: 'Check it before batch renders, or when a render came back watermarked unexpectedly.' This tells the agent exactly when to call it, and because the tool is unique among siblings, no exclusion is needed. This is direct, actionable guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds 'No API key needed' — a useful authentication trait not covered by annotations. It also describes the response fields, which is additional behavioral context. It does not discuss pagination or rate limits, but for a read-only listing tool with strong annotation coverage, this is sufficient.

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?

Three sentences with no fluff: the first lists what is returned, the second tells when to use it and gives the next step, and the third states authentication. Key information is front-loaded, and every sentence earns its place.

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 simple read-only tool with no required parameters and no output schema, the description covers the essential context: what the tool returns, when to invoke it, the follow-up action, and auth requirements. It does not mention result ordering or pagination, but those are minor gaps for a preset-listing tool, so completeness is high but not perfect.

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 baseline is 3. The description does not add parameter-level detail beyond the schema; it mentions return fields like 'one-line look description' which relates to query, but it does not elaborate on how to combine filters or value formats. The schema already carries the semantic weight, so a 3 is appropriate.

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 clearly states the tool lists ready-made starter designs and enumerates the exact fields returned (key, name, template kind, native size, categories, look description, preview URL). It distinguishes itself from saved-template workflows by using 'presets' and 'no saved template', and it names preview_card as the follow-up, helping an agent pick it apart from list_templates.

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 guidance: 'Start here when the user wants a social card and has no saved template' and then directs to preview_card. It establishes a clear context and next step, but it does not explicitly name the alternative (e.g., list_templates) for cases where a saved template exists, so it falls short of a full when/when-not/alternatives statement.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the API key requirement and clarifies the returned fields, which is useful behavioral context beyond the annotations.

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?

Three sentences, each earning its place: what is returned, the auth requirement, and when to call it. Front-loaded with the resource and fields, then usage guidance.

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 parameterless read-only list tool, the description covers the resource, the returned fields, the auth requirement, and the usage context. It doesn't describe pagination or output format, but with no output schema and a simple list operation, the provided information is sufficient for an agent to call it correctly.

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?

The tool has zero parameters, so the schema is trivially complete. The description adds value by explaining what the returned data contains, which is the relevant semantic content for a parameterless list operation.

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 clearly states the tool lists the user's saved templates and enumerates the fields returned (slug, name, kind, render_card/og_image_url overrides, last edited). It distinguishes itself from siblings by naming render_card and og_image_url as tools that need the slug from this list.

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?

Explicitly says to call this before render_card or og_image_url when the slug is unknown, and notes an API key is required. This gives clear when-to-use guidance and names the alternatives it feeds into.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: nothing is rendered now, image is generated on crawler fetch, cached at edge for a day, and each uncached fetch spends one image of monthly quota. This goes beyond annotations and helps the agent understand side effects (quota consumption) despite readOnlyHint.

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 description is well-structured and front-loaded: it states the core function first, then key behavioral facts (deferred rendering, caching, quota), then usage context, then return value. Every sentence earns its place, and it's appropriately sized for the tool's complexity.

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 description covers the essential context: what it does, when to use it, behavioral traits (deferred rendering, caching, quota), and return value (URL and meta tag). It doesn't explicitly mention the API key requirement in the schema, but the description does. Given the rich schema and annotations, this is nearly complete. Minor gap: no explicit mention of error cases or rate limits beyond quota, but that's acceptable.

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 schema already documents all parameters thoroughly. The description adds context about the template being from list_templates or save_template, and mentions the fields object semantics (omit to keep template's own text), but this is largely redundant with the schema. Baseline 3 is appropriate.

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 clearly states the tool's function: building a signed image URL for a saved template, ready for an og:image meta tag. It distinguishes itself from siblings by emphasizing the zero-infrastructure, URL-only approach (no rendering now, crawler fetches later), which differentiates it from render_card, preview_card, and card_from_url.

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 explicitly says when to use this tool: in page templates, CMS hooks, and static site generators, as the zero-infrastructure way to give every page its own card. It also implies when not to use it (when you need immediate rendering, use render_card/preview_card instead), and mentions the API key requirement. This is strong usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable context beyond annotations: free, no API key, watermark, does not touch quota, and returns the image inline. This enriches the behavioral profile without contradicting annotations.

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?

Three sentences, each earning its place: action, cost/watermark, usage and alternatives. Front-loaded with the primary purpose, no filler or redundancy.

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 preview tool with a nested fields object and rich schema, the description covers the core purpose, cost, watermark, and alternative routes. It clearly states the return is an image shown inline, and the schema covers layout restacking. Minor gap: no mention of error scenarios, but that's not essential for basic invocation.

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%, with rich per-field descriptions (e.g., enum values, character limits, template-specific behavior). The description adds no extra parameter context beyond the schema, so baseline 3 is appropriate.

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 states a specific verb and resource: 'Render a preset with the user's text and return the image'. It also distinguishes itself from siblings like render_card by mentioning the watermark and free nature, making the purpose unambiguous.

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?

Explicitly states when to use: 'Use it to show the user what their card will look like before they commit.' Provides clear alternatives for clean images (save_template + render_card on a paid plan) and explicitly contrasts with the editor's clean download. No ambiguity about when to choose this tool.

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

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

The description discloses the API key requirement, the quota consumption ('Each call spends one image of the monthly quota'), the watermark differences between paid/free tiers, and the output format (PNG shown inline at 1x). These go beyond the annotations (which already note readOnlyHint=false, so a non-read operation is expected). The quota cost and auth requirement are valuable extra context.

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 description is compact and front-loaded. The core purpose is stated in the first sentence, followed by side effects, then usage guidance. No filler or tautology; every sentence provides new information.

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 no output schema, the description clearly states the return format (PNG inline), the auth requirement, the quota cost, and the watermark distinction. It also mentions the template source from list_templates or save_template via the parameter schema. The guidance to prefer og_image_url for specific cases completes the picture for correct invocation.

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%, and each parameter (size, fields, template) already has thorough descriptions within the schema. The main description adds nothing beyond the schema (it only says 'with the given text'), so it does not exceed the baseline for high-coverage schemas.

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 precise verb and object: 'Render one of the user's saved templates with the given text and return the PNG'. It also names the sibling og_image_url and explains when to choose it instead, so it clearly differentiates from the family of tools.

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?

Explicit guidance is given: 'Use it when the user wants the actual file, e.g. to host it themselves' and 'For an og:image tag that needs no hosting, or for a 2x retina file, prefer og_image_url.' This directly addresses when-to-use and when-not-to-use, with a named alternative.

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

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

Annotations are minimal (readOnlyHint=false, no idempotency), so the description carries the burden. It discloses that an API key is needed, that it returns a slug and editor link, and that the design never changes. It does not mention side effects like overwriting existing templates or error conditions, but it provides meaningful behavioral context beyond the annotations.

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 description is compact and front-loaded with the core action, then adds usage guidance and return value. Each sentence earns its place, and it avoids redundancy with the schema. The structure is easy to scan and the information is well-ordered.

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 nested objects and multiple optional parameters, the description covers the essential context: the API key prerequisite, the intended usage pattern, the return value (slug and link), and the guarantee that design stays unchanged. It does not detail error handling or specific output formats, but given no output schema, the description provides enough for an agent to call it correctly.

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%, but the description adds meaning beyond the schema by explaining that fields are optional ('Omit a field to keep the template's own text') and that the 'fields' object sets new defaults. This clarifies the semantics of the 'fields' parameter beyond its schema descriptions, helping the agent understand how to use it correctly.

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 uses a clear verb ('Copy a preset into the user's account as a saved template') and identifies the resource (preset) and outcome (template usable by render_card and og_image_url). It distinguishes itself from sibling tools like render_card, list_presets, and og_image_url by focusing on the save operation, and it states the returned slug/link, making the tool's role unambiguous.

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 guidance: 'Do this once per design, not per image' and explains that after saving, every render only passes changing text. It also notes the API key requirement. It does not explicitly name alternatives or say when not to use it, but the guidance is clear enough for an agent to decide when to invoke it relative to siblings like render_card.

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