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

Annotations already mark the operation as destructive and idempotent, so the description need not repeat those. It adds meaningful context by stating the deletion is permanent and the fix items cannot be regenerated by re-running the audit, which informs the agent about irreversible consequences beyond the annotation flags.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, stating the core action in the first sentence. The second sentence earns its place by explaining irreversibility and providing a confirmation instruction, with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter destructive action with an output schema and strong annotations, the description covers what the tool does, how to confirm usage, and where to source the item ID. Nothing essential is missing 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%, so the baseline is adequate. The description adds real value by specifying that fixItemId must come from listFixItems, preventing arbitrary or guessed IDs. auditId remains minimally documented, but the high schema coverage keeps this dimension strong.

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 ('remove') and a clear resource ('entry from an audit's fix list'), making the operation unmistakable. It also distinguishes the tool from sibling fix-list tools like listFixItems and saveFixItems by framing this as a permanent deletion.

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 provides actionable usage guidance: confirm with the user before deleting, and obtain fixItemId from listFixItems. It does not explicitly enumerate when not to use this tool versus other deletion tools like deleteSiteAudit, but the guidance is clear and sufficient for the intended use.

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 goes well beyond the annotations (destructiveHint=true) by detailing the permanent consequences: results disappear, history and trend are affected, and re-running produces a new audit that does not restore the old one. It also adds a user-confirmation requirement, which is critical for a destructive operation. No contradictions 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 well-structured with the core action in the first sentence, followed by a concise explanation of irreversibility and the confirm-with-user instruction. Every sentence adds value, with no redundancy or unnecessary details.

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 single-parameter destructive tool, the description is fully complete: it states what is deleted, the irreversible nature, the impact on history and trend, and the need for user confirmation. Since an output schema exists, the lack of return-value explanation is not a gap.

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 already provides a clear description for auditId ('The audit to delete.') with 100% coverage. The description reiterates that the exact named audit should be deleted, which adds minimal extra meaning. It does not introduce new parameter details, so the 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 description clearly states the verb (delete), the resource (audit), and the full scope (all results, page scores, issues, fix items). It is easily distinguishable from sibling tools like deleteFixItem or startSiteAudit, as it explicitly targets audits and their associated data.

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 provides clear context on when to use it (to permanently delete an audit) and includes a safety instruction to confirm with the user before deleting. It does not explicitly list alternatives or when not to use it, but the specificity of 'audit' versus other tools makes the usage 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: crawling and sitemap parsing, return of URL list grouped by depth, remaining audit quota, and 'siteContextText' to be passed to startSiteAudit. 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 well-structured and front-loaded: purpose first, then return info, usage instructions, and sibling differentiation. Every sentence adds value without unnecessary fluff.

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 fully explains the tool's input (one domain parameter), output (URLs grouped by depth, audit quota, siteContextText), and how to use the output (pass siteContextText to startSiteAudit, discuss with user). With an output schema present, the description covers all necessary context.

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 one parameter 'domain' already described as needing protocol. The description does not add new semantic meaning beyond the schema; it repeats the requirement to include the protocol. 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 purpose: 'Discover all pages on a domain by crawling it and parsing its sitemap.' It uses a specific verb 'discover' and resource 'all pages on a domain'. The sibling differentiation section explicitly distinguishes it from startSiteAudit and previewPageAudit.

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 when-to-use: 'Use this as the first step before starting a full site audit.' It also provides a post-call instruction: present URL list to user and ask for page selection. The 'Pick the right tool' section gives clear alternatives and steps.

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?

It goes well beyond the annotations by warning 'THIS SENDS REAL EMAIL EVERY TIME IT IS CALLED,' stating non-idempotence, and advising not to retry on timeout without user confirmation. It also adds recipient, entitlement, and rate-limit constraints that annotations alone do not convey.

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 primary action is front-loaded, the critical side-effect warning is prominent, and every subsequent sentence adds operational value. There is no filler or repetition.

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 annotations, schema, and output schema, the description supplies all remaining operational facts needed for safe invocation: fixed recipient, real-email side effect, retry guidance, entitlement, and rate limiting. Nothing essential 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?

The single auditId parameter is already fully described in the schema as 'The completed audit to send,' and schema coverage is 100%. The description reinforces that an audit report is emailed but adds no new parameter-level semantics.

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: 'Email an audit report, with PDF attachments, to the authenticated account's own address.' It also distinguishes itself from view/export siblings by explicitly constraining the recipient to the authenticated account.

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 usage context: reports go only to the authenticated account, sending to a colleague/client is a dashboard action, and the tool requires the PDF export entitlement and is rate limited. It does not explicitly name an alternative tool, but the exclusions are 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, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds useful behavioral context: the CSV is returned as text, can be consumed programmatically, and represents one row per proposed change. This goes beyond what the annotations alone express.

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?

Two short sentences with no wasted words. The first sentence states the core operation and format; the second explains what can be done with the output and adds the PDF limitation. It does not repeat schema fields or annotation information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter, read-only export tool, the description covers everything needed to invoke it correctly: the required auditId is in the schema, the response format is stated as CSV text, and the PDF limitation is explicit. An output schema is present, so detailed return structure does not need to be duplicated here.

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 only parameter, auditId, is fully documented in the input schema with 100% coverage. The description does not add further detail about the parameter, but the schema already carries the semantic burden. This is the appropriate baseline case.

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 names the exact verb ('Export'), resource ('an audit's fix list'), and format ('as CSV'), and adds the semantic 'developer-handoff format, with one row per proposed change.' This distinguishes it from sibling listFixItems and other audit-related tools. The CSV-vs-PDF caveat further disambiguates what this tool produces.

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 clearly communicates the use case: obtain a machine-readable CSV fix list that can be read, transformed, or written to a file. It also gives an exclusion by stating that PDF export is dashboard-only. It does not explicitly name an alternative sibling tool, but the CSV-versus-PDF distinction is sufficient 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 include destructiveHint: true, but the description does not clarify what destructive action occurs (e.g., does exporting consume or delete the asset?). The description primarily describes a read-like operation (returning base64 and metadata), which may conflict with the destructive hint, though not explicitly contradictory.

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 a clear header, explanatory text, and usage examples. It is slightly repetitive in the usage section (mirroring function call), but overall efficient and front-loaded with key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (no need to describe return values), the description covers dependencies, transport-specific behavior, and usage flow. It is fully adequate for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds meaningful context for each parameter: sessionId and assetId are UUIDs from a generation step, and destinationPath is conditionally available only on local/stdio transport. This enhances understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool exports a generated image asset by session and asset ID. It uses specific verbs and resource names, and the context distinguishes it from siblings like generateImage or inspectImageSession.

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 provides explicit usage context: use after generateImage with sessionId and assetId, and mentions optional local disk saving. It lacks explicit when-not-to-use or alternatives, but the context is clear enough.

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 indicate this is read-only and idempotent, and the description adds valuable behavioral context: the organization is fixed during authorization, all tools default to it, and reconnecting is the way to change it. It also clarifies that entitlements determine feature availability, which helps an agent interpret results correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a concise statement of what the tool reports, then gives two concrete use cases. Each paragraph serves a distinct purpose and no sentence is redundant or 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 zero-parameter introspection tool with an output schema, the description covers everything an agent needs: what the tool reports, when to call it, why empty results may appear, and how entitlements affect feature recommendations. The output schema handles return-value details.

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 takes zero parameters and schema coverage is 100%, so there is nothing for the description to add about parameter meaning. The baseline of 4 is appropriate here because the description cannot meaningfully elaborate on an empty parameter list.

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 ('Report') and a clear resource: the connection's OpenGraph organization and plan entitlements. This distinguishes it from all sibling tools, which focus on audits, websites, images, or fix items.

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 when-to-use guidance: 'Call this when a result is unexpectedly empty' and 'Also use it before suggesting a feature.' It does not explicitly name alternative tools or exclusion conditions, but it clearly explains the diagnostic scenarios and how the information affects subsequent actions.

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 provide readOnlyHint, idempotentHint, and destructiveHint. Description adds synchronous nature, immediate results, that it does not count against monthly audit quota, and requires OAuth authentication. No contradictions.

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, no wasted words, front-loaded with core purpose, then usage triggers, then behavioral notes, then alternative. Perfectly structured.

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 a single parameter, good annotations, and an output schema, the description covers purpose, usage, behavioral constraints, and the return format in a summary. Completeness is high.

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 a single 'url' parameter that already has a description. The description does not add additional parameter semantics beyond what the schema provides.

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 verb 'Check' and resource 'URL', specifies the platforms (Facebook, Twitter/X, LinkedIn, Google), and distinguishes itself from sibling tool 'startSiteAudit' for full multi-page audits.

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 lists example user queries that trigger the tool ('check the link preview', 'how does this page look when shared', 'check my og tags', etc.) and provides an explicit alternative ('For a full multi-page audit... use startSiteAudit instead').

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, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context by stating that no schedule is returned for unmonitored websites and by listing exactly what the schedule read includes. 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 compact and front-loaded with the purpose, followed by a concise list of returned fields. The final sentences about unmonitored websites and IDs from listWebsites earn their place; there is no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one parameter, rich annotations, an output schema, and a description that already enumerates the returned schedule details plus the no-schedule edge case, nothing essential is missing for an agent to select and invoke 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?

The input schema already documents websiteId as 'Website ID from listWebsites', and schema description coverage is 100%. The description repeats this guidance rather than adding new parameter semantics, so the 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 description opens with a specific verb ('Read') and identifies the exact resource ('a website's recurring-audit schedule'), then enumerates the concrete data points returned. This clearly differentiates it from siblings like setMonitoringSchedule and getSiteAuditStatus.

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 provides clear usage context: it notes that website IDs come from listWebsites and explains the 'no schedule' case. However, it does not explicitly state when to prefer this tool over alternatives or mention exclusions, stopping 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: three data sources merging behavior, automatic gap-filling by hybridGraph, and hints about defaults (retry, cache_ok). Does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose, followed by a clear sibling comparison table. Every sentence adds value, and it is concise given the complexity (24 parameters).

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 complexity (24 parameters, output schema exists), the description explains the data sources, hybrid nature, and usage guidance. It could mention that the output schema provides detailed field descriptions, but overall it is complete enough.

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 is 3. The description does not elaborate on individual parameters beyond the schema, but provides overall context about data sources and output structure that helps understand parameter relevance.

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 fetches Open Graph metadata, HTML-inferred tags, and hybrid social preview data. It specifies the verb 'Fetch' and resource, and distinguishes from siblings by listing what each sibling 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?

The description explicitly provides a 'Pick the right tool' section that tells when to use getOgData versus alternatives like getOgMarkdown, getOgScrapeData, etc. It also advises using hybridGraph as the primary source.

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, etc. The description adds mode behavior, default values (e.g., html_elements default list), response shapes per mode, and proxy escalation logic. No contradictions 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 relatively long but well-structured with clear sections (modes, response shapes, special params, sibling comparison). Every sentence has purpose, though a few technical details could be tightened.

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 25 parameters and an output schema, the description covers the two primary modes, default behaviors, and important options. It lacks some edge-case clarifications but is sufficiently complete for an agent to use 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 baseline is 3. The description adds significant meaning: explains the two parameter groups (html_elements vs selectors) with examples, describes defaults, and clarifies how modes affect output. Some parameters (e.g., retry, cache_ok) get less attention, but overall adds value.

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 it extracts specific content from URLs via OpenGraph.io API v3, and lists two distinct modes with examples. It distinguishes itself from siblings by contrasting each sibling's purpose in a dedicated bullet 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?

The description explicitly explains when to use tag-based vs selector-based mode, and provides a complete sibling comparison table. It also gives guidance on when to use parameters like full_render and wait_for_selector.

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 mark this as read-only, idempotent, open-world, and non-destructive, and the description adds valuable behavior beyond that: it strips navigation/ads/boilerplate by default, caps the Markdown text block at 6,000 characters while keeping full content in the structured field, and discloses prompt-injection scanning and HTTP 422 blocking behavior. No contradiction exists between the description and 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 long, but the tool has 40 parameters and multiple behavioral nuances, so the length is justified. It is well structured with clear section headers (LONG PAGES, EXTRAS, UNTRUSTED CONTENT, Pick the right tool), front-loads the core purpose, and uses bolded parameter names for scannability without wasted sentences.

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 complex 40-parameter, 1-required-parameter tool with an output schema and rich annotations, the description covers everything an agent needs to invoke it correctly: purpose, sibling routing, chunking strategy, security handling, output cap behavior, and tuning knobs. The existence of an output schema means return-value details do not need to be repeated in the description.

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, but this description adds substantial cross-parameter meaning: it explains why query+chunking is preferred over max_chars, that include_links/include_images/include_headings avoid a second scrape call, how ai_sanitize_mode coordinates with ai_sanitize, and how include_tags/exclude_tags control page sections. This goes well beyond the individual schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: converts any URL's HTML into clean Markdown via the OpenGraph.io v3 markdown endpoint. It distinguishes itself from siblings by describing what the output contains (main-content prose, headings, links, images) and by including an explicit 'Pick the right tool' list that contrasts getOgMarkdown with getOgData, getOgScrapeData, getOgExtract, getOgScreenshot, 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?

Usage guidance is explicit and actionable: it tells agents to prefer query+chunking over max_chars for long pages, use include_tags/exclude_tags to target sections, and set ai_sanitize when feeding untrusted content to a model. The 'Pick the right tool' section directly lists when each sibling should be used instead, so an agent can route correctly without inferring.

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 `destructiveHint: false`. The description adds credit consumption details (100 or 200 credits) and a version note. No contradictions; additional behavioral context beyond annotations is minimal but adequate.

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: two sentences plus a brief note. It front-loads the core purpose and critical details (API credit usage, version status). Every sentence adds value with no 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 high schema coverage, existence of an output schema (not shown), and annotations that cover safety, the description is mostly complete. It could mention return format or pagination, but output schema likely handles that. Overall adequate for the tool's complexity.

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% (all 18 parameters have descriptions). The description adds no extra parameter meaning beyond what the schema provides, except for highlighting `responseStructure` for structured data. Baseline score of 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: 'Ask a natural-language question about the content of any URL and receive an AI-generated answer.' It distinguishes from sibling tools like `getOgData` or `getOgExtract` by focusing on natural-language queries and optional structured extraction via `responseStructure`.

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 implies usage for querying URL content with NL questions but provides no explicit guidance on when to use this tool versus alternatives (e.g., `getOgExtract` for structured data without AI). No when-not or exclusion cases are mentioned.

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?

Discloses that first 3000 chars are in text response, full HTML in structured field, explains auto_render vs full_render, and retry behavior. Annotations already declare readOnlyHint, etc., and description adds valuable context without contradiction.

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?

Well-structured with clear paragraphs, but slightly verbose. Could be trimmed slightly, but overall effective.

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 high parameter count, rich schema descriptions, and output schema, the description provides sufficient context for correct tool 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%, so baseline is 3. Description adds extra context for auto_render and full_render parameters, earning a 4.

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 scrapes raw HTML and distinguishes from siblings by listing their specific use cases.

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 provides a 'Pick the right tool' section with each sibling's purpose, giving clear when-to-use 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 convey readOnlyHint, idempotentHint, destructiveHint. The description adds context about the return format (hosted screenshotUrl), usage in browser/img tag, and proxy/retry behaviors, which are beyond what annotations provide.

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-organized: opening sentence, return format explanation, sibling comparison. It is efficient but the sibling list is somewhat lengthy; still no wasted 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?

Given the tool's complexity (24 parameters, many options), the description covers key capabilities, return value, and usage notes. It lacks only detailed output schema but mentions the hosted URL, so completeness is high.

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 adds meaningful summary of key parameter groups (full-page, viewport, dark mode, etc.) and their effects, providing extra context beyond individual schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool captures a screenshot via OpenGraph.io API v3, lists key features, and distinguishes from siblings by presenting a 'Pick the right tool' list with each sibling's 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?

Explicitly provides a 'Pick the right tool' section that details when to use this screenshot tool versus alternatives like getOgData, getOgMarkdown, etc., offering clear selection criteria.

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 read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral nuance: regression is tracked via durable issue identity, not list comparison, and the baseline advances automatically unless overridden. This goes beyond the annotations and gives the agent confidence in how results are computed.

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 paragraphs but each sentence earns its place: purpose first, then composition, then the regression nuance, then the baseline override. It is well-structured and front-loaded, though slightly longer than strictly necessary.

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 an output schema and rich annotations, the description covers the essential context: what it returns conceptually, the default/comparison behavior, and the underlying accuracy mechanism. The agent has everything needed to invoke it correctly without further investigation.

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 parameter descriptions for both auditId and baseline. The description adds extra semantic value by explaining the default baseline behavior and referencing source tools (startSiteAudit, listSiteAudits) for auditId. It clarifies usage beyond the schema, which is a bonus.

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 the exact question it answers: 'what changed on this site, and what should I fix first?' It then lists the concrete components (new/fixed/regressed issues, score delta, prioritized groups) and distinguishes itself from sibling tools like getSiteAuditReport by focusing on delta vs. a full report. This is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states it applies to completed audits and explains the optional baseline parameter to compare against a specific earlier audit. It does not explicitly name alternatives or when not to use it, but the context is clear enough that an agent can infer its place among siblings.

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 destructiveHint. Description adds the crucial constraint that audit must be COMPLETE, which is not in annotations. It also lists report contents, providing additional context beyond safety profile.

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 a decision table. It is front-loaded with the main purpose. Slightly verbose but every section adds value; could be trimmed slightly but still effective.

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 presence of output schema, annotations, and sibling tools, the description is fully complete. It enumerates report contents, specifies prerequisites, and provides clear usage guidance, leaving no ambiguity for an AI agent.

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 mentions the auditId parameter and its required status, but this is already documented in the schema. No additional parameter details beyond schema are provided.

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 verb 'Retrieve' and resource 'full structured report for a completed site audit'. It distinguishes from siblings like getSiteAuditStatus and previewPageAudit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the prerequisite (audit must be COMPLETE) and names the alternative tool getSiteAuditStatus for checking progress. The 'Pick the right tool' section clearly differentiates when to use each sibling.

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, and non-destructive behavior, so the description only needs to add operational context, which it does: return statuses, progress counters, summary scores appearing after completion, and a polling cadence. There is no contradiction with the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by precise usage instructions and a compact disambiguation list. Every sentence earns its place and no redundant phrasing is present.

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?

This tool has a single well-documented parameter, an output schema, and safety-relevant annotations. The description supplies the remaining operational details needed to use it correctly: polling interval, termination condition, status values, and the follow-up tool to call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the auditId parameter is already described as 'The audit ID returned by startSiteAudit.' The description reinforces that the ID comes from startSiteAudit, but adds no substantive new meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Poll') and resource ('status of a running site audit'), enumerates the exact status values returned, and distinguishes itself from getSiteAuditReport and startSiteAudit. An agent can immediately know what this tool does and how it differs from its siblings.

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 instructs when to call it ('repeatedly every 10–15 seconds after startSiteAudit'), when to stop ('until status is COMPLETE'), and which tool to use next ('then call getSiteAuditReport'). The 'Pick the right tool' section further clarifies the boundary between status polling and report retrieval.

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.

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

Annotations already mark it readOnlyHint=true and idempotentHint=true, and the description adds that the fix list is hand-authored and not regenerated, which is a valuable behavioral nuance beyond the annotations. It also discloses that each item's ID is returned for use with deleteFixItem, providing operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no fluff. The core action and the key caveat (hand-authored, not regenerated) are front-loaded, and the reference to deleteFixItem is appended naturally. 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?

With one required parameter, an output schema present, and annotations covering safety, the description provides all essential context: what the data is, how it is created, and how the returned IDs are used. Nothing critical is missing 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?

The only parameter auditId is documented in the schema with a brief description ('Audit ID.'). The tool description only implies it is the audit identifier, adding no new meaning beyond the schema. With 100% schema coverage, a baseline of 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 it 'reads the fix list saved against an audit' — a specific verb and resource. It distinguishes itself from the sibling deleteFixItem by noting it returns each item's ID for that tool, and clarifies that the list is hand-authored and not regenerated, setting it apart from audit-result 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 implies usage for viewing proposed metadata changes and notes, and contrasts with regenerated audit data ('not regenerated by re-running an audit'). It references deleteFixItem as the deletion counterpart, but does not explicitly name other alternative tools for audit outputs, so guidance is implicit rather than explicit.

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 read-only, idempotent, and non-destructive. The description adds behavior not in annotations: newest-first default, filtering/paging semantics, and that it returns audit IDs for downstream tools. No contradictions.

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 compact paragraphs, each purposeful: purpose and use cases, filtering/paging, and return value/next steps. No filler; front-loads the most important fact.

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 no required params, rich annotations, and an output schema, the description covers what the tool returns, how to filter/page, and how to continue to getSiteAuditReport/getSiteAuditChanges. Nothing essential is missing for an agent to select and invoke 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 all 8 params at 100%, so baseline is 3, but the description adds use-case semantics: websiteId builds a single site's history, from/to are ISO dates, and limit/offset page. It does not explain sort, but the default sort is stated.

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 ('List past site audits') plus scoping ('for the connected organization') and default ordering. It also names downstream tools, distinguishing it from getSiteAuditReport/getSiteAuditChanges and from mutation siblings.

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 tells when to use it: to find an audit to inspect, track scores over time, or get previous audit ID for comparison. It does not spell out exclusions versus startSiteAudit/deleteSiteAudit, but the purpose and filter guidance make context 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, idempotentHint=true, and destructiveHint=false, and the description adds meaningful behavior: it lists the returned health dimensions, explains the websiteId overload, and clarifies the durable-object relationship across repeated audits. This goes beyond what annotations alone convey without contradicting 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 description is front-loaded with the core listing purpose, then the websiteId detail, then the sibling-tool relationship. Every sentence earns its place and the structure makes important scoping information immediately visible.

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 7 parameters, an output schema, and safety annotations already present, the description covers the essential semantics: what is returned, how the websiteId overload behaves, and how the tool relates to nearby sibling tools. Nothing critical is missing 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 71%, and most parameters already have descriptive entries. The description reinforces websiteId's special behavior but does not add meaning for q, sort, limit, health, offset, or monitoring beyond what the schema provides, so the 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?

States the specific operation ('List the websites this organization has audited') and details the output fields, making the resource and scope unambiguous. It also distinguishes itself from listSiteAudits by defining a website as the durable object behind repeated audits and referencing sibling tools that operate on its ID.

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 concrete usage context: passing websiteId returns a single website in detail instead of the list, and it explicitly names getMonitoringSchedule and listSiteAudits as the tools to use with that ID. It does not explicitly state when listWebsites should not be used, but the routing guidance is strong enough for an agent to choose correctly.

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, idempotentHint, and destructiveHint. The description adds that the check is synchronous, returns immediately, does not persist an audit, and does not count against quota, complementing annotations perfectly.

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, well-structured: first sentence states core action and output, then clarifies synchronous/non-persisting nature, then lists score labels, then provides tool comparison. No superfluous sentences.

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 has an output schema, the description sufficiently explains the return values (score, label, breakdown, issues, mock previews) and score ranges. It covers all necessary context for an agent to use this tool effectively without needing to inspect the output schema.

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% for the single 'url' parameter, with description 'The full URL of the page to audit (e.g. https://example.com/product).' The tool description repeats the example but adds no new semantic value beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it runs an instant quality audit of a single URL and lists the returned data (score, label, breakdown, issues, mock previews). It clearly differentiates from sibling tools like startSiteAudit which is async and crawls an entire domain.

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 directly provides a 'Pick the right tool' section comparing previewPageAudit (instant, no quota) with startSiteAudit (async, uses quota), giving explicit guidance on when to use each.

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 annotations, the description discloses that this overwrites existing items for the same page/field, that the fix list is hand-authored and non-reproducible, and that blank/unchanged values are treated as removals upstream. However, there is an internal inconsistency: it says a note may leave proposedValue blank, but later says a blank value is rejected here, which slightly clouds the 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?

The description is well-structured: purpose first, overwrite warning second, validation and alternative tooling last. Every sentence carries operational weight, and the critical caveats are front-loaded.

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 destructive, non-reproducible write operation, the description covers read-before-write behavior, user confirmation, validation rules, and the correct deletion alternative. The only notable gap is the unresolved contradiction about whether a note with a blank proposedValue is actually accepted.

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 auditId, pageUrl, items, and proposedValue semantics. The description adds the upstream-removal context and validation rationale, but it largely restates the schema and introduces the blank-note ambiguity, so it does not unambiguously improve parameter understanding.

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: 'Record proposed metadata changes for one page of an audit — the developer handoff list.' It clearly identifies the write operation and the narrow scope, and it differentiates the tool from its siblings by mentioning listFixItems and deleteFixItem.

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 tells the agent to read with listFixItems first and confirm with the user before replacing entries, and it directs deliberate removals to deleteFixItem. This is exactly the when-to-use / when-not-to-use guidance needed for a destructive hand-authored 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?

Beyond the annotations (destructiveHint, readOnlyHint, etc.), the description discloses critical behavior: ongoing spend, indefinite quota consumption, alert emails, permanent deletion of schedule configuration when disabled, partial-update carryover semantics, and failure without the entitlement. These are exactly the hidden behavioral traits an agent needs.

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?

Although longer than average, every sentence carries operational weight. High-risk information is front-loaded with 'THIS COMMITS ONGOING SPEND,' and the pause-vs-disable distinction is clearly separated from the general behavior. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 13-parameter tool, the description covers cost implications, destructive semantics, partial-update behavior, entitlement requirements, and parameter relationships. Since an output schema exists, missing return-value details are acceptable. Nothing essential is left unexplained.

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 parameters are already well described. The description adds valuable cross-parameter context: frequency is required when enabling, unpassed settings are carried over, and includeNewPages increases quota use over time. This goes beyond the schema and helps correct parameter decisions.

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 names the exact resource and verbs: turn recurring audits on, change their settings, or turn them off for a website. It clearly differentiates this from related tools like getMonitoringSchedule (reading) and startSiteAudit (manual runs) by emphasizing recurring schedule configuration.

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 when-to-use and when-not-to-use guidance: use `paused: true` to keep configuration, use `enabled: false` to permanently stop and delete, and know that alert recipients are managed in the dashboard, not here. It also calls out the entitlement prerequisite and the need to confirm with the user before enabling or changing a schedule.

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?

Discloses that audits are asynchronous and can take several minutes, returns an audit ID, and instructs to use getSiteAuditStatus for polling. Also explains behavior when `urls` is omitted (backend crawls). No contradiction with annotations (readOnlyHint=false, etc.).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with core purpose, then parameter guidance, then async behavior and tool selection. It is somewhat lengthy but every sentence adds value. Minor redundancy in repeating 'audit all' explanation could be trimmed.

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 complexity (asynchronous, multiple URL sources, polling), and full schema coverage plus output schema existence, the description is complete. It covers all aspects needed for correct tool invocation and result handling.

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?

Although schema coverage is 100%, the description adds significant context: for `urls`, explains sourcing methods; for `domain`, includes protocol requirement; for `pagesRequested`, explains default and plan limits; for `siteContextText`, explains its role in enriching the overview. This goes well beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('start a full site audit') and what it audits (Open Graph, social media, SEO metadata). It distinguishes from sibling tools by listing alternatives and their purposes, such as discoverSiteUrls for crawl-based discovery and getSiteAuditStatus for polling.

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 guidance on when to use this tool vs. siblings, including a dedicated section 'Pick the right tool'. Explains how the `urls` array can be sourced from discoverSiteUrls, codebase scan, sitemap, or manual list, and that calling discoverSiteUrls first is not required.

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