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/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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-redundant behavior: the response shape varies by mode (concatenatedText vs data vs both) and the render-before-extract semantics. It omits any mention of credit cost or rate limits for this specific call, which the sibling getOgQuery does disclose.

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: mode distinction comes first, then response shapes, then tool routing. Bold headers and a response-shape list make it scannable. The routing block is long and the response-shape bullets restate some schema behavior, so a little space is not strictly earned, but nothing is confusing.

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 25-parameter tool with an output schema, the description covers the two extraction paths, their outputs, and the async/SPA rendering levers. The proxy tiers, retry controls and load-more parameters are left to the 100%-covered schema, which is a reasonable division of labor. Credit cost is the only notable omission.

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 baseline is 3. The description earns above that by explaining the interaction between the two extraction parameters — that supplying both yields data plus concatenatedText, and that the concatenated string is the joined text of all matches — semantics not stated in either schema entry.

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 it into two named extraction modes with their parameter names. The explicit routing table distinguishes it from getOgData, getOgMarkdown, getOgScrapeData, getOgQuery and getOgScreenshot without the agent needing to open 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 when-to-use guidance for each mode ('Best for bulk content extraction' vs 'ideal for structured scraping of specific named fields') and a per-sibling disambiguation list. Also states the conditional escalation rule for full_render and wait_for_selector. Nothing is left to inference.

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 cover read-only, non-destructive, open-world, non-idempotent behavior, so the description's job is the extra layer, and it delivers: 100 credits per request (200 with a large model) is operationally important and appears nowhere in structured fields. The v1.1/v3 billing note is somewhat internal trivia, and it doesn't mention rate limits or latency, keeping it short of a 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?

The core purpose and the cost warning are front-loaded in two tight sentences. The trailing sentence about the Query API staying on v1.1 until the billing path check is updated is internal implementation detail that doesn't help an agent decide or call correctly, so it is the one clause that doesn't fully earn 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?

With an output schema present and rich annotations, the description only needs to add purpose and cost, and it does both. The main residual gap is that it says nothing about whether structured output honors responseStructure failures or how large a page can be, but nothing essential to invoking the tool 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 all 18 parameters are already documented, including the modelSize cost tiers and the ai_sanitize_mode behaviors. The description only restates the responseStructure option that the schema already explains, adding no syntax, defaults, or interaction guidance beyond it — baseline 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 first sentence states a specific verb and resource: ask a natural-language question about a URL's content and get an AI-generated answer. That clearly separates it from passive scrapers like getOgScrapeData or getOgMarkdown, though it never names those siblings explicitly, so the differentiation is inferred rather than stated.

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?

Usage is implied by the verb phrasing — use this when you need an answer rather than raw content — but there is no explicit when-to-use vs. getOgExtract or getOgData, and no guidance on when the optional responseStructure path is preferable. The credit note hints at cost sensitivity without telling the agent when to avoid 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?

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.