betterimage.io

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

Annotations already declare readOnly, idempotent, and openWorld hints, but the description adds valuable behavioral detail: it fetches the page like a crawler, Jev decides over every preset in about 100 ms, the image is watermarked/free, no API key is needed, and passed fields override page content. This goes well beyond the structured hints.

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 dense but every sentence earns its place: core function first, then behavior, then usage direction, then override semantics, then fallback. The quoted user request and the list_presets pointer are functional, not 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?

There is no output schema, but the description explains the return value is an inline watermarked image and covers the fetch/render pipeline, no-auth requirement, and one-call behavior. The rich input schema covers the parameters; the only notable gap is what happens when the page fetch fails, which is not essential for tool selection.

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% with detailed per-field descriptions, including card-type restrictions and the image2_url dependency. The prose adds cross-cutting meaning: any passed field overrides what the page says, preset and size are alternative design controls, and the fallback is og-essay-light.

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 action and resource: 'Make a social card for a page that already exists, in one call.' It explains the full pipeline — fetching the page, extracting title/description/author/domain/icon, picking a design, and returning the image — which clearly distinguishes it from siblings like list_presets or render_card.

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 gives explicit when-to-use guidance: 'Use this first when the user gives a URL' with a concrete user phrasing example. It does not explicitly name sibling tools as the when-not alternatives, though it does point to list_presets for overriding the design choice.

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, idempotentHint, and openWorldHint. The description adds valuable non-schema behavior: it enumerates the return fields (key, name, template kind, native size, categories, look description, preview URL), notes that no API key is needed, and suggests the next logical call. This is rich context beyond the structured 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?

Four concise sentences, each earning its place: the first defines the resource and output fields, the second gives usage context, the third specifies the next step, and the fourth clarifies authentication. Information is front-loaded and there is no 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 simple read-only list tool with no output schema, the description is fully complete: it covers what the tool returns, when to use it, how to proceed with a chosen key, and auth requirements. The annotations cover safety and idempotency, and the schema covers the optional filters. Nothing an agent needs to call it correctly is missing.

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 detailed descriptions and enums for kind and category. The tool description does not add parameter-level detail beyond the schema, but it does not need to; baseline 3 is appropriate when the schema already carries the burden.

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?

States a specific verb ('Browse') and resource ('ready-made designs (presets) a card can start from'), and lists the exact fields returned. It distinguishes itself from list_templates by framing presets as ready-made designs used when there is no saved template, so an agent can tell them apart.

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 explicit when-to-use guidance: 'Start here when the user wants a social card and has no saved template.' It also names the follow-up action (preview_card). However, it does not explicitly name the alternative tool or state when not to use it beyond that conditional, so it stops short of a perfect 5.

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?

The description adds substantial behavioral context beyond the annotations: the image is generated only when a crawler fetches the URL, results are cached at the edge for a day, each uncached fetch consumes one image of the monthly quota, and an API key is required. These details are not present in the annotations and materially affect whether an agent should call this tool.

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 three dense sentences that front-load the purpose, then add the critical behavioral details (deferred generation, caching, quota, auth) and end with the return value. Every sentence earns its place and there is no padding.

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?

Even though there is no output schema, the description states what is returned ('the URL and the ready meta tag'). The schema covers all parameters thoroughly, and the description supplies the operational context—API key, caching, quota, and rendering timing—needed to invoke the tool safely and understand its effects.

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 detailed per-field descriptions for template, size, scale, and fields. The description itself adds little parameter-level meaning beyond mentioning 'saved template' and 'given text,' so the baseline of 3 applies without needing extra compensation.

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: 'Build a signed image URL for a saved template... ready to put in a page's <meta property="og:image"> tag.' It also distinguishes itself from rendering tools by explicitly saying 'Nothing is rendered now' and by framing the output as a URL and meta tag, which separates it from siblings like render_card and preview_card.

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 concrete usage contexts: 'use it in page templates, CMS hooks and static site generators' and calls it 'the zero-infrastructure way to give every page its own card.' It does not explicitly list when not to use it or directly compare itself to alternatives like card_from_url or generate_meta_tags, so it stops short of a 5.

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 the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral context: it is free, requires no API key, carries a betterimage.io watermark, and does not touch any quota. It also states that the result is returned as an image shown inline. This is valuable context not present in 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 with no filler. The core function is front-loaded, followed by key constraints (free, watermark, no quota), then a clear use case and alternative. 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?

The description covers the tool's purpose, output behavior, cost/watermark implications, quota impact, and the alternative clean-image flow. The schema already documents the preset parameter and field semantics, so nothing essential is missing for an agent to select and invoke this tool 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 description coverage is 100%, so the input schema fully documents all parameters, including the preset key and nested fields object. The description itself adds little parameter-level detail beyond 'with the user's text' and 'from a preset', but that is acceptable given the schema carries the load.

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: 'Render a preset with the user's text and return the image'. It also differentiates itself from render_card by framing this as a free, watermarked preview versus the 'clean image' path. This leaves no ambiguity about what the tool does.

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 explicitly states when to use this tool: 'Use it to show the user what their card will look like before they commit.' It also names alternatives for the clean-image case: 'save_template + render_card on a paid API plan, or the one-off clean download in the editor.' This gives clear when and when-not 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?

Beyond annotations, the description discloses key behavioral context: an API key is required, free-tier renders are watermarked, and each call consumes one image from the monthly quota. This is consistent with idempotentHint=false and adds actionable details not present in the schema or 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?

Every sentence earns its place: it covers function, output format, auth, quota, watermarking, and when to prefer an alternative. It is front-loaded with the core behavior and does not waste words.

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 a nested object, no output schema, and non-trivial quota implications, the description plus rich schema is complete. The agent learns the output format, the constraints, and the alternative, and the schema covers every parameter in detail.

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 input schema already fully documents all three parameters, including the nested fields and enumerations. The description adds only general context like 'with the given text' and does not need to repeat parameter-level syntax.

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 one of the user's saved templates with the given text and return the PNG'. It also distinguishes itself from sibling og_image_url by clarifying that render_card produces the actual file while og_image_url is for hosted tags.

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 explicitly says when to use this tool ('when the user wants the actual file, e.g. to host it themselves') and when not to ('For an og:image tag that needs no hosting, or for a 2x retina file, prefer og_image_url'). This gives the agent a clear routing decision.

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 indicate this is a mutating, non-idempotent action. The description adds useful behavioral context: API key requirement, return values, and the workflow warning that implies repeated saves are not needed. It does not contradict annotations, and it reveals the non-idempotent nature by telling the agent to save once per design.

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?

Four sentences, each earning its place: purpose, authentication, usage frequency, and return value. The most important information is front-loaded and there is no 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 tool with a nested fields object and no output schema, the description covers the key missing pieces: what the return value is, how to use it next, and the once-per-design pattern. The rich schema handles parameter-level detail, so only explicit error/limit behavior is absent.

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%, and each parameter is thoroughly documented in the schema. The description adds conceptual value by explaining that fields become the template's defaults and that the slug is returned, but it does not need to repeat schema details.

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 specific verb and resource: 'Copy a preset ... into the user's account as a saved template'. It also names the downstream consumers (render_card and og_image_url), which clearly separates this tool from siblings like list_presets and 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 clear workflow guidance: 'Do this once per design, not per image: afterwards every render only passes the text that changes.' It explains why and when to call the tool, though it does not explicitly state exclusions or alternative tools.

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