Sitelas

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

Annotations already declare non-readOnly, idempotent, non-destructive, closed-world, but the description adds substantive behavior beyond them: writes land in the DRAFT version and only go public on publish, idempotent retry semantics with the already_existed:true return, and ConflictError on slug reuse with different content. It also discloses validation leniency (required fields enforced, extra fields allowed, missing template fields render as empty strings) and the visibility default of public.

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 routing sentence and the add_page exclusion before any detail, which is the right order. It is long (~350 words) and the image paragraph is discursive, but each section — routing, images, validation, slug behavior, prerequisite — carries non-redundant information, 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?

For a mutation tool with no output schema and thin schema coverage, this is near-complete: it covers the draft/publish lifecycle, validation contract, error/retry behavior, prerequisite collection existence, and the return marker already_existed:true. The gaps are minor — site_id is never characterized and the full success payload shape is only hinted at.

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?

With schema coverage at 33%, the description must carry weight and largely does: content is explained as a JSON object validated against the content_type schema, image-typed fields are documented as {url, alt} objects versus url-typed plain strings, content_type is tied to a site's inline collections[].fields, and slug idempotency semantics are spelled out. site_id and published_at get no treatment in the description, leaving two of six parameters to the schema alone.

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 precise verb+resource ('Create a new content_items row for a site under a given content_type slug') and enumerates the exact URL patterns it serves. It explicitly carves itself out from the sibling add_page, so an agent can route without opening 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?

Gives explicit when-to-use, an explicit when-NOT-to-use ('DO NOT use add_page for detail pages of an existing collection') with the reason (index won't reflect it, sitemap won't emit). It also names the correct alternatives in each branch: create_collection when no collections[] entry exists, edit_content_item on slug collision, find_images/upload_image for images, and get_editor_link for user-supplied files.

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 cover the safety profile (non-destructive write), but the description adds real behaviour: creates a bare shell of one section + one heading, returns root and section ids for insert_nodes/patch_nodes, writes a new draft version, and what breaks if misused (baked static tree, collection-list won't reflect, sitemap/SEO miss). That is 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?

Front-loaded with the core action and return shape, then the exclusion. The parenthetical lists of example slugs are a bit heavy, but each clause carries real routing or behavioural 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 mutating tool with no output schema, the description still discloses the return value (root + section ids) and the follow-up tools to use. Combined with the exclusion section, an agent has everything needed to call it correctly or route elsewhere.

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 only 25%, so the description carries much of the burden: it explains `copy_of` semantics and the slug-vs-title expectation implicitly through the example copy flow. The remaining params (slug, title, site_id) are self-evident, so no significant gap remains.

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 with scope: creates a one-off page, not a collection detail page. It explicitly distinguishes itself from its nearest siblings (add_content_item, create_collection) by naming the cases it does not handle.

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

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

Gives explicit when-to-use (About/Contact/Pricing/landing pages), an explicit DO-NOT-use condition (path-parameterised detail pages) and names the correct alternatives for each case. The failure mode of misusing it is also spelled out.

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 non-read-only, non-destructive, non-idempotent, closed-world behavior. The description adds the key state effect — it builds a subtree and 'splices it into the page, saved as one draft' — plus internal composition details (theme tokens, independently editable text/CTAs). It does not mention permission requirements or failure modes, so it falls short of a 5.

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

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

Front-loaded: what the tool does and its key differentiator come first, followed by usage and routing. The 20-kind list duplicates the schema's kind enum description and adds length, but the overall structure is efficient for a 15-parameter tool.

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 write tool with 20 kinds and no output schema, the description covers selection, routing, and input shape well. Minor gaps remain around required site/page state and return behavior, though the schema and annotations cover most of that territory.

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 93%, so per-parameter meanings are already documented and the baseline is 3. The description adds only a high-level grouping ('copy fields', 'items[] array for list-based kinds') that largely restates what the schema already says.

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 ('add') and resource ('section') to a page, and immediately distinguishes itself from node-tree authoring. It also names the sibling tools it replaces for other tasks (patch_fixture, patch_nodes, insert_nodes), so an agent can select it without opening other 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?

Explicitly routes usage: 'Use this — not patch_fixture — to populate a page or add a section in-editor,' then names patch_nodes for surgical edits and insert_nodes for bespoke structure. It also maps all 20 kinds to concrete use-when conditions.

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=false, so the safety profile is covered. The description adds real behavioral context beyond that: rate limit (5 captures/min), depth/breadth caps (500 nodes, 10 deep), and the explicit note that it saves nothing. These are material operational facts not present in the annotations.

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

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

The purpose and return-value enumeration are front-loaded and the workflow guidance comes before the caveats, so the structure is sound. It is dense but every enumerated item conveys concrete capability; the only slight cost is length, which borders on verbose even though each element 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?

There is no output schema, so the description carries the burden of describing return values — and it does so thoroughly across all six artifact types. Combined with annotations covering the safety profile and rate limits, an agent has everything needed to call this correctly 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% and both parameters (url, viewport) are fully documented in the schema itself. The description does not add meaningful meaning beyond that — it does not mention the viewport parameter or its desktop/mobile options. 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?

States a specific verb+resource ('Capture a public URL for cloning') and immediately enumerates the six artifacts it returns, which differentiates it from siblings like screenshot_page, read_rendered_page, and read_rendered_page. An agent can distinguish it from those 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?

Provides an explicit workflow ('capture → study screenshot + element_tree → compose a fixture from primitives → call create_site_from_fixture') and names the alternative path for rehosting images (upload_image with url). It also states the condition for using this over the template path. Nothing is left to inference.

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

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

Adds substantial context beyond annotations: the with-domain call re-checks DNS and marks the domain verified when records resolve, and on failure returns expected_records and message that must be surfaced verbatim. It also warns that a verified domain on a never-published site still 404s and suggests offering to publish. This is consistent with readOnlyHint=false and openWorldHint=true.

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 two operating modes, then adds the important never-published caveat and sibling routing. Every sentence carries useful information and there is no redundant restatement of the title.

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 dual-mode tool with no output schema, the description explains what listing returns, what re-checking does, how failures are surfaced, and the important 404 caveat. It is complete enough for an agent to call the tool correctly in both modes.

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 description thoroughly explains the domain parameter's dual semantics (omit to list, supply to re-check) and adds meaning beyond the 50%-covered schema. However, the required site_id parameter is not described at all beyond the general phrase 'attached to a site', so the description only partially compensates for the schema coverage gap.

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, then clearly distinguishes the tool's two modes: listing domains when no domain is supplied and re-checking DNS when one is. It also names the related siblings set_custom_domain and remove_custom_domain, so an agent can distinguish attach/detach/check without opening other 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?

Explicitly says when to omit domain (list every custom domain and verification state) and when to supply it (re-check DNS after records were changed at the registrar). It also routes attach and detach operations to the named sibling tools, covering both usage and alternatives.

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 non-readonly, non-destructive, non-idempotent, closed-world. The description adds real context beyond that: it writes a draft version rather than publishing, describes the post-conditions (detail URLs resolve via Mustache, the <collection-list> iterates seeded rows), and warns that the content type must be unique within the site. It stops short of stating what happens on content_type collision or whether an existing collection is replaced.

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 opening sentence front-loads the core action, and the bulleted post-conditions are scannable. It is longer than strictly necessary for a single tool, but nearly every sentence (uniqueness rule, inline fields schema, publish follow-up) carries operational information rather than 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 an 8-parameter tool with nested template and index-page trees and no output schema, the description supplies the workflow context an agent needs: preconditions (list_content_types), post-call state, and publish sequencing. The template Node tree shape is delegated to fixture file paths rather than described, which is the only real 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 88%, so the baseline is 3, and the description still adds value: it ties fields[] to template placeholders ('include every field the template references'), flags the uniqueness constraint on contentType, and routes the agent to list_content_types. It does not improve on the schema's own detailed notes for image fields or path_prefix, so it is not 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 and resource ('Stand up a new collection on an existing site in one call') and enumerates exactly what gets created: the collections[] entry, the optional index page, and seeded content_items rows. It also explicitly distinguishes itself from the row-level siblings (add_content_item / edit_content_item / delete_content_item) that manage items afterward.

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 trigger phrases ('add a blog to my site', 'set up case studies', 'add a careers section') and names the adjacent tools to call at each stage: list_content_types beforehand to check the catalog, publish afterward to go live. That is explicit when-to-use plus alternatives.

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 annotations: validation with autofix of minor issues, hard errors thrown with paths, the site is saved as a DRAFT whose live URL 404s until publish, and the return payload (preview URL, site_id, manifest, warnings) is described. That draft/404 consequence is exactly the kind of downstream effect an agent cannot infer from readOnlyHint/destructiveHint alone.

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 routing guidance, and most sentences carry real signal. Minor waste in the closing sentence, which restates the dry_run behavior already given two sentences earlier.

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 supplies the return values; with a nested open fixture object, it explains validation/autofix semantics and the draft-state outcome. 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 schema already documents fixture, site_name (brand-text caveat included) and subdomain. The description's dry_run note duplicates the schema text almost verbatim rather than adding format or shape detail, 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?

Specific verb + resource: 'Persist a fixture YOU composed as a new Sitelas site.' It immediately distinguishes itself from the sibling create_site_from_template by naming it and stating it is the fallback path.

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 ('archetype-based create_site_from_template can't produce the structure you need'), the two concrete triggers (post-capture_url cloning, bespoke briefs), and an explicit when-not ('For typical generation, prefer create_site_from_template') with a quality rationale.

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?

Adds substantial context beyond annotations: the site is saved as a draft and not live until publish, there is no per-node patch fallback, page_slugs and collection_prefixes must be set now because paths lock after publishing, and a full response field list is given. This fills in creation, publication, and path-mutation behavior not captured by the readOnly/destructive/idempotent hints.

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

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

The purpose and key constraints are front-loaded, and the dense response-field enumeration is justified because there is no output schema. It is long and packed into a single paragraph, but every sentence carries useful operational 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?

Comprehensive for a complex creation tool with nested parameters and no output schema. It explains return fields, the customization workflow, draft status, layout_plan behavior, and path-locking constraints, leaving little ambiguity for an 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 already 100%, so baseline is 3, but the description adds value by linking parameters to the post-create workflow: brand_overrides at create time followed by one bulk patch_nodes call, layout triggering layout_plan.steps in the response, and site_name requiring a separate brand-name patch. These are cross-parameter workflow semantics 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?

Starts with a specific verb and resource: create a new Sitelas site by cloning a template archetype. It clearly distinguishes the operation from sibling tools like find_templates (used first) and create_site_from_fixture by naming the template-cloning workflow and its customization path.

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 describes the standard workflow: clone, apply brand_overrides at create time, then make exactly one bulk patch_nodes call. It names when to pass layout and references specific sibling tools (patch_nodes, publish, get_site) and alternatives (alternative_templates).

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 destructive/idempotent annotations, the description explains the live-site vs. draft behavior, that links elsewhere are not changed but returned in dead_links, that orphaned items are cleaned up, and that the action is permanent. These are exactly the consequences an agent needs before invoking a destructive tool.

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

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

The description is dense but front-loaded: the first sentence states the deletion scope, followed by usage routing and then behavioral consequences. Every sentence adds material information, and the final 'Permanent.' warning is appropriately emphatic.

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 collection-deletion tool, the description is highly complete on behavior, side effects, alternatives, and return-side effects like dead_links. It falls short only on explaining the required parameters, which is a real gap for an agent preparing the 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 description coverage is 0%, so the description would need to explain the two required parameters. It never mentions site_id or content_type, nor how to identify the collection to delete. The description gives some conceptual context about collections but does not compensate for the parameter documentation gap.

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

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

The description uses a specific verb and resource and spells out exactly what is deleted: the collection schema, listing page, and every item. It also directly distinguishes this tool from delete_content_item and patch_fixture, so an agent can identify its scope without opening sibling schemas.

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

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

It explicitly states when to use this tool (when the user wants a whole section gone), when to use an alternative (delete_content_item for one entry), and when not to use another tool (never patch_fixture for collection removal). This is unusually clear 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?

Goes well past the destructiveHint=true annotation by disclosing the real-world consequence ('comes off the live site immediately'), the authorization model (ownership verified via the parent site's user_id), and the return payload (slug and content_type) despite there being no output schema. These are exactly the facts an agent needs before committing to an irreversible publish-affecting action.

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

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

Three tight sentences, front-loaded with the addressing rule, then the side effect, then the return value. No filler and nothing repeated from the schema or annotations.

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?

Covers addressing, live-site impact, auth, and return value for a destructive tool with no output schema. It omits cascade behavior (do child nodes, sections, or published assets disappear?) and whether the slug becomes reusable, which matter for a delete of this scope.

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 75% and item_id has no schema description at all, but the description supplies the crucial semantic the schema lacks: the two parameter sets are alternatives, and slug must be exact when paired with site_id + content_type. It does not clarify what happens if both addressing modes are supplied or whether any parameter is required (required list is empty).

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 (delete) and resource (content item), plus the two alternative addressing keys, so it is clearly distinguished from siblings like delete_page, delete_site and delete_collection. An agent knows exactly what object this removes without opening the schema.

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

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

It explains how to identify the target (item_id alone, or site_id + content_type + exact slug), which is implicit guidance on invocation. It never says when to choose this over edit_content_item, delete_page, or list_content_items, and offers no exclusions or preconditions beyond the ownership note.

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 destructive/idempotent/openWorld, but the description goes well beyond them: nav-link pruning is on by default, a container would not be emptied (kept with a warning), the live site updates immediately while nav-link edits stay in the draft, and remaining links surface in `dead_links`. This is exactly the kind of side-effect and edge-case disclosure a destructive tool 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?

The exclusion and the default prune behavior are front-loaded, and every sentence (warnings, live vs draft, dead_links) carries operational value. It is slightly dense and could be split, but no sentence is 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 destructive delete with no output schema, the description supplies the safety-relevant behavior and return signal (preview URL, dead_links). The only real gap is the undocumented cascade flag, which matters because it changes the blast radius.

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 only 50%, so the description must carry weight; it elaborates prune_nav_links well (including the kept-with-warning behavior), but `cascade` is never mentioned in the description and neither slug nor site_id semantics are clarified. With half the parameters undocumented in the schema and cascade absent from the prose, the baseline-3 compensation is incomplete.

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 ('Delete a page from a site') and immediately scopes it with the home-page exclusion. Among siblings (delete_site, delete_collection, delete_content_item) it is unambiguous which resource this removes.

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

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

Explicitly says when it cannot be used (home page '/') and describes the default nav-link pruning plus the opt-out via prune_nav_links:false. It also directs the agent to handle `dead_links` before replying. It does not compare against delete_site or clarify whether child pages are affected outside the cascade flag, so it falls short of a full when/when-not/alternatives treatment.

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 far beyond that: it lists every affected resource (subdomain row, snapshots, submissions, alias history, custom domains removed from Vercel, billing cancelled, media bucket) and discloses the atomicity guarantee if billing cancellation fails.

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?

Dense but every sentence earns its place: destruction scope, irreversibility, usage trigger, confirmation gate, and failure behavior are all front-loaded for a genuinely destructive operation where thoroughness is warranted.

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, yet the description tells the agent everything needed to call it safely: what is destroyed, that it is irreversible, that confirm must be true, the subdomain guard, and the abort-on-billing-failure behavior.

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 67% and the schema already documents confirm's const:true and confirm_subdomain's guard. The description reinforces the confirm requirement in a workflow context ('to be deliberate') and ties subdomain confirmation to safety, though it does not compensate for the undocumented site_id.

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 ('Permanently delete a site') and enumerates exactly what is removed, which also distinguishes it from sibling destructors like delete_page, delete_collection, and delete_custom_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?

Explicit when-to-use with example utterances ('scrap a site', 'I created the wrong template'), explicit when-not-to-use ('Do NOT call this on user-said-something-vague'), plus the required confirmation workflow before invoking.

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 the safety profile (destructive, idempotent, non-readonly); the description adds the behaviors that actually matter here: shallow-merge semantics, merged-result validation against the content_type schema, fuzzy title resolution with error-on-ambiguity, 308 redirect on rename, ownership verification via parent site user_id, and slug-collision failures. This is far beyond what the annotations 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?

A single dense paragraph, but it is front-loaded with the core action and every clause earns its place (resolution, patch semantics, validation, image handling, ownership, errors). It is long relative to typical definitions, though for a nested-object mutation with no output schema the density is defensible rather than padded.

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

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

Covers the entire call path an agent needs: how to resolve the item, what patch fields do, merge/validation rules, image-field gotchas, and failure modes. With no output schema, the description also carries return-adjacent context through its error behavior, leaving no obvious 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 high (83%), so the baseline is 3, but the description adds real semantics: the image field object shape and the bare-URL coercion rule, the shallow-merge warning that re-sending alt is required, the validation and rejection behavior when content is patched, and the conditional requirement linking site_id/content_type to slug/title resolution.

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 ('Update fields on an existing content item') and immediately clarifies scope via the identification paths, which separates it from siblings like add_content_item, delete_content_item and publish_content_item. An agent can tell what the tool mutates 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 conditional guidance on resolution ('Identify it by item_id, OR — when you only know its name — by site_id + content_type + (slug | title)') and states the 'at least one field is required' constraint. It stops short of naming alternative sibling tools or when-not-to-use conditions, so it sits below explicit routing.

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, open-world, non-destructive, but the description adds genuinely new facts: the 30-searches-per-minute-per-user rate limit, the full return shape (URLs, thumbnails, dimensions, average color, attribution), and the critical side-effect boundary that nothing reaches the site until upload_image is called. That side-effect clarification is exactly the kind of context annotations cannot 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?

Front-loaded with the core action and the pre-composition constraint, then chaining advice, then caveats. It is on the long side and repeats the query-specificity advice that also appears in the schema, which is minor redundancy rather than waste.

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, yet the description enumerates the return fields, and it covers rate limits, the upload_image handoff, and per-orientation selection. An agent has everything needed to call this correctly and to know what to do with 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 coverage is 100%, so the baseline is 3, but the description adds query-craft guidance ('brooklyn bakery sourdough on wooden counter' beats 'bakery') that goes beyond the schema's phrasing. The count and orientation parameters are left to the schema and are only implicitly referenced, so it does not fully compensate on all three.

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 ('Search a curated stock photography library (Pexels) for real imagery') and distinguishes itself from siblings like list_site_images and replace_images_from_search by being the Pexels search entry point. An agent can tell exactly what will happen 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?

Explicit timing guidance ('Call this BEFORE composing any section that needs imagery — hero, feature-grid, testimonial cards, gallery, media-and-text'), names the follow-up alternative (upload_image with url) with a stated reason ('external URLs can rot'), and gives negative guidance against generic queries. This is textbook when/when-not/alternatives coverage.

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, idempotentHint=true, and destructiveHint=false, and the description is fully consistent with them: "Read-only: create_site_from_template creates the site." It adds behavioral context beyond annotations, including ranking semantics, match_quality meanings, out_of_scope handling, and layout_plan follow-up steps.

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 front-loads the purpose and the RANK/BROWSE split, and most sentences carry operational guidance that an agent needs. Some audience and register detail overlaps with the already-rich schema, so a slightly tighter version would be ideal, but it is structured and purposeful.

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 16-parameter, annotation-covered, read-only tool without an output schema, the description supplies the missing return-value semantics: match_quality, out_of_scope/instead, audience_check, and layout_plan. It also explains creation handoff to create_site_from_template, so an agent has enough context 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 useful grouping and workflow semantics: it explains that audience plus keywords plus needs drive ranking, that browse mode uses audience/query/slugs, and how layout relates to layout_plan. It does not fully duplicate every parameter definition, but it meaningfully clarifies which parameters to use in which mode.

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

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

The description states a specific verb and resource: choosing the template a new site starts from. It clearly distinguishes the two operating modes (RANK with a brief vs BROWSE without one) and explicitly routes site creation to the sibling tool create_site_from_template.

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

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

It gives explicit when-to-use guidance for both modes: pass a brief to rank, omit one to browse. It also explains follow-up conditions such as checking match_quality, handling out_of_scope, re-running with audience_check, and passing layout when the owner described the site's shape.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds real behavioral context: default trailing-28-day window, the shape of the response, the 90-day cap on activity, and the Free-tier billing_gate behavior with an instruction on how to react. That goes well beyond structured 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?

Front-loaded with purpose and return shape, then parameter guidance, then the gating caveat. Every sentence carries information; no repetition of schema or annotation 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?

With no output schema, the description supplies the return shape, defaults, and tier gating — enough to call correctly. Only `top_n` semantics are 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 coverage is only 17%, so the description must compensate — and it does for `range_days`, `since`/`until`, and `include_activity`, including the 90-day constraint. `top_n` (with its 1-50 bounds) is left undocumented, a minor gap.

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 ('Fetch pageview and unique-visitor analytics for a site') and enumerates the return contents (totals, daily timeseries, top paths, top referrers). No sibling tool covers analytics, and the scope is 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?

Gives clear selection logic between `range_days` and `since`+`until`, and names the trigger for `include_activity` ('how's my site doing?'). It lacks an explicit 'do not use this for X' exclusion, but the context is strong.

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 by explaining that the editor link opens signed in as the user but may still route to sign-in depending on session cookies. It also discloses the photo link's security model: one-time capability, 30 minutes, one upload, draft only, and not to be shared beyond the intended person.

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 and uses bullet structure effectively for the main usage cases. It is somewhat long and occasionally conversational, but most content earns its place by clarifying routing, auth behavior, and link sensitivity.

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 link-returning tool with no output schema, the description explains both possible link modes and their important constraints. It also covers the prerequisites and caveats an agent needs before handing the link to a person.

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 carries most parameter meaning. The description still adds useful selection semantics by explaining that image_target should be passed only when the person is supplying their own photo for a named spot, and that omitting it returns the editor instead.

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

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

The description states a specific verb and resource: returning a link to the site owner's visual editor, optionally opened to a page or collection item. It clearly distinguishes this from image-sourcing and placement tools like find_images, replace_images_from_search, and upload_image.

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

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

It gives explicit when-to-use cases: when the next step belongs to the person, when they want to make edits themselves, or when they ask to see their site. It also draws the key routing line between editor links for user-owned files and direct image placement tools for sourcing/placement.

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

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

Annotations already cover the safety profile, readOnly, idempotent, non-destructive. The description adds useful behavioral context beyond annotations: it discloses that responses are trimmed, limited to the first page's sections, and include collection fields with one example item plus theme/template metadata. It does not cover errors or pagination, so it is not fully exhaustive.

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 first sentence front-loads the purpose and return shape, and the usage guidance follows logically. Some phrasing is motivational and slightly repetitive, such as 'not avoiding examples on principle' and 'the goal is never to replicate,' but these sentences still steer agent behavior.

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 describe return values, and it does: first page's sections up to 8, each collection's fields with one example item, and theme/template metadata. Given the tool's reference-gathering role, the description is complete enough for an agent to call and interpret 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 description coverage is 100%, so limit, minimal, categories, and archetypes_category are already documented in the schema. The description alludes to calling 'with that category' and reading the skeleton, but adds little parameter-specific syntax beyond what the schema provides, making 3 the appropriate 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?

Names a specific verb and resource: 'Return example fixtures in the shape Sitelas expects.' It also explains exactly what the response contains and contrasts the tool with get_primitive_schema and composing from design principles, so an agent can distinguish reference-gathering from other schema/template 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?

Explicitly states when to use it: on an unfamiliar category, for a correct first call, by reading the skeleton first. It also names the alternative path, get_primitive_schema plus design principles, and warns not to replicate the example content.

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 readOnly annotation by disclosing that this reads the DRAFT not the live site, that whole-site content views are large and should be scoped, that header/footer/collections are always included in site_elements, and that copy view rewrites nothing for the agent.

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 draft-vs-live distinction and then routes by view in one dense paragraph; only the trailing 'Read-only.' is redundant with annotations, otherwise there is little waste.

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, yet the description explains what each view returns (node ids with text, form fields, FAQ items, container nesting, site-wide copy) and the max_items/truncated retry behavior, which is enough to call it correctly.

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

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

Schema coverage is 80% and the schema's own param descriptions are richer than the prose (e.g. view enums, page_slug caveats, max_items truncation follow-up are all repeated in schema). The description adds selection guidance for views but little parameter meaning the schema lacks.

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 ('Read what is on the site's DRAFT') and immediately distinguishes the three output modes, so an agent knows exactly what it returns versus read_rendered_page or get_site.

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

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

Explicit routing: 'content' is for returning to a site and before patch_nodes, 'structure' for moving/inserting/removing containers, 'copy' for a full rewrite, plus named alternatives (read_rendered_page for visitor view, get_site for pages/theme/publish state).

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

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

Annotations already cover the read-only/idempotent safety profile, and the description adds substantial meaning on top: it explains what styleStrip is, why certain inline styles are silently dropped by renderers, and what to do instead (use a Stack/Grid child). That is exactly the kind of non-obvious behavior an agent cannot get from structured 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 sentences, front-loaded with the return contract before diving into styleStrip semantics. The styleStrip parenthetical is dense but each clause carries real information; minor wordiness in the example explanation keeps it from 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?

No output schema exists, and the description fully specifies the shape of the returned data including the non-obvious styleStrip map. For a read-only, single-optional-parameter introspection tool this covers everything needed to call it correctly.

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

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

Schema coverage is 100% and the single optional `type` parameter is already documented with examples. The description restates the omit-to-list behavior, adding little beyond the schema, 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?

States a specific verb and resource ('Return the full prop schema for a single primitive') and enumerates exactly what comes back: types, defaults, options, required fields, allowed children, and styleStrip. No sibling in the tool list does schema introspection, so an agent can identify this tool's role at a glance.

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 a concrete workflow instruction — 'Read styleStrip BEFORE setting style on a node — eliminates the silent-drop trial-and-error' — and explains the no-arg mode ('Without `type` it lists every primitive'). It lacks explicit when-not-use guidance, but with no competing introspection sibling the context is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real operational context the annotations cannot: the default slim theme keeps responses compact, and the live_url null case is called out with the recommended agent behavior ('say so and offer publish rather than handing over a link'). That last point is exactly the kind of branch-handling guidance descriptions should carry; it stops just short of covering pagination/size limits on the pages array.

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 payload summary, then exclusions, then defaults and optional flags — a sensible order for an agent scanning top-down. It is long and the 'brief'/'data_files' glosses duplicate the schema's own parameter descriptions, so a few phrases fail to earn their 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?

No output schema exists, so the description carries the return-shape burden and does so thoroughly: per-page fields, site-wide search settings, theme default vs full, and the specific null case for live_url. An agent has enough to call it correctly and to interpret the result without a second lookup.

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 67%, and the description compensates by framing `include` as the way to get more in one call and by giving the default and the round-trip rationale for include_theme_config. It repeats some of the schema's enum explanations rather than adding new detail there, which keeps it below a 5.

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

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

Opens with a specific verb+resource ('Fetch details of a single site') and then enumerates exactly what comes back — pages, theme summary, search settings, publish status, URLs. It explicitly contrasts with get_page and get_site_changes, so an agent can place it precisely among 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?

Names the alternatives and the conditions that select them: get_page with view: 'structure' for the node tree, get_site_changes with include_versions: true for history, include for extra bundles, include_theme_config only when round-tripping the theme. Exclusion guidance is explicit rather than 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description reinforces read-only while adding substantive behavior: the implicit draft-vs-live baseline, what `since: 'previous'` widens to, and that `include_versions` returns three snapshots. It stops short of describing output shape or any size/latency limits, which keeps it from 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?

Every sentence carries information: the first defines the output scope, the second the default comparison, the third and fourth the alternate modes, and the last the safety hint. It is front-loaded with the core behavior and has no filler.

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

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

With no output schema, the description usefully sketches the return categories (added/removed/changed pages, theme/header-footer changes, optional snapshots). It does not mention result size, pagination, or how large diffs are reported, which is a modest remaining gap for a five-parameter comparison 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 80%, so the baseline is 3, but the description adds real meaning: it explains that `from` + `to` compares any two of live/draft/previous and gives the concrete example of 'previous' to 'live' being what the last publish did. `site_id` is left unexplained, which is the only gap.

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 ('Summarise what changed') and enumerates exactly what is captured: pages added/removed, content changes, and theme or shared header/footer changes. No sibling tool performs a diff/snapshot comparison, and this scope statement makes that distinct role unmistakable.

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 the default comparison ('draft against what is live — what is waiting to be published') and when to switch modes via `since: 'previous'` or `from` + `to`. There is no explicit exclusion or named alternative tool, but the mode-selection guidance effectively tells an agent which configuration to pick for which question.

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=false / destructiveHint=false; the description adds the traits that actually matter: all insertions land in one new draft version, the batch is all-or-nothing on a missing parent, colliding id, or bad after_id, and the cap is 50 per call. It further discloses the returned id_map, the slot-tagging validation behavior (unknown slot rejected with closest valid names, untagged content produces a warning), and the extra: {slot} convention for get_page(view: content).

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?

Structure is front-loaded and logical: what it does, insertion shape, structural-add use cases, copy_of alternative, cross-page collection case, safety versus patch_fixture, tagging, failure modes, limits. It is still dense and runs long for a tool description, and the doubled 'get_primitive_schema + get_primitive_schema' plus the unsupported node_json variant are sentences that don't earn their space.

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

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

There is no output schema, yet the description still tells the agent what comes back (id_map for copies), what a rejection looks like and its three triggers, and the batch size ceiling — everything needed to call it correctly and to chain patch_nodes afterward. For a 2-parameter, atomic, mutation tool this is complete.

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?

At 50% schema coverage the description does real work: it explains position's three spellings, that parent_id may point anywhere in the fixture (pages + siteElements), and the copy_of-versus-node decision with the copy's exact-match/fresh-id semantics. It loses a point for describing an input shape the schema forbids — a single top-level `parent_id` + `node_json` — which would fail against this draft-07 schema's root `additionalProperties: false`, and for the garbled 'Use get_primitive_schema + get_primitive_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 opens with a specific verb and resource ('Add many nodes to a site in ONE call, batched into one new draft version') and immediately names the sibling it supersedes for raw path-level edits (patch_fixture's JSON-Patch 'add'). It also splits the space between inserting new subtrees and cloning existing ones via copy_of, so an agent can distinguish this from add_section, add_page, or move_nodes 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?

When-to-use is spelled out with concrete scenarios (new section on a page, nav link, card in a grid, restoring a removed container), and when to switch to copy_of is given with its own trigger ('adding one more of something that already exists') plus a follow-up step (patch_nodes the copy's text via id_map). It even routes the cross-page collection case ('put my latest projects on the About page') to copy_of the collection-list with limit set, which is a non-obvious alternative an agent would otherwise get wrong.

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/non-destructive, so the safety burden is covered. The description adds real behavioral context beyond that: default ordering by most recent activity, that `email` overrides all other filters, and that the timeline is capped at `limit`. It doesn't mention pagination behavior of `offset` or the shape of a list-mode result, keeping it from 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?

Three compact sentences, front-loaded with the core capability, followed by filters and then the special email mode. The paraphrased example ('tell me everything we know about Sarah') earns its space by disambiguating intent. No filler.

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

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

There is no output schema, but the description covers the return shape for the email mode (contact record plus timeline, newest first, up to `limit`). The list-mode row shape isn't described, which is the main gap for a 9-parameter listing tool. Otherwise an agent has enough to call it correctly.

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

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

Schema description coverage is only 11%, so the description has to carry the load, and it does: it names the filter axes (text, tags, activity thresholds) and maps them to `min_submissions`, `subscribed_only`, and `since`. The `email` mode's override semantics ('the other filters are ignored') are also stated in prose. `limit` and `offset` paging semantics are left to the schema defaults.

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 contacts who have interacted with a site') and scopes it with concrete qualifiers (filled a form, subscribed to newsletter). This clearly separates it from sibling tools like list_submissions and read_submission, which operate on individual form entries rather than contacts.

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

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

Explicitly says which filters to use for list queries and dedicates a sentence to the alternate mode: 'Pass `email` for everything about one person.' The when-to-use for the single-person lookup is concrete and even includes a natural-language example. It stops short of naming sibling alternatives such as list_submissions, so it's 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 already declare readOnly/idempotent/non-destructive, so the safety burden is covered; the description adds genuine value beyond that by disclosing the returned fields (id, slug, full content JSON, visibility, timestamps) and the paging mechanism. It still doesn't mention pagination limits or total counts, but that is a minor gap.

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 sentences: scope first, filters second, return shape third, alternative-tool note last. No redundancy and nothing before the key filtering constraint.

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 compensates by naming returned fields, and annotations cover the safety profile, leaving an agent able to call it correctly. Only pagination behavior/limits remain 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 0%, so the description must carry the load; it does define content_type as a slug filter and enumerates visibility values, but the visibility default is already in the schema and it never explains site_id or the limit/offset semantics (default 50, max 200) beyond the word 'paging'.

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 ('List content items') with concrete examples (blog posts, projects) and the scoping key (site + content_type slug), which cleanly separates it from siblings like list_content_types or list_sites.

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 routes mutation intent to add_content_item / edit_content_item / delete_content_item, so the agent knows this is the read path. However, it gives no guidance on when to prefer this over other listing/read tools (e.g. list_content_types, get_site_tree) or prerequisites for the content_type slug.

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/non-destructive and closed-world, so safety is covered. The description adds genuinely non-obvious behavioral context: schemas are per-site with no platform catalog, the schema is open so `observed_fields` should be included on write, and `image` fields are stored as `{url, alt}` objects rather than strings. It does not cover pagination or response size, but the extra context is substantive.

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 what it lists and the primary call-before guidance, then a clearly separated block for field-type semantics. The type-mapping block is dense and long, but its caveat about `image` objects earns its space; minor tightening of the field enumeration would improve it.

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 carries return-value burden: it enumerates every returned property and maps each `type` to its underlying value shape. Nothing an agent needs to call this correctly and interpret the result 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 both `site_id` (per-site catalog) and the `content_type` detail-template mode are already documented in the schema. The description reinforces per-site scoping but adds no syntax or examples for the `content_type` parameter itself, 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?

Opens with a specific verb and resource ('List every content collection declared on a site') and immediately states the per-site scope plus the returned shape (`fields[]`, `contentType`, `pathPrefix`, `observed_fields`). An agent can distinguish it from `list_content_items` or `get_primitive_schema` 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?

Explicitly routes two workflows: 'Call this before `add_content_item` to discover which fields a collection supports — or before `create_collection` to confirm a contentType isn't already taken.' Both the when and the specific sibling alternative are named.

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/non-destructive, so safety is covered. The description adds ordering (newest first), return payload contents (public URLs, storage paths, byte sizes), and a conflict-behavior warning about concurrent edits in the editor. Most of that warning concerns the sibling write tools rather than this tool itself, which keeps it just short of a 5.

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

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

The lead sentence front-loads purpose and return shape, and the two-use framing follows immediately. The second paragraph is slightly long and spends more words on sibling-tool hazards than on this tool, but every sentence carries actionable 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?

No output schema exists, and the description compensates by naming the returned fields. For a three-parameter read tool with full annotation coverage, an agent has everything needed to select and call it correctly.

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

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

Schema coverage is 100%, so site_id, limit, and since are already fully documented, establishing a baseline of 3. The description adds a workflow-level interpretation of `since` (pass the moment you sent the editor link), but no format or edge-case detail 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?

Opens with a specific verb and resource ("List the images in a site's library, newest first, with their public URLs") and distinguishes itself from the upload-side siblings (upload_image, find_images, replace_images_from_search) by describing a read of the existing library. An agent knows exactly what it gets back 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?

Names two concrete situations to use it (collecting what arrived after get_editor_link, and checking pre-existing images before upload) and pairs each with the follow-up tool. It goes further and states which downstream tools NOT to use (patch_fixture, replace_site) and why, which is real routing guidance rather than implied usage.

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, so safety is covered structurally. The description adds real value beyond that by explaining the null `live_url` semantics and how the agent should respond to it, though it says nothing about result volume or ordering for larger accounts.

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?

Five short sentences, each earning its place: purpose, return fields, the `url` guarantee, the `live_url` null case with a prescribed action, and the sibling pointer. The most decision-relevant constraints 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?

With no parameters, no nested objects, and no output schema, the description carries the return-shape burden itself and does so by listing the key fields plus the one field whose null value changes agent behavior. Nothing needed to call or interpret 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?

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description correctly devotes its space to return-value semantics instead.

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 all websites owned by the current user') and enumerates what comes back (subdomain, publish status, plan tier, creation date, URLs). It explicitly differentiates from the sibling get_site by scoping itself to listing and pointing to get_site for per-site detail.

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?

Names the alternative ('Use get_site for per-site detail') and gives concrete handling guidance: share `url` because it always resolves, and when `live_url` is null offer publish instead of a link. The when-to-use and the edge-case behavior are both 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?

Beyond the annotations, it discloses detailed behavior: return summary fields, durable attachment links, the `monthly_counter` structure, per-calendar-month allowance semantics, locked-submission behavior on Free, and the fact that capture is never gated on plan. It also gives important agent-facing guidance not to imply data was lost or to pitch a plan change, which is unusually rich behavioral 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 front-loaded with purpose and return shape, then proceeds through allowance and filtering details. It is long, but most sentences carry non-obvious behavioral or policy information that an agent needs in order to respond correctly to locked submissions.

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 carries the burden of explaining return values, and it does so in detail: summary fields, attachment links, and the `monthly_counter` block. It also explains the complex locked-submission behavior and filter semantics thoroughly enough for an agent to call the tool correctly.

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

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

Schema description coverage is 0%, and the description adds useful meaning for three of five parameters: `form_type`, `unread_only`, and `since`. However, it does not explain `limit` or add much beyond the obvious for `site_id`, so it only partially compensates for the lack of 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 starts with a specific verb and resource: "List form submissions for a site." It clearly distinguishes itself from `read_submission` by saying this returns summaries and by explicitly directing the agent to `read_submission` for the full payload of one submission.

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 names when to use this tool versus `read_submission`, lists the available filters, and warns that `form_type` is free-form so an unfiltered call should be read before filtering. It also explains that locked submissions cannot be recovered through `read_submission` or contact tools, which is a clear usage constraint.

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 destructiveHint=true, idempotentHint=false, readOnlyHint=false, and the description adds real context on top: which operations are rejected and that the tool 'writes one new draft version' rather than mutating live content. It stops short of covering recoverability (undo) or what the response returns, but the safety profile is well conveyed.

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 its two modes, then constraints, then alternatives — a sensible order. The position-value recap slightly duplicates the schema, and the single dense paragraph could be split for scanability, but nothing 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?

For a destructive, non-idempotent mutation with no output schema, the description covers the essentials: modes, validation rules, and the draft-version write. The remaining gap is what the agent gets back and whether the move can be reversed via undo, which would round it out.

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

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

Schema coverage is 80% and already documents all five parameters, so baseline would be a 3. The description adds genuine meaning beyond the schema by spelling out the position vocabulary ('start' / 'end' / { after_id }) inline and by stating that target_parent_id must live in the same page/element tree as node_id — a server-side constraint the schema only hints at.

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 (move a node) and immediately scopes it to two modes: reorder within the current parent or re-parent within the SAME tree. It also self-describes as 'the safe reordering primitive,' which separates it cleanly from insert_nodes and add_page named later.

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 exclusions and alternatives: cross-tree moves should use add_page (with copy_of) / insert_nodes. It also enumerates the rejected cases (root node, self/descendant, cross-tree), so the agent knows both when to use it and when the call will fail.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context beyond the annotations: the mutation lands in a 'draft version' rather than the live site, the return value is a preview URL, and screenshot_page is the follow-up for visual verification. It stops short of saying whether existing draft edits are overwritten.

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?

Five tight sentences, each earning its place: action, when-to-use, path format, return value, and follow-up tool. The core operation is front-loaded before the routing and format details. No filler.

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

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

With no output schema, the description correctly covers the return value ('Returns the preview URL') and the follow-up verification path. It also handles the path-format subtleties of JSON Pointer. It omits the 200-op limit and whether the prior draft is replaced, which are minor gaps for a two-parameter 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 50% and the description's path-format note ('/theme/config/colors/primary', '/pages/0/tree/children/2') largely duplicates the example already present in the json_patch schema description, though the theme-token example is new. site_id remains undocumented in both places, albeit self-evident as a UUID. The description adds only marginal meaning over the schema, so baseline 3 is right.

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 — 'Apply an RFC 6902 JSON Patch ... to the latest fixture snapshot for a site, then save the result as a draft version.' It clearly conveys the operation and its output state. It implicitly contrasts with update_site_from_fixture ('without shipping the full fixture again') but never names a sibling tool, so it falls short of full differentiation.

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

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

Gives an explicit when-to-use condition: 'Use this when you need precise multi-field edits across the fixture ... without shipping the full fixture again.' That is a clear routing rule. However, it offers no when-not guidance and does not name alternatives (e.g. patch_nodes, update_site_from_fixture) that an agent might otherwise confuse it with.

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 (destructiveHint/idempotentHint/openWorld) by disclosing partial-success semantics, duplicate-node_id merge rules, search order across pages/header/footer/collection templates, the collection_templates_touched side effect that changes every item page at once, plus post-write dead_links and unreadable_text/contrast-check side effects. These are exactly the behaviors an agent must anticipate before invoking a destructive batch write.

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 and the 'primary patch primitive' claim are front-loaded, and nearly every sentence carries operational value (rejected handling, merge rules, template side effects). It is, however, a single dense paragraph with some overlap against the nested schema descriptions and would read better chunked.

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, yet the description documents the notable return fields — rejected/patches_rejected, dead_links, unreadable_text, collection_templates_touched — and warns to check dead_links before reporting completion. Nothing material is missing for a 200-item batch mutation 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?

Adds real routing meaning beyond the schema: which node types each shorthand lands on, that data_patch keys are camelCase and validated against the primitive schema, and that unknown keys reject the patch with allowed keys listed. Slightly reduces confidence because the routing summary omits 'callout' and says nav-link routes to data.text while the schema says data.label for nav-link's label.

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 (node-level patches applied in one call, batched into one new draft version) and explicitly positions itself as the primary primitive — 'there is no single-node tool' — separating it from insert_nodes, update_page and move_nodes. An agent can identify the tool's role 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 concrete when-to-use guidance via the 'typical post-create flow' (read manifest, build {node_id, text} entries, send ONE call) and explicit failure routing (send a small follow-up for entries in 'rejected' rather than resending everything). It also names the alternative (get_primitive_schema) for cases the shorthands don't cover.

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 (destructiveHint/idempotentHint/openWorld) by disclosing that the live URL does not resolve until this runs, that the action is reversible via undo with what: 'last_publish', and that a billing_gate result must be surfaced verbatim rather than worked around by unpublishing another site.

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 scope rules, then the consent gate, then error handling. Dense and mostly waste-free, though the 'with page_slug it publishes one page; with item, one collection item' sentence partly restates what the schema already documents.

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-idempotent mutation with no output schema, it covers the side effect (live URL), reversibility, the consent precondition, the error path, and what the returned url guarantees. An agent has everything needed to invoke it safely.

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 75%, and the description reinforces the crucial default semantics — omitting page_slug or item promotes the whole draft, and passing them narrows scope to a single page or collection item. It adds intent-level meaning (page_slug requires an already-live site) but leaves locale unaddressed 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 and resource ('Make the draft live') and then enumerates the three scope modes: whole draft, one page via page_slug, one item via item. This lets an agent distinguish it from siblings like add_page, add_content_item and unpublish without reading 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?

Explicit when-to-use gate: only after the owner's explicit yes following a preview, with an explicit prohibition on auto-publishing and on inferring publish intent from 'change X'. It also names the correct alternative flow (add_content_item writes the draft, this takes it live).

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/non-destructive, and the description still adds substantive behavior: server-side render in ~35ms with no browser, reads the draft via preview URL, live mode also surfaces dead links. It also explains what it catches that a diff cannot — exactly the context an agent needs to trust the result.

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 primary directive and the key contrast, but the bike-shop and Medicare FAQ anecdotes, while persuasive, add length that a schema-driven reader does not strictly need. Efficient overall, slightly padded by narrative.

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 does describe the return shape (rendered text, headings, expanded items, `dead_links`) and the two modes. Missing only explicit pagination/size limits for very large pages, which is minor for a read 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?

The `live`, `item`, and `slug` parameters are all given purpose and timing in the description, well beyond the schema's own text. `site_id` is left undocumented in both places, but the remaining semantics are strong enough to exceed the 75%-coverage 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?

States a specific verb and resource ('Fetch a page's SERVER-RENDERED text via the preview URL') and enumerates what comes back (visible copy, headings, expanded list items). It explicitly separates itself from get_page (structure) and screenshot_page (looks), so an agent can pick it without opening any schema.

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

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

Gives explicit triggers: 'Call it on every page you touched, before showing the user anything', prefer over screenshot_page, `live: true` after publishing and before sharing the address, `item` right after add_content_item or a detail-template edit. Alternatives and exclusions are named outright.

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=false, and the description explains precisely why: the tool marks the submission as read by default, and it gives the escape hatch (mark_read=false to leave the is_read flag alone). This explains the mutation, its opt-out, and is consistent with idempotentHint=true (marking read twice is idempotent) and destructiveHint=false.

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, front-loaded with the primary fetch purpose, then the side effect and its override. No filler; every clause 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 no output schema, the description compensates by enumerating the returned fields (name, email, message, every field value, schema at submission time) and discloses the read-marking side effect. An agent has everything needed to call it correctly.

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

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

Schema coverage is 0%, so the description must carry the load; it does so for mark_read, explaining the default behavior and what false does—well beyond the bare boolean schema. submission_id is only implied by "by id" and not elaborated (e.g. UUID), leaving a small gap.

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 ("Fetch the full content of a form submission by id") and enumerates exactly what comes back (name, email, message, every field value, schema at submission time). The "by id" framing distinguishes it from list_submissions at a glance.

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

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

Usage is implied: fetching a submission requires an id, and the mark_read default is explained. But there is no explicit guidance on when to choose this over siblings like list_submissions or draft_reply_to_submission, nor any precondition about obtaining an id first.

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 destructive=true and idempotent=true, so the bar is lower, but the description still adds real value: it discloses that the domain is removed from both the Vercel project and Sitelas's records, that the *.sitelas.com address keeps working, and that the owner must remove DNS at the registrar afterwards. The confirm: true requirement is also surfaced.

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 sentence that is front-loaded with the core action, then the reasons, then the confirm requirement, then the post-action note. It's slightly long but nearly every clause carries meaning.

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 annotations covering safety, the description supplies the missing operational context: what remains working, what the caller must do after (DNS at registrar), and what Sitelas cannot do. Enough to call it correctly, though a hint about verifying removal isn't included.

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 all three parameters are documented in the schema, so baseline is 3. The description reinforces the confirm requirement and the apex+www scope but adds little syntax or format detail beyond what the schema already 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?

States a specific verb+resource pair (detach/delete a custom domain from a site) and clarifies the apex + www scope. It is clearly distinguishable from sibling tools like set_custom_domain and check_custom_domain without opening their 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?

Names concrete situations that select this tool — a typo'd domain, swapping to another domain, or stopping serving a hostname — which gives the agent clear usage context. It stops short of explicitly naming set_custom_domain as the swap alternative, so it's a 4 rather than 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 flag destructive=true and non-idempotent, but the description adds substantially more: all removals collapse into ONE new draft version, operations are validated against the actual tree, the batch is all-or-nothing (a single missing node id rejects everything), root nodes are refused, and there is a 50-removal cap. These are failure and atomicity semantics an agent cannot infer from 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 core action and scope, then alternatives, then failure semantics — a sensible order with no filler. The closing 'Up to 50 removals per call' duplicates the schema's maxItems, and the traversal detail overlaps node_ids, so it is slightly longer than strictly needed.

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 batch mutation with no output schema, the description supplies everything an agent needs: what gets created (a new draft version), atomic failure behavior, root protection, the count limit, and the safer-alternative framing. Nothing material 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?

node_ids already carries a detailed schema description covering traversal locations, splice behavior, root-node refusal, uniqueness, and the 50 cap — the prose largely restates this. site_id is undocumented in both places (schema coverage 50%), and the description adds nothing about it. Adequate, but little value 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 and resource (delete many nodes from a site) plus the scope constraint (in ONE call, batched into one new draft version). The concrete examples — dropping a testimonials section, removing a nav link, cutting a card from a grid — make the operation unmistakable and distinguish it from siblings like delete_page, move_nodes, and patch_nodes.

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 names the use case ('structural subtraction ... whenever the brief calls for the template's layout minus something') and the alternative (patch_fixture's JSON-Patch 'remove' ops), with the reasons selecting this tool: no hand-constructed paths, tree-validated, no root removal. It also routes root-node deletion to delete_page, so both the when and the when-not are covered.

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

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

Annotations already flag destructiveHint/openWorldHint/idempotentHint=false, but the description adds substantial context beyond them: all patches land in ONE new draft version (not a live publish), missing node_ids are reported as skipped rather than fatal, and there is a hard cap of 20 images per call driven by the Pexels rate budget. These are exactly the mutation-safety and failure-semantics details 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?

Front-loaded with the core action and the one-call benefit, then the alternatives, then the input-construction guidance and limits. Dense and nearly every sentence earns its place, though it is a long single paragraph that could be broken up for faster scanning.

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, but the description covers the essentials for a destructive batch mutation: draft-version isolation, skipped-node reporting, and per-call cap. It could say more about the response shape when some patches are skipped, but nothing critical to correct invocation 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?

With only 50% schema coverage, the description carries weight by explaining how to build patches from manifest image_nodes and when to override the suggested_query. The 20-item cap and the 'node_id (and field) may appear at most once' uniqueness rule are stated. It stops short of restating the orientation/field semantics, which the schema itself documents well, so it adds value without duplicating everything.

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 compound verb chain (search Pexels, upload to CDN, patch src + alt) on a specific resource (many image nodes at once) and explicitly distinguishes itself from the sibling sequence find_images + upload_image. An agent can tell exactly what this tool does that no sibling 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?

Gives an explicit trigger ('use this after create_site_from_template to swap every placeholder image'), names the alternative it replaces ('2N sequential calls (find_images + upload_image (with url) per image)'), and explains how to source inputs from the manifest's image_nodes and suggested_query. When-to-use and when-to-use-the-other-option are both covered.

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

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

Annotations declare destructiveHint=true and non-idempotent, but the description goes further: it says precisely what is destroyed (pages, theme, header and footer), that the work must be redone afterwards (copy and photos), and that the live URL is unaffected because the result is still a draft. It adds post-call behavior too — share `url`, relay `next_step`, never claim it is live.

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, then mode-by-mode breakdown, then the post-call instruction — a clean structure. A few clauses (the owner's "not my style" quote, the repeated reminder to redo copy and photos) are slightly padded, but nothing is redundant with the schema.

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, nested-payload mutation with no output schema, the description covers draft-vs-live semantics, the three payload shapes, consent, and the follow-up agent script; the stale-write guard lives in the schema text. Nothing an agent needs to invoke this safely 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 coverage is 100%, so the baseline is 3; the description earns above it by explaining the semantic effect of each mode argument (template_slug rewrites the same site rather than creating a new one; fixture replaces everything; page_updates touches only listed page trees). It does not add detail on expected_draft_updated_at or theme combination beyond what the schema already states.

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 ("Replace an existing site's DRAFT") and then enumerates the three mutually exclusive modes. An agent can distinguish this from sibling patch_fixture, create_site_from_template, update_page, and set_theme from the text alone.

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

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

Gives explicit selection conditions per mode (template_slug = owner wants a different design, fixture = replacement you composed, page_updates = only listed pages) and an exclusion rule: "never build a second site for a switch." It also states the consent prerequisite ("Do it only on the owner's yes"), which is exactly the kind of routing an agent needs.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, and the description reinforces this with an explicit 'reports and changes nothing' statement. More valuably, it discloses non-obvious behavior: contrast is measured on the rendered pages, which is why it catches light-on-light text after a colour change — context the annotations cannot convey. It stops short of noting cost/latency or result size for a full-site review.

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 front-loading is good — 'Review the draft' plus the default-focus behavior comes first — but the description is a dense ~200-word block that duplicates the parameter descriptions almost verbatim (broken links, alt text, SEO titles, form options, FAQ items appear twice). Trimming the mode enumeration to a pointer at the schema would tighten it substantially.

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 must convey what each mode yields, and it does — problems-to-fix lists, design metrics, per-node explanation, and up to 3 next steps. Read-only safety is covered and the sibling set is unaffected. It could still say roughly how much output comes back from a full-site 'health' pass, but nothing an agent needs to call it correctly is absent.

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

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

Schema coverage is 75% and the focus enum is documented in detail inside the schema, so the description largely restates it. It does add two useful inferences beyond the schema: 'health' is the default, and supplying node_id implicitly selects 'explain'. That modest added value fits the baseline-3 case where structured fields do 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 description states a specific verb (review) against a specific resource (the draft site) and then enumerates all four modes with what each returns, so an agent can distinguish 'health' from 'design', 'explain' and 'next' without opening the schema. The opening sentence is front-loaded and unambiguous about 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?

It gives explicit triggers: run after a build, a big edit, or a set_theme colour change, and it maps the 'next' mode to the 'what should I do next?' question. What's missing is routing against siblings — it never says to prefer read_rendered_page or screenshot_page for raw inspection, or get_site for structure — but the when-to-use guidance itself is clear.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotent, non-destructive), and the description adds substantial context beyond them: ~5s real-browser cost, concurrent text/title fetch at no extra wall-clock, always capturing via preview-{slug}.{rootDomain} which renders the draft or 302s to live. That routing behavior is exactly the kind of non-obvious trait annotations cannot 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?

Front-loads the core decision ('genuinely VISUAL') before the returns and latency details, and every sentence carries information. It is dense with em-dash asides and runs slightly long, but nothing is 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?

No output schema exists, yet the description explains what comes back (page text and title alongside the image) and why to read the text. Combined with latency, preview-URL semantics, and the sibling alternative, an agent has everything needed to call this 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 75% and the schema descriptions are already detailed for slug, viewport, and full_page, including the mobile-breakpoint rationale. The description's 'pass viewport' and breakpoint-collapse mention largely restate that structured content rather than adding new syntax or constraints, 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?

States a specific verb+resource ('Capture a JPEG' of a page) and immediately scopes it to genuinely visual questions, explicitly distinguishing it from read_rendered_page which is name-checked. An agent can tell these two apart without opening 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?

Gives explicit when-to-use criteria (layout, spacing, hierarchy, hero reads as designed, mobile breakpoint collapse) and an explicit when-not ('when the question is only about wording prefer read_rendered_page at ~357ms'). The alternative is named and the selecting condition is quantified with latency.

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 beyond the annotations by disclosing that it 'Writes one draft version', that changes are reversible via 'as-designed ... to put the original back', and that an empty call is a pure read. These are real behavioral facts annotations cannot convey. Missing: what happens on a list node that is not a collection list, or whether the draft must be published afterward.

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?

One long sentence with nested parentheticals that reference the tool by its own name makes it hard to parse on first read. The core verb is front-loaded, but the recursion and stacked clauses cost the reader effort that a short bulleted split would have avoided.

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 mutation tool with no output schema and no readOnly annotation, this covers the safety story (non-destructive, reversible, draft-only) and the discovery path. The main gap is that the draft/publish lifecycle and the 'library design' discovery flow (an empty call returns design ids) are only implied, not spelled out in sequence.

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?

With 75% schema coverage the schema already documents most fields, yet the description still adds value by naming the two design families (library designs, plain arrangements such as image-top/overlay) and enumerating the style dimensions (surface, corners, padding, photo shape, text alignment, hover). It does not explain what any individual style enum value visually does, so an agent must guess between 'border'/'shadow'/'filled'.

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 and resource plus scope: 'Change how every card of a collection list looks, in one call'. The two-parameter split (design swaps whole card, style adjusts it) is clearly stated. It loses a point for the circular phrase 'a library design from set_card_design (with no design)', which forces the reader to reconstruct meaning from 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?

Explicitly routes away from the tempting alternative: 'Prefer this to rewriting a card template with patch_nodes/insert_nodes ... it cannot drop a field, break the card's link or lose the way back', and gives the reason. It also defines a discovery mode ('With neither design nor style it changes nothing and returns the designs and style choices'), so an agent knows how to explore before mutating.

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?

Without the annotations an agent would be guessing, but the description still adds far more than they do: what gets stored, the paid-plan gate, propagation timing, and the instruction to relay dns_instructions and next_step verbatim. It does not address the destructiveHint=true annotation, so an agent cannot tell whether attaching replaces or conflicts with an already-attached domain; that is the remaining gap.

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 effect, then the follow-up and the plan gate in decreasing order of importance. It is a single dense paragraph running long, but nearly every clause carries actionable information; the example hostname list is the only mildly redundant part.

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 fields (dns_records, dns_instructions, next_step) and how to use them. Combined with the verification follow-up and the billing gate, an agent can complete the whole task flow from this description alone.

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, but the description adds real semantics: apex versus subdomain hostnames produce different DNS record sets (A record plus www CNAME vs a single CNAME). That is behavior the schema's regex cannot convey, though per-parameter prose is otherwise left to the schema.

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

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

States a specific verb and resource ('Attach a custom hostname ... to a Sitelas site') and then spells out the mechanics: registers with the CDN, stores it against the site, returns DNS records. It is clearly distinguishable from check_custom_domain (verification) and remove_custom_domain (teardown) in the sibling 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?

Explicit routing: after DNS propagates (5-30 min) call check_custom_domain with the domain, and on a Free-plan site the tool returns billing_gate, which the agent should mention once before offering to connect. Both the follow-up step and the when-not case (Free plan) are stated, along with where plan info comes from (list_sites/get_site).

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?

Adds substantial context beyond the destructiveHint/idempotentHint annotations: edits land in the draft, partial input is merged, contrast is auto-repaired and reported via text_recoloured, the check costs ~20s, and a preview URL is returned. It also warns to tell the owner what changed, which is the kind of consequence info annotations can't 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?

Front-loaded with the core action, then side effects, then latency and return value. Dense and largely waste-free, though the contrast-repair explanation is repeated across the opening and the second 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?

For a non-idempotent, destructive, multi-purpose mutation with no output schema, the description covers the side effects, the auto-repair behavior, the runtime cost, and the return value. Nothing an agent needs before invoking it 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 coverage is already 88%, so baseline is 3. The description still adds value by explaining the merge semantics of the colours object ('any subset; what you leave out is kept') and the relationship between preset_name and save_as, which is spread across separate schema 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 and scope ('Change the site's colours and fonts in the draft') and immediately names the additional operations it bundles (brand name/tagline, preset re-apply, save_as). It also distinguishes itself from node-level siblings by telling the agent to prefer section/button data for single-element tweaks.

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 a clear boundary case: 'For one section's surface or one button, prefer that node's own data over the theme.' That is a real alternative-selection rule. However, the brand name/tagline handling overlaps update_site_brief without saying which to prefer, and no explicit 'when not to use' for the whole tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description still adds real behavioral detail beyond them: omitted providers are kept, `null` disconnects one (partial update), changes go live on all public pages with no publish step, and preview links are excluded. It does not explicitly connect "null disconnects" to the destructiveHint flag, so not a full 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?

Dense but every sentence carries a distinct constraint (accepted input form, partial-update rule, propagation scope, authorization, sibling alternative, compliance note). The core verb+resource leads, and 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?

For a 5-parameter mutation with no output schema, the description anticipates the questions an agent would have: what counts as valid input, how omission/null behave, how fast changes take effect, where they do not apply, and the sibling it is not. Nothing material 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 coverage is 100%, which sets a baseline of 3. The description nevertheless adds cross-parameter semantics the schema lacks — omitted providers are kept and `null` disconnects — plus the guarantee that only IDs are accepted (snippets are parsed, never arbitrary script). That is meaningful value over the per-parameter schema text.

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 (Connect) and the exact resources (GA4, GTM, Meta Pixel, Plausible to their published site), and explicitly contrasts with the sibling get_analytics. An agent can distinguish this from get_analytics without opening 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?

Names the alternative (get_analytics) and the condition that routes to this tool: owners who want their numbers in external tools or to measure ads. Adds an explicit authorization constraint (use only IDs the owner gave you) and a compliance caveat for EU/UK visitors.

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 flag destructive/not-idempotent, and the description still adds real value: exactly what gets destroyed (every unpublished change), the friction of confirmation, and the outcome flags restored=false / reset=false when there is nothing to undo. The closing clause 'neither touches the other' discloses a non-obvious interaction guarantee that annotations do not 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?

Three tight sentences, front-loaded with the core definition and then the two modes, each followed by its parenthetical edge case. No filler; every clause carries either an action, a guard, or an edge-case outcome.

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-idempotent mutation with no output schema, the description covers what is destroyed, the confirm gate, the nothing-to-undo signals, and cross-mode independence. What is missing is smaller: nothing about site_id scope (whole site vs single page) is stated in text, though the 'what' schema covers that for last_publish.

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 67% and already documents both 'what' and 'confirm', so the description is duplicating some of that. It still adds meaning beyond the schema: the result flags ('restored=false when there is nothing to undo', 'reset=false when the site was never published') let the caller interpret the response, which is absent from the input 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?

'One-step undo' with the two enum modes spelled out ('last_publish' reverts the most recent publish; 'draft' discards unpublished changes) is a specific verb+resource statement that lets an agent tell the two behaviors apart. The only gap is that it never contrasts itself with the sibling 'unpublish', which also reverses a publish and could be confused with 'last_publish'.

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

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

It gives concrete selection conditions for each mode ('reverts the most recent publish' vs 'discards every unpublished change so the draft matches the live site') and an explicit precondition ('needs confirm: true, so ask first'). It stops short of naming alternatives such as unpublish, so it is clear context without explicit routing.

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 destructiveHint=true and idempotentHint=true, but the description adds genuinely new behavioral facts beyond them: visitor-facing 404 on the address, page leaves the menu, the rest of the site stays live, and drafts are retained for republishing. It doesn't discuss permission/auth requirements or how to undo (the undo sibling exists), which keeps it from 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?

Three tight sentences, each earning its place: scope, reversibility, then the guardrail on when to use it. The core scope is front-loaded and nothing is padding.

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

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

No output schema exists, and annotations carry the safety profile (destructive, idempotent, open-world). The description supplies the visitor-facing effect, reversibility, and the usage guardrail, so an agent has everything needed to call it correctly.

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

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

Schema coverage is 67% and the schema's own page_slug description is rich. The description nonetheless adds the key semantic split (page_slug = one page, omit = whole site) in its own words, reinforcing correct invocation. The locale parameter is left entirely to the schema, preventing full credit.

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+scope: 'Take the whole site offline... or with page_slug just one page.' An agent can instantly distinguish this from delete_site/delete_page because the description says drafts are kept and it can be published again. No ambiguity about what is being taken offline.

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 and when-not: only when the owner explicitly asks to take something down, and 'never to make room for another site's publish.' That exclusion is valuable routing guidance. It stops short of naming the alternative tool (e.g. delete_site vs unpublish) explicitly, so not quite 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 declare this destructive, non-idempotent, and openWorld=false, but the description adds substantial context beyond them: it explains the auto-rewrite of internal links (and that the response reports the count/node ids), cascade behavior for sub-pages, 308 redirects on publish, the reserved-route and collision guards, and that it writes a new draft version requiring publish to go live. This is unusually rich behavioral disclosure for a mutation 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-loaded with the core purpose and alternatives before the detailed rename semantics. It is long but nearly every sentence carries actionable constraint or behavioral info; the only cost is density, which slightly favors an agent reading carefully over skimming.

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 8 params, a nested metadata object, and no output schema, the description is complete: it covers every meaningful parameter behavior, the rename edge cases, and what the response reports (rewritten link count, moved sub-pages). 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 coverage is 75% and the schema itself describes cascade, rewrite_links, new_slug, sort_order, and metadata thoroughly. The description reinforces these with additional meaning, especially the hard-to-infer constraint that the home page ('/') cannot be renamed and the reserved-route restriction. That extra rule beyond the schema earns a 4 rather than a baseline 3.

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 verb (update) and resource (a page's metadata), enumerates the editable fields (slug, title, sort_order, metadata), and draws explicit boundaries against update_seo, insert_nodes/patch_nodes, and nav-link node edits. An agent can distinguish it from all relevant siblings 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?

Explicitly routes the agent: use update_seo for search title/description/share image/noindex, insert_nodes/patch_nodes for tree edits, edit nav-link nodes for nav changes. It also names the condition under which this tool is the right choice ('whenever a page's slug no longer matches what the page became') and the precondition (at least one field must be passed).

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 a mutation (destructiveHint=true), and the description adds behavior annotations cannot convey: omitted fields are preserved, `null` deletes a field, per-page writes ship as a draft version while site-wide writes go live immediately, and site-wide values act as fall-through defaults. It also warns to use only owner-supplied facts and never placeholders for `business`.

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 verb and the mode split, and nearly every clause carries operational information (publish step, null semantics, site-wide exclusivity). It is a dense single paragraph, though, and the long parenthetical field enumerations make it harder to scan than a short bulleted structure would.

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 3-parameter tool with deep nested objects and no output schema, the description covers both operating modes, live-vs-draft consequences, field support, deletion semantics, and where to read existing values. An agent has everything needed to call it correctly without further exploration.

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 layers on mode-scoping that the flat schema can only state per-field: which fields are site-wide only (business, verification), how `page_slug` accepts collection item addresses, and the merge-vs-null semantics. It adds framing value beyond the per-property 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?

States a specific verb and resource ('Set SEO metadata for a site or a specific page') and immediately distinguishes the two modes by their discriminating parameter (`page_slug`). An agent can tell this apart from siblings like `update_page` or `set_tracking_codes` 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?

Explicitly routes per-page mode to `publish` for go-live versus site-wide mode being live immediately, names `get_site` as the way to read current values, and gives the specific trigger for `business` ('use it when the owner asks to appear as a local business in search'). That is when-to-use and how-to-follow-up, not just context.

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?

Exceeds what annotations convey: merge is field-by-field with omitted fields preserved, decisions[] is left untouched, and the decision log caps at 50 with oldest dropped. That directly answers what a mutation with destructiveHint=true actually overwrites versus preserves, resolving the alarming annotation.

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 front-loaded sentences, each adding distinct information: identity/scope, merge semantics, and timing plus the decision-log path. No filler or restatement of the title.

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 non-idempotent, destructive-flagged mutation with no output schema, the description covers persistence, merge behavior, and the decision log. It doesn't hint at what the call returns or any permission requirements, which is the 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 50%, but the description compensates by mapping the brief subfields to the domain and by explaining the decision/why split (choice in decision, reason in why). Only site_id and the 500-char limits are left solely to the schema, and those are trivial.

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 (set/incrementally update), a named resource (the durable site brief) and enumerates exactly what the brief holds (vibe, category, brand voice, palette/font names, tagline, audience). This distinguishes it clearly from sibling mutations like set_theme or update_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?

"Call this once after picking a direction, then again whenever the direction shifts" gives concrete timing for invocation, and the decision/why sentence gives a second trigger. It stops short of naming alternatives (e.g., set_theme for palette changes), so no explicit when-not guidance.

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

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

Adds substantial context beyond the annotations: the 2MB storage cap, the 100,000-character inline limit, replacement semantics under the same name at a stable URL, CSV normalization into row objects, and even a summary of the return payload (url, row count, shape, fetch line). The replacement/overwrite behavior is consistent with destructiveHint=true, and the stable-URL nuance usefully qualifies the idempotentHint=false annotation.

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 and the key 'never do this' guidance, and nearly every clause carries a distinct constraint. It is a dense single paragraph, however, and the source-selection rules would be more scannable as a short list.

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 still covers the return payload, size limits, format conversion, overwrite behavior, and the asynchronous link-mode flow. Nothing material is missing for an agent to select a source and invoke this 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% and the schema descriptions already carry the mutual-exclusion rule, the CSV `as` modes, the name pattern, and the link-mode flow. The description restates the exactly-one-of rule and the size thresholds but adds no syntax or format detail beyond the schema, 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?

States a specific verb and resource (store a JSON or CSV data file) plus the concrete outcome (public URL fetchable by an embed's script), and gives example use cases (product finder, price table, store locator). This clearly separates it from upload_image and from add_content_item in the sibling list.

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

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

Explicitly rules out alternatives ('Never paste the data into the embed itself, and never hide it in an image') and gives a decision rule among the three sources: url for anything big, content up to 100,000 characters, mode:"link" for a file only the owner has.

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 destructiveHint, openWorldHint, and non-idempotency, so the safety bar is lower. The description adds real behavioral detail beyond that: image processing pipeline, the one-hour PUT URL staging flow for local agents, the ~30KB base64 cutoff, and the 10MB URL source limit. It does not state that placing via image_target may overwrite an existing image, which would be the key remaining gap given destructiveHint=true.

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 return value, then flows into source selection, placement, and the local-agent flow. It is dense with parentheticals and em-dashes, but nearly every clause carries actionable routing information rather than 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 9-parameter, nested-object mutation tool with no output schema, the description covers the return value (a URL), both source paths, the staging-workflow sequencing, and the explicit exclusion case. An agent can choose and invoke it correctly without further reading.

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 89%, so the schema already documents most parameters; the description still adds decision-level semantics, e.g. url is the 'usual source', base64 is for images you authored and is capped in size, and mode 'link' is a multi-call staging flow. The image_target placement tradeoff and the patch_nodes fallback are explained rather than repeated.

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 precise verb+resource and scope: stores an image on Sitelas's CDN with specific processing (resize, WebP, blur placeholder) and returns a URL. It explicitly distinguishes itself from siblings by naming the alternative (get_editor_link) for the case where the person has the photo on their device.

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

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

Gives explicit routing rules: use url in the normal case, base64 for small self-authored images, pass image_target to place in the same call, otherwise use patch_nodes or edit_content_item. It also names the wrong-tool case ('when the PERSON has the photo on their device, this is the wrong tool at any size') and redirects to get_editor_link with image_target.

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