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

Goes well past the annotations by disclosing the return shape (inline base64 plus format, dimensions, size), the file-write sandbox (~/Downloads/opengraph-mcp or MCP_EXPORT_DIR, name or path inside it only), and the security-driven exception that SVG is never returned inline because it can carry script.

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?

Front-loads purpose, then returns, then constraints, then usage examples. Slight redundancy: the destinationPath folder rule is restated almost verbatim in both the paragraph and the usage block.

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?

An output schema exists so return values needn't be spelled out, and annotations plus description cover safety and side effects. It omits failure modes (expired session, unknown assetId) that would help an agent recover from errors.

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 a baseline 3 applies, but the description adds real meaning: sessionId/assetId come from a prior generateImage call, and destinationPath is transport-conditional and confined to the export folder.

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 and resource ("Export a generated image asset by session and asset ID") and ties itself to the generateImage lifecycle, so an agent can distinguish it from inspectImageSession or iterateImage without opening a schema.

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 an explicit prerequisite ("After generating an image with generateImage") plus concrete call examples, and states the local/stdio condition for destinationPath. It never names an alternative tool for inspecting or listing assets, so the when-not guidance is incomplete.

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 extensively discloses behaviors: three methods for diagram creation, newline encoding, D2 syntax rules, output styles (draft/standard/premium), cropping options, and warnings about mixing syntax. Annotations indicate readOnlyHint=false and destructiveHint=false, and the description aligns with these, providing additional context about iterative refinement and non-destructive edits.

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 excessively long, containing multiple sections, numerous examples, and detailed warnings. While well-organized with headings, it lacks conciseness; an AI agent would need to parse a large amount of text to extract key information. Front-loading is present but the sheer volume makes it inefficient.

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?

Given the tool's complexity (26 parameters, 0 required, output schema exists), the description is highly complete. It covers all major usage patterns, error-prone cases (e.g., mixing syntax), parameter interdependencies, and provides practical examples. The output schema exists, so return value explanation is not required.

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?

Despite 100% schema description coverage, the description adds substantial value beyond the schema: it explains how diagramCode and prompt interact, provides copy-paste ready examples for each diagram format, details aspect ratio presets, stylePreset meanings, outputStyle effects, and cropping usage. This greatly enhances understanding of parameter usage.

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 purpose: 'Generate professional, brand-consistent images optimized for web and social media.' It lists specific use cases (blog heroes, OG images, social cards, diagrams, etc.) and provides quick start examples, distinguishing it from sibling tools which are URL/image inspection tools, not generation 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?

The description includes a section 'WHEN TO USE THIS TOOL (prefer over built-in image generation)' listing explicit scenarios and 'WHY USE THIS INSTEAD OF BUILT-IN IMAGE GENERATION' with reasons. It provides clear context for when to use this tool versus alternatives, and since siblings are not image generation tools, the guidelines are unambiguous.

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, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds important behavior: 500-credit fresh analyses, 1-credit cached reads, cache keying by URL plus sections, synchronous latency up to a minute, server-side rendering/proxies, and nulls for insufficient evidence. It is rich, but the annotations carry substantial burden and the description does not contradict them.

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 purpose and return shape are front-loaded, and the later cost and caveat paragraphs are relevant to correct use. It is longer than typical, but the structure keeps the high-value routing, billing, and reliability details easy to scan.

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?

With an output schema present, the description does not need to explain return values in full, but it still summarizes the profile sections and caveats such as null evidence and ranked color candidates. Together with rich annotations and 100% schema coverage, it gives an agent everything needed to call the 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema about cache_ok, sections, and questions: changing sections or adding questions forces a fresh billed run, skipping sections does not lower cost, and custom questions are never cached.

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: building a structured brand profile for a website via the Brand Intelligence API. It enumerates the returned categories and explicitly distinguishes this tool from getOgData and getOgMarkdown for single-page needs, so an agent can identify it without opening the schema.

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 exactly when to use this tool: to understand or write as a brand. It also names the alternatives, getOgData and getOgMarkdown, and the condition that selects them: a single page. Cost and cache rules further guide invocation decisions.

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/openWorldHint, so safety is covered; the description adds genuine behavioral context the annotations cannot — that results are merged from three sources with a documented precedence (`hybridGraph` best-of) and that gaps are auto-filled. It omits cost/credit implications, which a sibling (getOgQuery) does disclose, leaving a small gap for a 24-parameter network call.

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?

Purpose, return shape, and the key consumption instruction are front-loaded in the first two sentences before the routing table. Every line of the routing table contributes to sibling selection, so nothing is padding despite the length.

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?

An output schema exists, so return values needn't be re-explained, and the 24-parameter schema is fully documented. Annotations cover the read-only/idempotent profile, and the description covers source-merging behavior and sibling routing. Only the credit/cost dimension, which matters for a proxy-heavy external API, is left unstated.

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 explains every one of the 24 parameters, including retry, proxy tiers, and render modes. The description adds no parameter-level syntax, defaults, or interaction rules beyond what the schema states, so the baseline score of 3 applies.

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 opening sentence names a specific verb ('Fetch') and resource ('Open Graph metadata, HTML-inferred tags, hybrid social preview data') for 'any URL', and further decomposes the return into three named sources. An agent can distinguish it from getOgMarkdown, getOgScrapeData, and getOgExtract from the description alone, without opening any schema.

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 'Pick the right tool' block explicitly enumerates every sibling's purpose and the condition that selects it (raw HTML for own parsing, prose for LLM feeding, screenshot for visual capture). It also gives an in-tool directive: use `hybridGraph` as the primary source because it fills gaps. This is the strongest form of routing 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 readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description goes beyond them by documenting that return shape varies by parameter combination (html_elements only → concatenatedText; selectors → data + concatenatedText; both → data + concatenatedText) and by flagging cost on the sibling query tool. It stops short of disclosing credit cost, rate limits, or failure behavior for this tool, which keeps it at 4 rather than 5.

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?

Front-loaded with the two modes and their response shapes, then routing and JS-rendering tips — a strong information hierarchy. A few lines restate schema content (e.g., the html_elements tag-list example), so it is slightly longer than strictly necessary, but no section is wasted.

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?

Output schema exists, so return values need not be explained, yet the description still summarizes them per mode, which aids selection. For a 25-parameter tool the coverage of proxy tiers, caching, retry escalation, load-more, and sanitize modes is left entirely to the schema; that is acceptable given 100% schema coverage but leaves the behavioral picture partial.

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 the 3 baseline is already met by structured fields; the description still adds real value by showing an example selector map, explaining that labels become keys of the returned data object, and clarifying the concatenation behavior of html_elements. It does not touch the many proxy/cache/retry/ai_sanitize knobs, leaving those entirely to 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?

States a specific verb and resource ('extract specific content from any URL') and immediately decomposes the tool into its two operational modes, tag-based vs selector-based. The 'Pick the right tool' block explicitly differentiates it from getOgData, getOgMarkdown, getOgScrapeData, and getOgQuery, so an agent can select it without opening sibling schemas.

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 routing table names every sibling and the condition that selects each, plus which mode of this tool to use for bulk text vs named fields. It also gives conditional guidance inside the tool itself ('for JS-heavy / SPA pages set full_render: true', 'use wait_for_selector when content loads asynchronously').

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 readOnly/idempotent/openWorld, but the description adds genuinely non-derivable behavior: the 6,000-character text-block cap with full content in the structured markdown field, default boilerplate stripping, automatic render escalation for JS-heavy pages, and HTTP 422 as the block-mode failure mode. These are exactly the operational facts an agent needs and none appear 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?

Front-loads the core purpose, then uses labeled sections (LONG PAGES, EXTRAS, UNTRUSTED CONTENT, Pick the right tool) that scan well. It is on the long side and the sibling list partially duplicates information available from the sibling tools' own descriptions, which costs a point.

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 40-parameter open-world fetch tool with an output schema, the description supplies everything an agent needs to choose it, pick a retrieval strategy, and handle untrusted output safely. Return-value detail is correctly delegated to the output schema, with only the one non-obvious cap called out.

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 baseline would be 3; the description earns above that by explaining intent rather than syntax — the include_links/include_images/include_headings rationale ("avoids a second scrape call"), the query-vs-max_chars tradeoff, and the sanitize/warn/block semantics. With 40 parameters it still can't cover most of them, so it stops short of a 5.

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?

Opens with a specific verb+resource+mechanism ("Convert any URL's HTML into clean Markdown via the OpenGraph.io API") and immediately states the transformation outcome (strips nav/ads, main-content prose). The 'Pick the right tool' block explicitly contrasts it against getOgScrapeData, getOgExtract, getOgQuery and getOgData, so an agent can disambiguate without opening a schema.

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 an explicit routing table mapping each sibling to the case it serves, plus conditional guidance within the tool itself (use query+chunking for long pages, max_chars only when prose is genuinely needed, ai_sanitize when output feeds a model). When-to-use, when-to-prefer-alternatives, and when-not are all covered.

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, openWorldHint, destructiveHint and idempotentHint, so safety is covered. The description adds genuinely non-redundant context: a per-request credit cost of 100 (200 on the 'mini' model) and a cost of 1 for a cached answer, which materially affects whether an agent should call it repeatedly. It stops short of mentioning rate limits, latency or error behavior.

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 tight sentences: core behavior first, optional structured mode second, cost implications last. Every sentence earns its place and nothing is padded.

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?

With an output schema present, 100% parameter documentation and annotations covering the safety profile, the description needs to carry only the extras. It supplies the cost model, which is the main thing missing from structured fields, but could note cache-vs-fresh behavior more explicitly given that cache_ok is a first-class parameter.

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 all 18 parameters are already documented in structured data and the baseline is 3. The description repeats the responseStructure option and echoes the mini/nano cost difference that the modelSize schema field already states, adding little semantic detail the agent does not already have.

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 and resource: ask a natural-language question about any URL and receive an AI-generated answer, with an optional structured-data mode. The purpose is unambiguous, but nothing in the text tells the agent how this differs from siblings like getOgExtract, getOgData or getOgMarkdown, which cover overlapping ground.

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 phrasing 'ask a natural-language question about the content of any URL' implies when it is appropriate, and the 'optionally pass a responseStructure' clause hints at a structured-extraction variant of that use. However, there is no explicit when-to-use guidance, no exclusions, and no named alternative such as getOgExtract for extraction-only needs.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: the text response is truncated at 3,000 characters while full HTML lives in the structured `html` field, and it explains the auto_render vs. full_render performance trade-off. It does not state this tool's own credit cost or auth requirements, leaving some operational context out.

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?

Front-loaded with the core purpose and the key output caveat (3,000-char truncation) before any options or routing. The sibling routing table is somewhat long and partially duplicates what those siblings likely say themselves, but for a family of six near-identical fetch tools it justifies its space.

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?

An output schema exists, so return values need no explanation, but the description still clarifies the truncated `text` vs. full structured `html` split, which is the most likely source of agent error. For a 23-parameter, open-world scraping tool, only the omission of per-request credit cost and any auth/rate-limit notes keeps it from a 5.

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% across 23 parameters, so the baseline would be 3. The description earns a point by adding guidance the schema alone doesn't convey: prefer auto_render for most cases, reserve full_render for guaranteed JS execution when auto_render fails, and that wait_for_selector forces full_render.

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 and resource ("Scrape and return the raw HTML of a URL via the OpenGraph.io API v3") and immediately contrasts with siblings via a 'Pick the right tool' table. An agent can distinguish this from getOgMarkdown, getOgExtract, or getOgData without opening any schema.

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 use conditions ("when you need to do your own parsing, extract all links, inspect the DOM structure, or feed raw markup into another tool or model") and an enumerated routing table naming every sibling with its purpose. Selection between alternatives is fully determined by the text.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, and the description adds the single most important non-obvious behavior: it returns a hosted `screenshotUrl` rather than inline image bytes. It does not mention credit cost for this tool (only for getOgQuery) or latency expectations for full-render captures, which would have completed the picture.

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?

Front-loaded with purpose, then return-shape, then a compact routing table — all three sections are load-bearing. Slightly over-long: the credit note on getOgQuery is irrelevant to invoking this tool and could be trimmed from this description.

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 24-parameter capture tool with an output schema and full schema coverage, the description supplies purpose, capability surface, return shape, and sibling routing — nothing an agent needs in order 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%, so the baseline is 3; the description earns the bump by grouping the 24 parameters into scannable capability buckets (capture mode, viewport dimensions, dark mode, format/quality, cookie-banner dismissal, selector include/exclude). It adds no syntax or default details beyond what the schema already supplies.

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 and resource ('Capture a screenshot of any URL') and immediately enumerates the capability envelope: full-page/viewport, dimensions, dark mode, format/quality, cookie-banner dismissal, selector targeting/exclusion. The routing table explicitly separates it from getOgData, getOgMarkdown, getOgScrapeData, getOgExtract and getOgQuery.

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?

Contains an explicit 'Pick the right tool' decision table mapping each sibling to its output type, plus the downstream usage instruction ('use this URL directly in a browser, an <img> tag, or pass it to another tool'). An agent can select this tool with no inference required.

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 declare readOnlyHint=true and destructiveHint=false. The description adds valuable context beyond that by detailing what information is returned (metadata, assets, relationships), which helps the agent understand the tool's output 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?

The description is concise, uses bullet points for clarity, and front-loads the main purpose. Every sentence adds value without 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?

Given the output schema exists, the description covers the essential aspects: returns session metadata, asset lists, and relationships. It is complete for a read-only inspection tool with clear use cases.

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 the only parameter sessionId having a format and description. The description does not add additional semantic details about the parameter, 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 clearly states 'Retrieve detailed information about an image generation session and all its assets,' specifying the verb, resource, and scope. It distinguishes from sibling tools like generateImage and iterateImage.

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 lists three use cases: reviewing session content, finding asset IDs for iteration, and understanding history/toolchains. This provides clear guidance on when to use this tool, with no mention of when not to use, but the use cases imply exclusions.

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 indicate readOnlyHint=false (mutation) and destructiveHint=false. The description adds value by detailing behaviors like editing parts, style changes, cropping, and fixing issues, and advising to include source for diagrams to preserve structure.

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 with bullet points and numbered steps, front-loading the main purpose. Every sentence adds value, and it is appropriately concise without being terse.

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?

Given the tool's complexity (7 parameters, 3 required, output schema present), the description covers editing, cropping, and diagram iterations with guidance on preserving source. It fulfills all informational needs 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%, providing descriptions for all 7 parameters. The description enhances this with examples for the prompt parameter (e.g., 'Change the primary color to #0033A0') and clarifies the cropping coordinates as top-left and bottom-right, aiding the agent.

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 specific verbs like 'refine', 'modify', and 'create variations' on an existing image, clearly distinguishing it from sibling tools like generateImage (new image) and exportImageAsset (exporting). The list of use cases further clarifies the scope.

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 states 'Use this to:' followed by concrete scenarios, and provides a specific 'For diagram iterations:' section with numbered steps. While it doesn't explicitly state when NOT to use, the purpose is clear and contrasts well with siblings.

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