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

Goes well beyond the annotations: the backend rejects duplicate element ids, sections are validated first, dry_run defaults to true and caches under a draft_id, validation failures still return a draft_id, font weights needing new links surface in font_weights_notice, and Webcake credentials are required. This is exactly the operational context an agent needs for a mutating tool.

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

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

Front-loads the append operation and the dry_run default before secondary details, and every sentence carries information. It is dense and slightly long, but no sentence is wasted.

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

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

No output schema exists, and the description covers the key return signals (draft_id on validation failure, font_weights_notice) plus credential requirements. It does not fully describe the shape of the dry_run preview response, a minor gap for a server-side mutation.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds cross-cutting meaning: dry_run's default and dual behavior, draft_id's cache-loading purpose, its acceptance by patch_page, and the sparse-node filling from factory defaults. It largely echoes the schema for the core fields, keeping it out of the top band.

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 — appending section nodes to an existing page's `page` array — and clarifies it is server-side with only new sections sent. It also names patch_page as the sibling for element-level fixes, so an agent can distinguish it from other write tools 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?

Explains when the tool applies (appending to an existing page) and routes element-level fixes to patch_page, plus documents the dry_run-first workflow. It stops short of an explicit when-not-to-use statement versus siblings like create_page or update_page.

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?

Goes well beyond the annotations: discloses the automatic deterministic layout corrections and auto_fixed list, CDN re-hosting of external images/fonts, dry_run default true and caching under draft_id, that a failed publish does not fail the create and result.publish reports outcome, the 10-minute preview link lifetime, and credential/organization resolution order. Annotations only cover readOnly/destructive/openWorld, so this adds substantial 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?

Front-loaded with the core action, but the single long block buries several operationally critical facts (dry_run default, draft_id semantics, organization resolution) in a dense paragraph rather than structuring them. Most sentences earn their place, but the wall of text and lack of paragraphing hurt scanability.

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 6-param, zero-required, no-output-schema creation tool, the description covers the full operation: validation, layout fixes, save, publish behavior and failure mode, dry-run contract, draft reuse, organization resolution, and credential requirement. An agent has everything needed to invoke it correctly without opening the 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 already 100%, so baseline is 3; the description adds real semantics over the schema for several params (dry_run default and caching behavior, publish consequence, draft_id retry coverage, organization_id resolution chain with the 'personal' sentinel). It doesn't add format/syntax detail for the sparse 'source' schema beyond what's documented, keeping it from 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?

States a specific verb+resource ('Creates a new page in the user's Webcake account') and delineates the full lifecycle: validation, layout correction, save, publish. Distinguishable from siblings like new_page_skeleton (no save/publish) and update_page (modification not creation), though it never explicitly names them.

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?

Clear usage context is embedded: dry_run defaults to true for validation, draft_id covers the retry/fix/after-timeout steps, publish:false gives source-only. The 'covers the dry-run → real call step, fixes after errors, and retries after a timeout' line is explicit routing guidance. No explicit exclusions vs siblings, so not 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 only declare readOnlyHint and openWorldHint, so the description carries the extra load and does so well: it discloses AND-combination semantics, case-insensitive substring matching, the custom_domain-or-default_domain matching rule, the no-filter default ordering, the credential requirement, and the result field set. That is rich behavioral context beyond the annotations.

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

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

Three dense sentences with no filler. The search scope is front-loaded, followed by matching semantics, default behavior, result fields, and prerequisites in a logical order.

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

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

There is no output schema, but the description compensates by listing the returned fields (id, name, organization_id, custom_domain, default_domain, updated_at). Combined with the auth requirement and matching semantics, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the per-parameter details already exist and baseline is 3. The description goes a step further by explaining the interaction between parameters (AND-combined) and clarifying that domain matches either custom_domain or default_domain — relationship semantics the schema cannot express on its own.

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 ('Searches the account's pages') and enumerates what can be searched on (name, domain, page id), which clearly separates it from get_page or list_elements. It stops short of explicitly naming a sibling such as list_pages or get_page, so the differentiation is inferable 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?

Gives concrete call conditions: filters are AND-combined, and with no filters it returns the most recently updated pages. It also hints page_id is useful to confirm a page exists/is owned. No explicit exclusions or named alternatives are offered, but the context needed to pick this tool is present.

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 annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description goes further by disclosing the return contract — a summary, key `specials` fields, a sparse skeleton node whose boilerplate the server fills, and a filled example for common types. With no output schema, that disclosed behavior is valuable, though some terms (`specials`, "skeleton node") stay undefined.

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 is front-loaded in the opening clause and the remaining clauses each carry distinct information (what is returned, and the two return shapes). It is a single dense sentence with domain jargon but no filler or repetition, so nothing is wasted even if it reads densely.

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 no output schema and no required parameters, the description carries the load of describing return values, and it does so for both call shapes. Remaining gaps are minor — the meaning of `specials`, error behavior, and how the skeleton is intended to be reused are not clarified.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it states that `types` returns { elements: { [type]: details } } while `type` returns a single doc, which is not expressed anywhere in the input schema. It also clarifies the mutual purpose of the two params (one type vs several in one call).

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 ("Returns usage details for one element type") and even enumerates what those details contain (summary, specials, skeleton, example). It implicitly separates itself from list_elements by being a per-type detail lookup, but never names that sibling or any other, so differentiation is left to inference 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?

It clearly explains when to use the `types` array versus the single `type` string (several types in one call vs one type), which is genuine usage guidance. However, it offers no guidance on when to reach for this tool at all compared to siblings like list_elements or get_page_schema, so a tool-selection context is only implied.

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

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

Annotations already declare readOnlyHint=true, so the description adds little behavioral context beyond the content list. It doesn't disclose any side effects or permissions, but the read-only nature is clear.

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 a single, well-structured sentence that front-loads the purpose and lists the specific topics. No wasted words.

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

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

For a zero-parameter reference tool with no output schema, the description adequately covers what the tool provides. It lists the key conventions, making it complete for its purpose.

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

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

The tool has zero parameters and 100% schema description coverage. The description does not need to add parameter information. Baseline 4 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 what the tool returns: 'page-building conventions reference' with detailed contents (output shape, coordinate system, event vocabulary, workflow). This clearly distinguishes it from sibling tools like get_page_schema or list_pages.

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 the tool should be used when conventions are needed but does not explicitly state when or when not to use it. No alternatives or exclusions 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?

Annotations already declare readOnlyHint and openWorldHint, but the description adds substantial extra context: it is a public API needing no credentials, it normalizes underscores to hyphens, it resolves Material Symbols to the outlined variant with a filled fallback, and it fully describes how the SVG must be plumbed into Webcake (svgMask per breakpoint, color from styles.background, preserveAspectRatio='none'). That is real behavioral disclosure beyond the structured hints.

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

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

Front-loaded with the core action and API reference, then progressive detail on formats, resolution rules, return shape, and Webcake rendering. Every clause carries information, though the Webcake rendering passage is dense enough that the paragraph runs long.

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 tool with no output schema, the description compensates by documenting the return shape ({ icons: { '<ref>': { ok, svg, iconify } } }) and the downstream rendering contract. An agent has everything needed to call it and consume the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by defining the transformation semantics of each ref string — prefix handling, underscore-to-hyphen conversion, and bare-name treatment as Material Symbols. It adds meaning the schema example alone does not convey.

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 (resolves) and resource (icon-font names into inline SVG markup) and names the concrete backing service (public Iconify API). It is unmistakable against siblings like search_images or render_preview because it operates on icon refs, not images or pages.

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?

Explains the accepted ref formats ('ms:verified', 'fa:chart-line', 'mdi:home', bare names) and ties them to where the agent will encounter them (block.icon values from an ingest result), which is clear contextual guidance. It stops short of explicitly stating when-not to use it or naming a fallback alternative, so it lands just under full marks.

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 openWorldHint=true, and the description goes well beyond them: it discloses the default compaction behavior, exactly what boilerplate is stripped, how to opt out (compact:false), and that Webcake credentials are required. It stops short of describing failure behavior for missing pages or size limits, but the added context is substantial for a read tool.

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

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

Front-loads the verb and resource, then the return shape, then the compaction default, then the auth prerequisite. Three dense sentences with no filler; the compaction clause is slightly long but each clause carries distinct 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?

There is no output schema, so the description must carry the return shape — and it does, naming the tree sections plus name, organization_id, and source_version, and explaining the default sparse form. Combined with annotations covering the read-only safety profile, an agent has enough to call this correctly; only edge-case/error behavior is unaddressed.

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, and the description earns more by explaining the semantic purpose of compact:true — the output is not just smaller but is the re-hydratable shape accepted by the save tools, which the schema text does not convey. page_id is left to the schema, which 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 a specific verb and resource ('Fetches an existing page's source tree') and enumerates the top-level sections returned (page, popup, settings, options, cartConfigs). This is clearly distinguishable from siblings like get_page_schema, list_pages, and get_element 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?

Usage context is only implied: the note that the compacted tree matches 'the same sparse shape the save tools accept and re-hydrate' hints this is the read half of an edit round-trip. It never names an alternative tool or states when to prefer list_pages/find_pages/get_page_schema instead, so no explicit routing guidance is given.

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, so the description's statement of returning full JSON Schema aligns and adds detail (Draft 2020-12, structure). No hidden behaviors or 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?

Single sentence, front-loaded with verb and object, no wasted words. Perfectly concise for the tool's simplicity.

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

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

For a zero-parameter read-only tool, the description fully covers what it does and what it returns. No output schema exists but the description specifies the return structure sufficiently.

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?

No parameters (schema coverage 100% with empty schema). Baseline is 4 as per rule. Description adds no param info because none are needed.

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 'Returns' and resource 'full JSON Schema of a Webcake page source object' with clear purpose 'for structural reference and validation'. It distinguishes from siblings like validate_page or get_page by stating it returns the schema itself.

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 clearly implies when to use (when needing schema for reference/validation) but does not explicitly mention when not to use or name alternatives. However, the context of sibling tools and the tool's name make the use case 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 only cover readOnlyHint and openWorldHint; the description goes far beyond them, disclosing the size caps (2–5 KB vs 25 KB), deterministic canvas conversion, clone_notes/canvas_summary, automatic image re-hosting on save, garbled-Vietnamese repair with a warning, and the explicit 'No credentials, no writes' safety statement.

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

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

The purpose is front-loaded, but the body is a single dense ~300-word block that re-explains much of what the parameter descriptions already state. For a genuinely complex tool some of this earns its place, yet the redundancy and lack of paragraph structure work against readability.

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 no output schema, the description carries the full burden of describing the return shape, and it does so thoroughly: sections, headings, CTAs, form fields, size_hint, typography, font_groups, palette, design_tokens, and the canvas 'source'/clone_notes payloads. An agent can anticipate the result at both detail levels.

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 largely restates the schema's detail/intent/sections semantics rather than adding meaning, with the one genuinely additive nuance—that base_url triggers remote stylesheet fetching—already being covered in the schema. It compensates for nothing and adds little beyond structured data.

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 clause gives a precise verb+resource ('Parses an HTML string into a reference AST for rebuilding the page in Webcake') and enumerates the extracted outputs (sections by role, colors, fonts, design tokens, canvas conversion). However, it never names its obvious sibling ingest_url, so the agent must infer the boundary (raw HTML here vs URL fetching there) rather than being told.

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 well framed through the parameter semantics: when to choose detail:'compact' vs 'full', intent:'adapt' vs 'clone', and when to supply base_url. It does not state explicit exclusions or point to alternatives such as ingest_url, so the 'when not to use this' guidance is absent.

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?

Well beyond the readOnlyHint/openWorldHint annotations, it discloses timeout, size cap, JS non-execution, the empty-body warning, SSRF-style private/link-local blocking, and 'no credentials, no writes.' It also explains the deterministic absolute-canvas conversion path and clone_notes/canvas_summary 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?

Front-loaded with the core action and densely informative with little filler, but the single long paragraph (with em-dashes and asides) is heavy, and the detail-level semantics echoed in the schema description create mild 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 no output schema, the description carries the full burden and does so: it enumerates the returned AST fields, the compact/full distinction, canvas_summary/source handling, and failure modes. An agent has everything needed to call and interpret the tool.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics: what detail:'full' yields, what intent changes, and that absolute-canvas exports return a clone source either way. Much of the detail/intent prose duplicates the schema, capping it above baseline rather than at the top.

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 ('Fetches a public webpage') and immediately scopes it (GET, 10 s timeout, 2 MB cap, external stylesheets and @imports). It distinguishes itself from the sibling ingest_html by defining the shared output ('the same reference AST as ingest_html') and its distinct input (a URL).

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

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

Provides strong contextual usage signals: JavaScript is not executed so client-rendered sites may return little content, fetches are limited to public hosts, and the intent/detail params set expectations. It does not, however, explicitly frame ingest_html as the alternative to pick when the agent already has HTML in hand; the routing is left implicit.

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 only declare readOnlyHint and openWorldHint=false; the description adds real behavior beyond that: order of returns ('one box per item in input order'), edge-case handling ('notes for off-canvas or over-wide inputs'), and the no-credentials/no-network guarantee. It stops short of describing error conditions or units explicitly, so not 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?

Front-loaded with purpose, then modes, then margin constraints, then return shape and the pure-computation guarantee. Five dense sentences with no filler, though the mode list partially restates the schema's enum descriptions, keeping it just under a 5.

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 16 params, one required, no output schema, and only readOnly annotations, the description carries the return-format burden and does so ('one box per item in input order, plus notes'). It covers defaults context and edge cases; units are only implied by '(px)' comments in the schema, which is a minor remaining 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?

Schema coverage is 100%, so the baseline is 3 and the schema already documents all 16 params including defaults. The description still adds a derived fact not in the schema: the effective content column (80–880 desktop, 20–400 mobile) produced by the margin defaults, plus mode-specific mobile stacking behavior that guides which params matter.

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?

Specific verb + resource: 'Computes on-canvas coordinates (top/left/width/height) for a group of elements on both breakpoints.' The final clause ('Pure computation: no credentials, no network.') cleanly separates it from every sibling CRUD/render tool. An agent knows exactly what this returns without opening the schema.

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

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

The description explains what each mode does and that it respects page margins, which implies the intended scenario (getting positions before placing elements). However it never states when to reach for this tool in a workflow (e.g. before add_section/new_element) and names no alternative or exclusion. Usage is inferable but not prescribed.

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 description adds detail about output format (grouped by category, summary, container info). No contradictions; it enhances transparency.

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?

Single sentence with no wasted words, front-loaded with action and resource, structured with logical groupings of output 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?

Given no parameters and annotations, the description fully covers what the tool does and returns. No output schema, but description explains output content adequately.

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?

No parameters exist, and schema coverage is 100% (empty). Description does not need to add parameter information; baseline for 0 params is 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 verb 'list', the resource 'supported element types', and specifies grouping by category, one-line summary, and container flag. It distinguishes from sibling tools like 'get_element' (singular) and 'new_element' (creation).

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 browsing all element types but does not explicitly state when to use or not use this tool versus alternatives. Context from sibling tools suggests it's for overall listing.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the bar is lower. The description adds value by specifying output fields and the default org concept, plus authentication requirements (WEBCAKE_API_BASE + WEBCAKE_JWT). 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?

Two sentences deliver purpose, output fields, a usage hint, and authentication prerequisites. No wasted words; front-loaded with action.

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

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

For a parameterless list tool with annotations, the description fully covers what is returned, the significance of the default org, and environment requirements. No gaps given the tool's simplicity.

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?

Input schema has zero parameters and 100% coverage. Per guidelines, baseline is 4. The description does not add parameter detail, but none is needed.

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 'Returns the account's Webcake organizations' with specific fields (id, name, is_default). It adds context about the default org, distinguishing it from other organization-related calls. No sibling tool duplicates this purpose.

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

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

The description explains when to use this tool (to get organizations, especially the default org for page routing) but does not explicitly exclude alternatives or compare to siblings. The context is clear, but lacking exclusions prevents 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=true and openWorldHint=true, so the description adds value by specifying the ordering (most-recent first) and the exact fields returned. 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 two sentences, front-loaded with the core purpose, and every word contributes. No extra 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 covers purpose, fields, and ordering, but lacks information on pagination, limits, or whether the list is complete. Given no output schema, missing pagination details reduces completeness for a list operation.

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

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

The tool has no parameters, and schema coverage is 100% (no properties). The description does not need to add parameter meaning beyond what the schema provides; baseline for 0 parameters is 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 lists pages owned by the account, specifies returned fields (id, name, organization_id, updated_at), and indicates ordering (most-recent first). However, it does not differentiate from sibling tools like find_pages, which may filter.

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 only usage guidance is authentication requirements (WEBCAKE_API_BASE and WEBCAKE_JWT). No context on when to use this tool versus alternatives like find_pages or get_page, and no exclusions or prerequisites 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?

Annotations (readOnlyHint=true, openWorldHint=false) already establish that nothing is persisted, and the description adds substantial non-obvious context beyond that: exactly what is seeded (fresh id, styles for both breakpoints, specials) and exactly what is deliberately omitted (properties, runtime, empty events, per-breakpoint config) because the server fills them from factory defaults on validate and save. This tells the agent not to hand-populate those fields.

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 tight sentences with the primary behavior front-loaded and the omission rationale following. No filler, though terms like 'specials' and 'per-breakpoint config' are project jargon that go unexplained.

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 no output schema, the description carries the return-shape burden and does so well, enumerating what the node will and will not contain. What is missing is the downstream step — which sibling consumes this node (e.g. add_section/validate_page) — leaving the workflow slightly open.

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 both parameters (type, name) are already documented in the schema, including the name-override semantics. The description only restates that a type is required and adds no format, enum, or naming-convention detail beyond the schema, so 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?

States a specific verb and resource — it *returns* a default element node for a given type, in a named 'sparse authoring shape'. The word 'Returns' implicitly separates it from retrieval tools like get_element and from the persisted new_page_skeleton, but no sibling is named explicitly, so the differentiation is left to inference.

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?

There is no explicit when-to-use statement or conditional routing to alternatives. Usage is only implied by the mention of the 'sparse authoring shape' and the fact that the server fills gaps on validate/save, from which an agent can infer this is a pre-authoring scaffolding step rather than a read of existing data.

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 openWorldHint=false, so the safety profile is covered and the description's 'Returns' is consistent with it. Beyond that, it discloses the exact returned shape and the non-obvious behavioral fact that width_section is the canvas width all element coordinates are measured in — real context an agent needs before placing elements.

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 dense sentences with no filler, and the most important fact (what is returned) is front-loaded. The return-shape enumeration is compact rather than sprawling, though it slightly crowds the more decision-relevant width/coordinate sentence.

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

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

There is no output schema, and the description compensates by naming the returned keys (page, popup, settings, options, cartConfigs). Combined with the read-only annotations and the coordinate-system explanation, an agent has everything needed to call this correctly and interpret the result.

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, and the description earns above that by linking desktopWidth/mobileWidth to settings.width_section and explaining the consequence: this width is the coordinate basis for every element. It omits mobileOnly, but that parameter is already documented in the schema.

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

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

States a specific verb and resource: returns an empty, complete top-level page source in the Webcake editor's shape, with the exact top-level keys enumerated. This clearly separates it from read-oriented siblings like get_page, though it never names create_page or explains which sibling to prefer for bootstrapping a real page.

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 only implied: the phrase 'empty, complete top-level page source' suggests scaffolding a new page before adding elements, but there is no explicit when-to-use statement, no prerequisites, and no named alternative (e.g. create_page). An agent can infer intent but receives no 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?

Beyond the destructiveHint/readOnlyHint annotations, it discloses that validation errors block the save, that dry_run defaults to true so no write occurs unless dry_run:false, that force discards concurrent changes, and that credentials are required even on a dry read. These are exactly the behavioral facts an agent needs for a destructive mutation.

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 is front-loaded and the prose is information-dense, but the op grammar is restated almost verbatim in both the description and the patches schema, and the long final sentence packs save-routing rules tightly. Mostly earning its place with some duplication.

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, credential-gated mutation with no output schema, it covers the full lifecycle: source loading, merge, whole-tree validation, save routing per draft type, dry-run preview, retry path, and force. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the schema baseline is 3, but the description adds real meaning: the op grammar (update/replace/remove/add), that update cannot delete keys, that merge cannot fix additionalProperties errors, and that an empty patches with draft_id commits as-is. Most of this is nonetheless echoed in the schema, so it lands just above baseline.

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 and a distinguishing constraint ('Edits a page by element id without sending the whole source'), immediately separating it from update_page/create_page/add_section. The draft_id/page_id duality is framed clearly so an agent knows what resource it targets.

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 routes the agent well: draft_id originates from failed/dry-run create_page, add_section or update_page calls, and empty patches with draft_id is explicitly the retry path after a timeout. It does not, however, give an explicit when-not-to-use rule versus update_page for a fresh edit, leaving the choice partly inferred.

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 only declare destructive/openWorld; the description adds substantial context they cannot carry: the build-host fallback to a source-only publish that 'serves nothing' and returns a warning, the ~10-minute rendering window on preview links, domain reuse semantics on republish, and the credential requirement. It is consistent with destructiveHint=true (it overwrites the live published record) and never contradicts 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-loaded with the action and its two effects before diving into fallbacks and domain behavior, and every sentence carries real information. It is one dense, deeply nested paragraph rather than cleanly segmented, which costs it the top mark.

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 mutating tool with no output schema, the description covers the full lifecycle: what is built, what record is written, what URL is served under each domain case, what happens with no build host or a failed build, and what dry_run returns. Nothing an agent needs to invoke 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 restates the custom_domain omit-vs-'' distinction and the dry_run default that the schema already documents, adding little parameter meaning beyond the structured fields.

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+resource ('Publishes an existing page') and immediately distinguishes it from sibling mutations like update_page/create_page by naming the two concrete effects: building the rendered app on the build host and creating/updating the published record that public serving reads. An agent knows exactly what this does without opening the schema.

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

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

Gives clear operational context: dry_run defaults to true so an agent knows calling it blind does nothing destructive, and it explains the domain-resolution conditions (custom_domain provided / omitted / empty). It stops short of naming alternatives (e.g. render_preview or update_page) or stating when not to publish, so not 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?

Far exceeds the annotations: discloses the ~50 requests/day per-IP rate limit, the HTTP 429 / ok:false failure shape, that tiles requires a self-hosted Playwright host and otherwise degrades to one image, that MICROLINK_API_KEY raises quota, and that published previews expire ~10 minutes after the last publish. This is exactly the behavioral context annotations cannot carry.

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?

A single dense paragraph, front-loaded with the core action and output before engine/rate-limit details. Almost every clause is actionable, though the Microlink doc URL and dual env-var naming add marginal bulk.

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

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

There is no output schema, so the description must cover return behavior — and it does: PNG image, multiple band images under tiles, or ok:false on rate limiting. Combined with the expiry caveat and host requirements, an agent has everything needed to call it and interpret results.

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 already 100% for all five params, so the schema carries the parameter burden. The description largely restates the same facts (url precedence, tiles fallback, width semantics) rather than adding new syntax or constraints; the baseline of 3 fits.

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 concrete verb+resource+output: renders a public URL to a PNG screenshot and returns it as an image. It further specifies two targeting modes (page_id vs url) and precedence, which cleanly separates it from every sibling tool (none of which are screenshot 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?

Explains the two input modes and their precedence ('url takes precedence'), the tiles vs single-image choice and its host prerequisite, and full_page defaults. It stops short of explicit when-not-to-use guidance, but the operational context is clear enough for correct selection.

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 only declare readOnlyHint and openWorldHint. The description adds crucial behavioral context: the default shared proxy works without configuration, and a PEXELS_API_KEY or x-pexels-key header uses a personal quota. It also details the response structure (hotlinkable URLs, sizes map, avg_color, size_guide), which is essential without an output schema.

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 purpose and remains information-dense with no filler sentences. It is a single long paragraph rather than a bulleted list, which slightly hurts scanability, but every sentence contributes relevant detail.

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 no output schema, the description fully covers the return shape (photo fields, `sizes` map, `avg_color`, attribution, `size_guide`, and the parallel-search response envelope). It also addresses authentication modes. An agent has everything needed to call and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful detail beyond schema descriptions: the interaction between `pick` and `queries` (best limits to top photo, all returns full list), the parallel behavior of `queries`, and the practical size_guide mapping to slot widths.

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 ('Searches') and resource ('Pexels stock photos') and distinguishes the operation from all siblings, which cover different resources like icons, pages, and uploads. An agent can immediately tell this is the stock-photo search tool.

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?

Explains when to use `queries` (multiple slots in parallel), `query` (single search), and `pick:'best'` vs `pick:'all'`, giving clear operational context. It does not explicitly exclude or compare against sibling tools, but no true alternative for stock photo search exists among them.

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 destructiveHint=true, but the description goes well beyond them: it discloses the validate-first step, the exact refusal codes (page_changed_externally, unverified_overwrite), the force:true override, the dry_run default and draft caching, and the Webcake credential requirement. An agent knows what gets destroyed (outside edits on force) and what failure modes to expect.

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 behavior, then layers validation, concurrency, dry-run, draft reuse, and credentials — every sentence carries distinct information with no filler. It is dense and would read better with minor structure, but nothing is redundant.

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 no output schema, the description still explains what a dry run returns (a masked request + draft_id) and the reuse path, plus failure behavior and auth requirements. For a destructive 6-parameter mutation tool, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the per-parameter docs already carry the load. The description still adds integration value by wiring the parameters into a workflow — how base_version/force interact in the concurrency check, and that draft_id lets a retry re-run from cached source without resending JSON — rather than merely restating individual fields.

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 and scope: 'Replaces an existing page's stored source with an edited tree (source only; the published build is not refreshed).' The parenthetical implicitly separates it from publish_page and patch_page by nailing down that only the stored source changes, which lets an agent route correctly without opening schemas.

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

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

Gives strong when-to-use context: validate-first flow, dry_run defaulting to true, draft_id reuse after a dry run or timeout, and when the server refuses the save. It never names a sibling alternative (e.g. patch_page vs update_page, or publish_page for the live build) explicitly, so it falls just short of a 5.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses limits (20 entries, 200 MB each, parallel processing), transport-dependent behavior (stdio vs HTTP for local paths), the collection:true/false outcome depending on credentials, the exact failure shape (ok:false, reason:'organization_required'), and dry_run semantics. It also complements destructiveHint=false by stating the operation changes no page data.

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

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

The purpose is front-loaded, but the remainder is one dense run-on block with stacked em-dash clauses that is hard to parse. Most content is genuinely useful, yet the packaging over-packs detail (org resolution is repeated from the schema) and could be broken into tighter 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?

With no output schema, the description carries the burden and does so well: it explains the return value (entry→hosted-URL map), failure outcomes, credential/collection effects, and transport constraints. An agent has everything needed to call this complex tool correctly.

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

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

Schema description coverage is 100% and the parameter descriptions are already thorough (including the org-resolution chain and dry_run behavior), so the description largely mirrors existing schema semantics. It adds the framing of in_folder as the editor's media-picker library, but nothing materially new. Baseline 3 applies when the schema does the heavy lifting.

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 (re-hosts), a specific resource (images on Webcake's CDN at statics.pancake.vn), and the return shape (a map from original entry to hosted URL). This clearly distinguishes it from the closest sibling, search_images, without the agent needing to open either 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 description gives clear operational context: it documents the credential/org-resolution path (organization_id → WEBCAKE_ORG_ID → auto-select), states dry_run defaults to false because the tool only adds to the media library, and notes local paths are rejected on the remote HTTP transport. It provides no explicit routing against sibling tools (e.g., when to prefer search_images), so it stops short of a 5.

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

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

With readOnlyHint/openWorldHint already covering the safety profile, the description still adds real behavioral content: the deterministic auto-corrections applied before validation, the auto_fixed channel, and a meaningful errors-vs-warnings distinction (blocking vs. visible defects). There is mild tension between 'applies deterministic layout corrections' and readOnlyHint=true, but since it explicitly reports them in auto_fixed rather than persisting, this reads as a pure computation rather than a genuine 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?

Front-loaded with the core action, then two dense but information-bearing sentences. The rule enumerations are long, but each clause corresponds to a distinct class of check the agent may need to reason about, so little is wasted.

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

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

No output schema exists, so the description correctly carries the return contract (errors, warnings, auto_fixed) and explains what each channel means. It is nearly complete for a single-parameter validator, with the only gap being guidance on when in a workflow to invoke it and whether the corrected page must be re-saved.

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?

One parameter at 100% schema description coverage, so the schema already documents that 'page' accepts either the source object or a JSON string of it. The description adds no format, size, or encoding guidance beyond that, which is the expected baseline when the schema does the heavy lifting.

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 ('Validates a page source') and then enumerates the exact rule families checked (unique ids, dangling event targets, container-only children, form-data bindings). No sibling tool performs validation, so an agent can distinguish this immediately from layout, render_preview, or create_page.

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 only implied: 'errors (structural problems that block saving)' hints that this is a pre-save gate, but the description never explicitly says when to call it versus alternatives such as render_preview, layout, or patch_page. No prerequisites, ordering, or exclusions are stated.

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