PageHub

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false; the description adds real context beyond that by disclosing the on-disk side effect (creates pages/<slug>.liquid), that a slug is derived from the display name, and that the call returns a pageId. It does not say what happens on a slug collision or duplicate name, which is the main unstated behavior.

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

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

Four tight sentences with the core action and artifacts front-loaded, followed by parameter hints and the guide pointer. The telegraphic fragment style ("Guide: get_style_reference(...)") is efficient, though the seo sentence is partly 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 6-parameter creation tool with a nested seo object and no output schema, the description covers the return value (pageId), the produced file plus record, and where to look for style guidance. Missing only failure/duplicate-slug behavior to be fully 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?

Schema coverage is 100%, so the schema already documents every parameter including the nested seo object; the description only reiterates that text is HTML+Liquid and that seo.title/seo.description are settable here. That is a minor reinforcement rather than new semantics, so baseline 3 applies.

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

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

States the specific verb and resource ("Create a page") and goes further by naming both artifacts produced: pages/<slug>.liquid and its record. It also states the return value (pageId), so an agent knows exactly what this tool does that update_page or create_site do not.

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 usage context — the first page created is home, page name drives the slug, and SEO can be supplied at creation time — plus an explicit pointer to get_style_reference({topic:"pages"}) for guidance. It stops short of stating when to prefer this over update_page for an existing page.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false. The description adds non-obvious behavior beyond that: the inserted content is a copy with fresh ids, so the library source is untouched, and placement is controlled by exact anchor text or position 0. It does not spell out permission requirements or whether the page must be unpublished, which is the remaining gap for a destructive 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?

Three tight clauses, front-loaded with the action and its core semantics, then the alternative and the reference guide. No filler sentences; every clause carries information an agent needs.

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

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

For a 6-parameter destructive mutation with no output schema, the description covers placement mechanics, the copy semantics, and the main alternative path. It stops short of stating what is returned (e.g., the new block ids) or any precondition on the target page, which leaves a modest gap for a write tool with destructiveHint=true.

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 id, slug, after, before, pageId and position. The description restates the same semantics (before/after as exact text, position 0 = top, slug as a library block) without adding format, precedence (what happens if both before and after are given), or default details beyond the schema. 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 (place) and resource (library block identified by `slug`) plus the destination (a page file) and the key transformation (a copy with fresh ids). It also names the sibling tools it is not — get_block for reference, edit_site_file for custom design — so an agent can route correctly without opening a schema.

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

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

Gives an explicit alternative path: to design a section for this business, write it with edit_site_file and use get_block as reference. That is real when-not guidance. It does not explicitly say to find the `slug` via search_blocks/list_blocks in the description (that lives only in the schema), so it falls just short of full when/when-not 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?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description still adds real value by disclosing what is inspected and that results come back classified by severity, and by clarifying the target is the draft rather than the published site. It does not mention cost, timeout, or result-size characteristics of an audit run.

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

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

Two dense sentences with the subject, scope, checks, and return format front-loaded; nothing redundant or filler.

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

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

All four parameters are documented in the schema, annotations cover the safety profile, and the description states what the output contains despite no output schema. Minor gap: no indication of how large a violation report can get or whether partial results are possible.

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 enum for level, the pageId default, and the id/templateSlug exclusion are already documented in the schema. The description adds only a light framing of the draft-vs-template choice, which the schema already states more precisely.

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 ("WCAG audit of a page") and enumerates the checks performed (contrast, alt text, headings, ARIA, interactive elements), plus the return shape ("violations by severity"). It does not explicitly name the sibling audit_seo as a different-in-kind alternative, so an agent must infer the distinction from naming 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?

Usage is implied by "site's draft (or a stock template)", which tells the agent this runs against unpublished content or templates rather than a live site. However, there is no explicit when-to-use/when-not guidance, no mention of a prerequisite (e.g. site must be selected), and no routing to audit_seo for SEO concerns.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that output is a set of fixes and that the target is the draft/template rather than the live site, but says nothing about cost, limits, or what happens on a published page.

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 compact sentences, zero filler, scope stated first and the return content tacked on at the end where it belongs.

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 return shape and only offers 'Returns fixes' — no structure, no scoring scale (a 'score' is promised but never characterized). For a multi-dimension audit tool that is a meaningful gap, though the annotations cover safety.

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 already documents the id/templateSlug mutual exclusion, the page_home default, and the url-path semantics of pageId under templateSlug. The description only signals the site-vs-template mode at a high level, so baseline 3 applies since the schema does the heavy lifting.

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

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

The description gives a specific verb (audit/score) and resource (a page of the site's draft or a stock template), and enumerates the audited dimensions: meta, heading hierarchy, alt text, link text, content depth. The SEO-vs-accessibility split from audit_accessibility is inferable from the listed checks, though the sibling is never named.

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 implies the applicable scope — the site's draft, or a stock template instead of a site — but never states when to pick this over audit_accessibility or how to handle published pages. Usage is inferable rather than guided.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral detail beyond annotations: it checks both apex and www, reports free/attached/erroring status, includes required DNS records, and reinforces that nothing is changed.

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

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

The description is a single efficient sentence, front-loaded with the verb and resource, and ends with the important non-mutation guarantee. Every clause adds relevant 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 simple two-parameter read-only preflight tool with full schema coverage and rich annotations, the description provides enough context about what is checked and what kinds of results to expect. It does not explicitly explain how it relates to get_domain_status or set_domain, which keeps it short of fully complete routing guidance.

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

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description adds the useful detail that the candidate domain is checked at apex and www, but it does not explain the optional site id parameter, so baseline 3 is appropriate.

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

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

The description gives a specific verb and resource: preflight a candidate domain, covering apex + www and returning free/attached/erroring status plus required DNS records. It implicitly differentiates from sibling mutation tools by saying it changes nothing, but it does not explicitly name alternatives such as get_domain_status or set_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?

Usage is implied by the word "preflight": this is a read-only check to run before attaching or changing a domain. However, the description gives no explicit when-to-use guidance, no exclusions, and no named alternative for checking an already-attached domain.

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=true and openWorldHint=true, so safety is covered structurally. The description adds real value beyond them by naming exactly what is destroyed (both apex and www variants detached from Vercel) and the side effect of resetting redirectMode to none, though it says nothing about permissions or downstream propagation.

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, zero filler, with the primary action front-loaded and the side effects second. 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?

For a single-parameter mutation with no output schema, the description covers what is removed and what changes on the backend, which is what an agent needs to call it correctly. Return behavior and whether the change is reversible are left unstated.

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

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

Only one parameter, and schema description coverage is 100% ('Site id.'), so the schema already documents it fully. The description adds nothing about the id beyond implying it targets the active site; 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 (remove the custom domain from the active site) and the exact scope (apex and www variants, Vercel). An agent can distinguish it from set_domain, check_domain, get_domain_status and set_domain_redirect_mode without opening any schema.

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

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

The scenario is unambiguous: this is the teardown counterpart to set_domain, and 'from the active site' anchors it to the currently selected site. No explicit exclusions or named alternatives are given, so it stops short of a 5.

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

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

Annotations declare write, openWorld, idempotent, non-destructive; the description is consistent and adds real value beyond them: the collection is created or reused (explaining the idempotent hint) and a pasted secret key is stored encrypted and never shown again. That secret-handling and interaction constraint is exactly the kind of context annotations cannot convey. It stops short of describing failure modes or what a successful response contains.

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 and front-loaded: the core action and its effects come first, then input sourcing, then the secret-handling caveat. Phrasing is terse to the point of being clipped ('inputs = the keys list_apps shows'), which costs a little readability but wastes no sentences.

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

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

For a 5-parameter write tool with a nested inputs object, annotations, and no output schema, the description covers the prerequisite, side effects, idempotency, and the sensitive-input rule. Remaining gaps (behavior on invalid keys, whether name overrides the collection name) are mostly covered by the schema, so nothing critical is missing for a correct 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 100%, so the schema already documents id, app, name, inputs, and bookingUrl. The description clarifies that 'inputs' keys mirror what list_apps shows and that values in it may be pasted secrets, which adds some meaning, but it does not explain name or bookingUrl at all. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Connect an app') and goes further to name the two effects: it makes or reuses the app's collection and runs the first sync. Tying the app identifier to list_apps makes the relationship with that sibling explicit, so an agent can tell which tool to call first.

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?

Clearly establishes the prerequisite ('from list_apps') and constrains interaction behavior ('never ask for one they haven't offered, point them to the hint'). It gives clear context for when to use it, but never names the alternative for a subsequent re-sync (sync_collection) or states when not to use it.

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 a non-readonly, non-idempotent, non-destructive, open-world write. The description adds two useful behavioral facts beyond them: the plan gate and the default source of manual. It says nothing about what happens on a slug collision, whether creation is site-scoped, or what is returned, so the added context is real but thin.

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 verb phrase followed by the highest-value detail (the field-schema format), then defaults and gating. Dense and mostly waste-free, though the trailing "…" leaves the field-definition shape deliberately open rather than fully specified.

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 7-parameter tool with a nested object, no output schema, and full schema descriptions, the description covers the two things the schema cannot: the nested field-definition format and the source-type enum. Gaps remain around site scoping (the `id` parameter is only labeled "Site id") and the fact that slug uniqueness is likely enforced.

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%, but the description goes beyond it by spelling out the element shape of the `schema` array ({ key, label, type, required?, default?, help? }) and enumerating all twelve field types — details the schema itself only gestures at with "items: object". It does not add anything for `id`, `slug`, `isPublic`, or `description`, which the schema already covers.

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 ("Create a collection") and immediately explains what a collection's contents are (a field schema with typed entries), which distinguishes it from create_collection_row and list_collections in substance. It never names a sibling or explicitly contrasts with them, so differentiation is inferred rather than stated.

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

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

"Plan-gated" supplies a real precondition and "Source defaults to manual" clarifies the default path, but there is no explicit when-to-use guidance versus alternatives such as import_collection_csv (for CSV-sourced collections) or update_collection_schema for later edits. Usage is implied rather than directed.

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 readOnly=false, destructive=false, and idempotent=false, so the safety profile is partly covered. The description adds meaningful context beyond them: 'validated against the schema' and especially 'Plan-gated,' which signals a non-obvious precondition the annotations don'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?

Three tight fragments, front-loaded with the core action, and every clause carries information (validation, plan-gating). No filler, though the fragmentary style is terse enough that structure is minimal.

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-param mutation with a nested object and no output schema, the description covers the essentials and flags plan-gating, but omits what a successful create returns, how validation failures surface, and any required site/collection selection context. Minimum viable.

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 all three parameters, making the baseline 3. The description restates that `data` maps field key → value and adds the validation note, but adds little syntax or format 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?

States a specific verb (Create) and resource (one row), which distinguishes it from the bulk sibling create_collection_rows and from update_collection_row. It doesn't name the sibling explicitly, but 'one row' clearly implies singular creation, so it's clear though not fully differentiated in prose.

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

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

Usage is implied by 'Create one row' versus the plural create_collection_rows sibling, but there's no explicit when-to-use guidance, no prerequisite for selecting a site/collection first, and no routing to alternatives. Adequate but leaves inference to the agent.

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 generic write profile (readOnly=false, destructive=false, idempotent=false); the description adds non-obvious behavior the annotations can't express: all-or-nothing atomic validation, errors that name the failing rowIndex, a 500-row cap, and a plan-gated prerequisite. This is exactly the context an agent needs before committing a bulk 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?

Three telegraphic clauses, front-loaded with the operation and its limits; the sibling pointer is placed last where it belongs. 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 mutation tool whose safety profile is covered by annotations, the description supplies atomicity, limits, error shape, plan gating, and an alternative route. The only real omission is any hint of the success response, which is minor given no output schema is required to be explained.

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

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

Schema coverage is 100%, so the schema already documents slug, rows, and id; baseline would be 3. The description goes slightly beyond by clarifying that each row object is a field key → value map and by restating the 500 max on rows, which helps the agent build the payload correctly.

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 (insert rows into a collection) plus scope (up to 500, one call), and implicitly distinguishes itself from the single-row sibling create_collection_row by stating batch capacity. An agent can identify the tool from the first clause 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?

Routes the agent explicitly to import_collection_csv when the payload is a big CSV, and the 500-row ceiling implies the threshold for switching. It does not state a negative condition beyond that (e.g., use create_collection_row for a single row), but the batch-size cue covers the main routing decision.

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=false, destructiveHint=false, and idempotentHint=false, so the safety and repeat-call profile is covered. The description's real addition is the return payload (id, editor link, previewUrl), valuable since no output schema exists, but it says nothing about slug uniqueness, template validity, permission requirements, or failure modes.

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

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

Two tight sentences with zero waste: the action and its output are front-loaded, and the follow-up workflow hint comes second. Nothing is 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?

For a zero-required-parameter creation tool with no output schema, the description covers the action, the default, the returned fields, and the next step. It could be more complete by pointing at list_templates for discovering non-default template slugs or by noting that the site is unpublished until publish_site.

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 all four parameters are already documented and baseline would be 3. The description earns a bump by explaining that the default template "acme" is the blank starter, which gives semantic meaning beyond the schema's bare "Template slug (default \"acme\")".

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 ("Create a site from a template") and adds scope detail (default "acme", the blank starter) plus what is returned. It does not explicitly differentiate itself from close siblings like duplicate_site, import_site, or pull_template, so an agent must infer which creation path applies.

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?

"Then build it with the file tools" gives useful next-step routing to write_site_file/edit_site_file, so the workflow position is implied. However, there is no when-not guidance and no statement about choosing this over import_site, duplicate_site, or list_templates 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description does add real value beyond the annotations by disclosing the cascade scope ('all its rows') and irreversibility ('No undo'), but says nothing about permissions or what the response reports.

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 brief sentences, with the destructive scope front-loaded ahead of the irreversibility warning. 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?

There is no output schema, but for a destructive delete the essential facts – cascade scope and no-undo – are present. Missing detail on permissions and result reporting is minor.

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%: both 'id' and 'slug' are documented in the schema. The description mentions the collection but adds no format, scoping, or precedence guidance (e.g., whether slug or id wins), so the baseline 3 is appropriate.

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

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

States a specific verb (delete) and resource (collection), and the phrase 'and all its rows' pins down the cascade scope that separates it from delete_collection_row. It stops short of naming that sibling, so an agent must infer the contrast.

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

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

The description warns 'No undo' but never says when to use this versus delete_collection_row, update_collection_schema, or other collection tools. There is no explicit alternative routing or prerequisite (e.g., permission or site-scoping) guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that — no mention of irreversibility, permission requirements, or behavior when the rowId does not exist. With annotations doing all the work, the description contributes essentially no additional 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?

A single front-loaded sentence with no filler or repetition. It is efficient, though arguably too terse for a destructive operation.

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 single-row delete with complete schema coverage and annotations covering the safety profile, this is minimally adequate. It omits any confirmation semantics or failure behavior, but with no output schema there is no return-value burden.

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%, with each parameter (id, slug, rowId) documented in the schema itself. The description only restates that rowId selects the row, adding no format or constraint detail beyond the schema. Baseline 3 applies when the schema carries the load.

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

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

The description names a specific verb (Delete), resource (row), and scope (one row from a collection) identified by rowId. It implicitly distinguishes itself from delete_collection (whole collection) but does not name any sibling explicitly.

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?

No guidance on when to use this versus delete_collection, delete_node, or delete_page, and no prerequisites or warnings. The agent must infer usage entirely from the name.

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 covered; the description adds the non-obvious behavior that the operation is rejected under referential dependency. It does not say whether deletion is reversible or what the refusal error looks like, keeping it out of 5 territory.

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 sentence with zero filler; the scope qualifier is front-loaded and the failure condition is packed into a clause rather than a separate 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 two-parameter destructive tool with full schema coverage and annotations covering the safety profile, this is largely complete. The only missing piece an agent could want is post-deletion state (recoverable or not, cascade effects).

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% — both 'id' (site id) and 'component' (component id from list_components) are documented in the schema. The description adds no format, sourcing, or constraint detail beyond that, 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 ('delete an unused component') plus a scoping qualifier ('HTML-first sites'), which cleanly separates it from rename_component, list_components and delete_page 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?

The parenthetical 'refused while anything renders it' is an explicit precondition telling the agent when this call will fail, which is real usage guidance. It stops short of naming an alternative (e.g. detach/rewrite blocks first) or of saying how to confirm a component is unused before calling.

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=true and idempotentHint=true, but the description adds value the annotations cannot: the delete cascades to the backing file, deleting the home page promotes the next page, and the last page is blocked. Those are exactly the side effects and failure modes an agent needs before firing a destructive call.

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

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

Two short sentences with zero filler; the destructive scope is front-loaded and the two edge cases follow. Every clause carries information that changes 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?

For a destructive tool with destructiveHint declared and no output schema, the description covers scope, cascade, and the two blocked cases. Only the site-vs-page id relationship is left unaddressed, which is a minor gap against a fully documented schema.

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

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

Schema description coverage is 100%, so both `id` (site id) and `pageId` are documented in-schema, and the 3 baseline applies. The description adds nothing about whether pageId is scoped per site or global, which is the one genuine ambiguity left given the optional 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?

"Delete a page and its file" gives a specific verb plus resource and even names the cascade (the file goes too). It is clearly distinguishable from delete_site, delete_component, and delete_collection_row by resource. There's no explicit sibling callout, but the resource noun does the disambiguating work.

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

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

The description supplies one real "when not to use" condition (the last page can't be deleted) and notes the home-page special case. It does not point at alternatives such as unpublish_site or update_page for the cases where deletion is the wrong move, so guidance is implied rather than 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 already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is fully covered by structured data. The description only adds 'Requires an explicit id,' which is a restatement of the required field rather than new behavioral context such as permanence, cascade effects, or auth requirements.

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

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

Two short sentences with the action front-loaded and no wasted prose. The second sentence is mildly redundant given the schema marks id as required, keeping it just below a perfect score.

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

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

For a single-parameter, no-output-schema tool whose annotations carry the destructive and idempotent profile, the description is minimally sufficient. It omits any note on irreversibility or side effects, which would be valuable for a destructive operation.

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

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

Schema description coverage is 100%, so the single 'id' parameter is already fully documented as 'Site id to delete.' The description's 'Requires an explicit id' adds no syntax, format, or constraint detail beyond the schema, matching the 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 a specific verb and resource ('Delete a site'), which is unambiguous and distinguishable from sibling mutations like delete_page or delete_collection by the resource noun alone. It does not explicitly contrast with those siblings, but the target resource is clear.

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

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

There is no guidance on when to use this tool versus alternatives such as delete_page, unpublish_site, or duplicate_site, and no mention of prerequisites (permissions, confirmation, or irreversibility handling). Usage must be inferred entirely from the name.

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=true and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond that: it doesn't say whether deletion is permanent or recoverable, what happens if the path doesn't exist, or whether the site must be unpublished. With strong annotations this is acceptable but thin.

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 sentence with zero filler; the scope constraint and the sibling pointer are both 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?

A destructive mutation with no output schema needs to tell the agent the path convention and the role of baseVersion, and it doesn't. Annotations cover reversibility/safety, so the definition is broadly usable but leaves real gaps for error-prone invocation.

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

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

Schema coverage is only 33% – only `id` is documented ("Site id."); `path` and `baseVersion` are bare. The description says nothing about path format/relativity (site-root-relative?) or what baseVersion means for a delete (optimistic-concurrency token), which is exactly the information missing from 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?

Specific verb ("Delete") plus scoped resource ("partial, section or other non-page file") and it names the sibling it is not ("pages: delete_page"). An agent can distinguish this from delete_page/delete_site/delete_component 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?

Explicitly routes page deletions to delete_page, which is the main ambiguity risk among the delete_* siblings. It does not mention adjacent tools (read_site_file, edit_site_file, list_site_files) or any precondition such as the site needing to be selected/unpublished 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 a non-readonly, non-destructive, non-idempotent mutation; the description adds real context beyond that by listing copied fields, the excluded domain/published state, and that the copy is immediately active. It doesn't spell out that repeated calls create additional copies, but the 'becomes active' wording makes the create-new-resource effect clear.

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

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

Three compact sentences: copy scope first, exclusions second, resulting state and response third. No filler, and the most decision-relevant information is 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 output schema, the description usefully reports what the result contains (editor link, previewUrl), and it covers both included and excluded fields of the copy. It omits error/permission conditions and idempotency implications, which keeps it just short of fully 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?

Schema coverage is 100%, so id, name, title and description are already documented in the schema, which sets the baseline at 3. The description reinforces that title/description are overrides on the copied values, but says nothing about the 'name' slug or that id is the source identifier beyond what the schema 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?

Opens with a specific verb+resource ('Copy a site') and enumerates exactly what is copied (content, title, description, portal, crawlPolicy), which separates it from create_site or import_site. It stops short of naming those siblings, so the distinction is inferred from the verb rather than stated.

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

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

The negative scoping ('Domain and published state are not copied') tells the agent what this tool will not do, which is useful guidance. However, there is no explicit statement of when to duplicate versus create a site, import a site, or pull a template, and no prerequisites (e.g., ownership of the source) are given.

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

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

Beyond the annotations, the description discloses useful behavior: exact text matching, replaceAll, insertAfter/insertBefore anchors, linting on save, line-numbered errors, closest-match feedback when oldText is missing, a diff-like reply, and draft staging. The remaining gap is minor given the annotation set already covers destructive and non-idempotent behavior.

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

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

The description is compact and front-loads the core editing model. Most sentences earn their place, though the fragment 'Smallest span; keep data-edit-*' is cryptic and slightly reduces clarity.

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 file-editing tool with no output schema, the description covers the important mechanics: matching, insertion, lint errors, near-miss feedback, reply behavior, and draft staging. It is complete enough to call correctly, though sibling routing guidance 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 only 50%, so the description meaningfully compensates by explaining how oldText, replaceAll, newText, insertAfter, and insertBefore interact. It does not explain path or id semantics, but baseVersion is already documented in the schema.

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

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

The description clearly states a specific verb and resource: changing a site file by exact text. It distinguishes the exact-text editing mechanism and mentions replaceAll and insert anchor modes. It does not explicitly differentiate itself from sibling tools such as write_site_file or edit_site_files.

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

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

The description explains edit modes but gives no explicit guidance on when to choose this tool over alternatives like write_site_file or edit_site_files. There are no when-not-to-use conditions or sibling routing instructions.

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/non-idempotent/not-read-only, and the description adds genuinely new traits: all-or-nothing atomicity, lint-on-save rejection, draft staging rather than live publish, and implicit page creation for new pages files. It does not cover conflict/version failure behavior or what happens to unchanged files, so it's strong but not complete.

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 atomic-write guarantee, then the entry model, then side effects and stage semantics in four dense sentences with no filler. Phrasing is telegraphic ('as edit_site_file', 'All land or none'), which is efficient but requires the agent to look up the sibling for edit-shape details.

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

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

For a destructive batch mutation with no output schema, it covers the essentials an agent needs: atomicity, lint gate, draft staging, side-effect page creation, and the two entry modes. Return values aren't documented, but no output schema exists and the description's core behavioral risks are all disclosed.

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 50% schema coverage, the description meaningfully compensates by explaining the entry model: path plus `edits` mirroring edit_site_file, or `text` for whole-file creation, plus the page-creation consequence for pages paths. It says nothing about `id`, `baseVersion`, `seo`, or `name`, though those carry 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?

States a specific verb and resource with scope: batch edit of several site files as ONE atomic write. It explicitly contrasts its per-entry modes (edits 'as edit_site_file', or `text` to create) and its implicit side effect (a new pages/<slug>.liquid also creates its page), which distinguishes it cleanly from edit_site_file and write_site_file.

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?

Conveys when to prefer this over the singular sibling: multiple files that must move together, and the page-plus-nav-link scenario folded into one call. It stops short of stating explicit exclusions (e.g. 'use edit_site_file for a single file', 'use write_site_file for a full rewrite'), leaving the agent to infer single-vs-batch 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 cover read-only, idempotent, non-destructive, and closed-world behavior, so the description is free to add real value — it discloses the search scope (all sets), the ranked return shape, and a practical coverage limitation about brand logos in Tabler. It does not mention result count/pagination beyond the schema's limit default, but the coverage caveat is genuinely useful context an agent couldn't infer.

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

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

Two dense sentences, front-loaded with the action and scope, with the caveat last. The embedded template snippet is slightly noisy but earns its place by showing the exact reference format the agent will receive.

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 describing the return as ranked refs in a concrete format, and all four parameters are covered by the schema. What remains thin is guidance on result selection (ranking criteria, how many sets are searched), which keeps it from a 5.

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

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

Schema description coverage is 100%, so all four parameters are already documented with examples and an enum, giving a baseline of 3. The description's example ref 'tb/TbPhone' clarifies the set/name output format but adds little about the parameters themselves (q, set, kind, limit) beyond what the schema 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?

The description states a specific verb (search) and resource (every icon set) and even describes the return value as ranked refs. It is clearly distinguishable from siblings like find_image and find_video by resource type, though it never names them explicitly.

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 rather than stated: the brand caveat ('Tabler lacks many brand logos; brands come from fa / si') steers the agent toward the right set/kind but never says when to choose find_icon over find_image or when to fall back to another tool. There are no explicit exclusions or alternative 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the description's job is to add context, and it does: the source precedence ('local bank, then Unsplash/Pexels') tells the agent that the local curated bank is tried first and that external providers are a fallback, and 'verified, ready-to-use URLs' signals results are hotlink-ready with no download step. It does not disclose failure behavior or attribution requirements, which keeps it below 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?

A single front-loaded sentence with no filler; every clause carries information. It is docked slightly because 'local bank' is an undefined internal term that leaves the reader guessing what that source is.

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?

Five optional params with full schema coverage and no output schema mean the description should at least sketch the return shape, and it does only minimally ('verified, ready-to-use URLs'). Missing are result shape/attribution obligations for Unsplash and Pexels, behavior when nothing matches, and any hint about how count interacts with the local bank fallback.

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 enum and default semantics for q, count, category, provider and orientation are already fully documented. The description adds only one nuance beyond the schema — that a local bank is consulted before the selectable Unsplash/Pexels providers — which is useful but doesn't elaborate on any individual parameter.

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 ('Stock photos') plus a quality claim ('verified, ready-to-use URLs'), which cleanly separates it from find_icon and find_video by resource type. It never names those siblings, so the differentiation is implicit rather than explicit.

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

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

The sentence describes what the tool returns, not when to reach for it. There is no guidance on when to prefer find_image over find_video/find_icon, no prerequisite or preconditions, and no note about what to do when results are empty or the query is too vague.

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 the tool as read-only, idempotent, open-world, and non-destructive. The description adds useful behavioral context about the provider and return format (direct MP4 URLs), but it does not mention licensing, attribution, rate limits, or any limitation on results.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently communicates resource, return format, provider, and intended usage.

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 annotations that cover safety and external-world behavior, plus complete schema descriptions and no output schema, the description provides enough context to call the tool correctly. It states the return format as direct MP4 URLs, though it could note whether results include metadata or attribution requirements.

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 input schema already documents all six parameters including query, count, provider, duration bounds, and orientation. The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states the resource (stock videos), the concrete return value (direct MP4 URLs), the provider (Pexels), and the intended use (<video> tags). It implicitly distinguishes from find_image by being about videos, but does not explicitly name that sibling or any other alternative.

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

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

The phrase 'for <video> tags' gives an implied use case, so the agent can infer this is for obtaining stock video assets for HTML video elements. However, it does not explicitly say when to use this versus find_image or other resources, nor does it state exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds real context beyond them by disclosing what the return value consists of (base class string plus responsive modifier class names) and that it is intentionally partial — 'a starting point; extra classes can be appended.'

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, zero padding. The output artifact is front-loaded before the caveat about extensibility, which is the right ordering for an agent scanning for what it gets back.

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 eight optional parameters, a 100% documented schema, and no output schema, the description should describe the return shape — and it does, naming both the base string and the modifier class names. The only meaningful omission is the relationship to validate_button_classes, which would complete the workflow picture.

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 all eight parameters with allowed values and defaults. The description references only the 'intent' trio (variant, shape, size) and the responsive modifiers, adding little beyond what the schema provides — the baseline 3 applies.

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

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

The description names the concrete artifact produced (a canonical DaisyUI 'btn' class string plus responsive CTA modifier names) and the inputs that drive it (variant, shape, size). That is specific enough to distinguish it from mutation-oriented siblings, though it never names the closely related validate_button_classes tool.

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

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

Usage is implied rather than stated: it is a class-string builder for button markup and can serve as a starting point with extra classes appended. There is no explicit when-to-use or when-not guidance, and no routing to or from validate_button_classes, which is the most likely confusion point.

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 readOnly, idempotent and non-destructive, so the bar is lower; the description adds real value by disclosing that the call 'Counts as a use', a metered/quota consequence not visible in structured fields. It also implies the return payload is Liquid source. No mention of failure behavior for unknown slugs.

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 front-loaded sentence plus a short usage caveat; every clause carries information (resource, key parameter, purpose, exclusion, billing implication). 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 helpfully names what comes back (Liquid code) and what it is for. It does not address pagination, error cases, or whether site scoping via id changes resolution, which are the remaining gaps for a read tool of this kind.

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

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

Schema description coverage is 100%, so both parameters (id, slug) are already documented in the schema. The description only echoes that lookup is by slug and adds no format, scoping, or precedence guidance beyond it — baseline 3 applies.

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

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

States a specific verb and resource: retrieves a library block's Liquid source by slug. It also disambiguates from template-application siblings by saying it is 'a reference for writing your own section, not a default to place', which immediately separates it from apply_kit_block-style 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?

Tells the agent the intended use — inspect an existing block as a reference when authoring your own section — and warns against treating the result as something to drop in. It stops short of naming the alternative sibling to use for actual placement, leaving that inference to the agent.

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 a read-only, idempotent, closed-world read, so the safety profile is covered. The description adds real domain context — that some dates exist upstream of the rental tool (pushId) and some are owner-closed (claimId) — but says nothing about pagination, empty windows, or what the response shape looks like, and there is no output schema to lean on.

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?

It is a single sentence with no filler, which is good, but the compression is excessive: the parenthetical claimId/pushId clauses are cryptic to a reader who has not seen the response. Density is traded against comprehension.

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 read tool with four required parameters and no output schema, the description should carry the return-value burden. It gestures at the important fields (claimId, pushId) and the window limit, but never explains the structure of returned dates per home, so an agent cannot predict the response.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the YYYY-MM-DD format and the 62-day bound. The description only obliquely implies slug identifies a collection ('a collection's homes') and adds no format or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

The description names a concrete resource — booked and closed dates for a collection's homes — and distinguishes data provenance types (owner-closed dates carrying claimId vs. not-yet-pushed dates carrying pushId). It never states a verb and never names calendar siblings such as set_dates or share_calendar_link, so it stops short of a 5.

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

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

There is no when-to-use guidance and no routing to alternatives; an agent looking to change availability must infer on its own that set_dates (not this tool) is the mutation counterpart. The only implied context is the 62-day span limit.

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 profile is covered. The description adds genuinely new behavioral context: webhook-feed collections additionally expose the ingest URL and POST-signing instructions, while the secret is never printed — an important disclosure about output sensitivity.

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, zero filler, with the core read purpose front-loaded and the webhook caveat as a secondary clause. Every sentence carries 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?

With no output schema, the description usefully previews the returned fields and the conditional webhook payload. It does not cover lookup failure behavior (what happens on an unknown slug) or confirm site scoping, which a read-by-slug tool would benefit from.

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

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

Schema coverage is 100%, with both id and slug documented in-schema, so the baseline is 3. The description says 'one collection' but does not clarify slug-vs-id selection or that only slug is required, adding nothing 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 ('Read one collection's definition') and enumerates what comes back (schema fields, source, isPublic). A single-collection read is clearly distinguished from list_collections and update_collection_schema in the sibling set.

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

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

The 'one collection' framing implies this is the single-item read rather than the list, but no sibling is named and no condition (e.g., 'after list_collections to inspect a schema') is given. Usage is inferable but never stated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description still adds value by disclosing that the read returns live external state (apex/www Vercel state, exact DNS records), implying a network-dependent, open-world response, and that the `check` mode is non-mutating.

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 resource and the returned fields, then the one notable mode. Nothing is wasted or repeated from 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?

With no output schema, the description's enumeration of returned data (redirect mode, apex/www state, DNS records) is what makes the return value legible, and the `check` mode is explained. What's missing is disambiguation from the domain-related siblings, which matters given how many exist.

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 both `id` and `check` are already documented, and the description's note that `check` preflights 'without changes' mostly restates the schema's 'Candidate domain to preflight.' It adds a small amount of meaning but the schema carries the load.

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 (read) and resource (custom domain) and enumerates exactly what is returned: redirect mode, apex/www Vercel state, and DNS records. It stops short of naming the sibling tools (check_domain, set_domain, clear_domain) that an agent would otherwise confuse it with.

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

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

The second sentence gives a clear condition for the `check` parameter (preflighting a different domain without changes), which is a real usage hint. But there is no guidance on when to call this versus check_domain, set_domain, or clear_domain, and no stated prerequisites such as a selected site id.

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/closed-world, so the description's job is to add meaning, and it does: it discloses that warnings, redirect origins, and page-limit omissions appear in the result, and that the 'ready' state carries the new site id, editor link and previewUrl. It omits the status lifecycle (what states exist, which are terminal), which is the one behavioral 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?

Two sentences, no filler. The field inventory is front-loaded and the 'when ready' enrichment is correctly placed second as the payoff case. Every clause maps to something an agent would actually act on.

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 legitimately carries the return-value burden, and it does so well: counts, warnings, redirects, omissions with next step, and the ready-state payload. For a read-only status tool with full annotation coverage this is close to complete; only the status enumeration 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?

Single parameter at 100% schema coverage, with the schema itself saying 'From import_site.' The description corroborates the origin by naming the import_site run but adds no format, length, or lifecycle detail beyond what the schema field already states. 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?

Names the resource precisely ('Progress of an import_site run') and enumerates what that progress contains: status, page and media counts, warnings, redirects, omitted pages. That ties it clearly to the import_site sibling rather than any list/get tool. The verb itself is only implied ('Progress of'), which keeps it from a full 5.

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

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

The reference to 'an import_site run' and the 'next step to bring them in' implies this is polled after import_site to close the loop, but there is no explicit when-to-use statement, no polling cadence, and no guidance on what to do with a non-ready status. Usage is inferable rather than stated.

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 open-world, so the safety profile is covered. Because there is no output schema, the description carries the return-payload burden and does so by naming the concrete contents (items, shipping, cancellation terms, balance, deposit hold, signed agreement, buyer answers), which tells the agent to expect commercially sensitive and PII-bearing data and to size its response handling accordingly.

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 compact sentence with no filler, and the highest-value information (that this returns the full record, not a summary) is front-loaded. It is a fragment rather than a sentence, which costs a little clarity but wastes nothing.

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 two-parameter read tool with full annotations and no output schema, the field enumeration covers most of what an agent needs to know about the response. What remains missing is the relational context: when to prefer this over list_orders or update_order, and any notion of access limits on the sensitive fields it promises to return.

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

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

Schema description coverage is 100%, so both parameters (site id and orderId) are already documented, including the cross-reference to list_orders. The description adds nothing about parameters, so the baseline 3 applies; the schema does the work, not the prose.

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 is a noun fragment naming the resource ('One order in full') and enumerating its contents, but never states the verb or scope explicitly. The title and the enumeration make retrieval of a single order inferable, and 'one' contrasts implicitly with the sibling list_orders, yet the differentiation is left to inference rather than stated.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative. An agent must infer from the name and from the list_orders sibling that this is the single-record follow-up to a listing call; the only routing hint ('From list_orders') lives in the schema, not the description.

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 the safety profile is clear. The description adds little behavioral context beyond saying it fetches the current configuration; it does not clarify whether a default site is used or what the returned configuration contains.

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 front-loaded sentence with no wasted words. The key action and scope appear immediately.

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

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

For a simple read-only tool with rich annotations and fully documented schema, the description is largely sufficient. The only minor gaps are the optional 'id' behavior and a brief indication of what 'portal configuration' includes.

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

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

Schema description coverage is 100%, and the single 'id' parameter is documented as 'Site id.' The description reinforces that the portal belongs to a site but does not clarify that 'id' is optional in the schema or what happens if it is omitted.

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 gives a specific verb and resource: fetch the current portal configuration, scoped to a site. It distinguishes itself from set_portal and remove_portal by the read verb, though it does not explicitly name those 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?

Usage is implied by the read-only fetch phrasing and the existence of set_portal/remove_portal siblings, but the description does not state when to use this versus those alternatives or mention prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description still adds genuinely new behavioral context — that AI credit status is included and that no credits causes the visitor-facing bubble to be hidden — which explains a state an agent would otherwise misread as a configuration bug. It stops short of covering behavior when chat is unconfigured.

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 front-loaded sentence with no filler; the field enumeration reads as a compact manifest of the return payload, which is doing real work rather than padding. Every clause maps to something the caller gets back.

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 shoulders the burden of describing the return payload, and it does so item by item while also flagging the credits/bubble dependency. It does not cover the empty or unconfigured case, which is the main remaining gap for a getter.

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?

Only one parameter exists and the schema documents it fully ('Site id.'), so the 100% coverage baseline of 3 applies. The description refers to 'the site's' settings but adds no detail on how a site is identified or what happens when id is omitted (it is not required).

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 (read) and resource (site chat bot settings), then enumerates exactly which settings are returned: on/off, assistant name, greeting, owner instructions, lead capture fields, lead destination, and AI credit status. That enumeration makes it unmistakable against the sibling mutator set_site_chat and against unrelated getters like get_site_email.

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

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

The read-vs-write distinction from set_site_chat is implied by the verb 'Read' and the tool name pairing, but the description never says when to call this versus set_site_chat or other site getters, nor does it state prerequisites such as a required site id or selection state. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds substantial behavioral context about the returned email: it lists the fields (subject, preheader, Liquid source, objects, parts), specifies allowed HTML blocks (div, p, h1-h3, a, img with Tailwind), and forbids forms, buttons, video, and data-* attributes.

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 and jargon-heavy, packed into three sentences with no clear front-loading of the core action. The opening fragment 'One site email:' is not a proper lead, and details about Liquid syntax and block restrictions dominate, though the length is not excessive.

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

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

Given a simple getter with two parameters, full schema coverage, and no output schema, the description provides rich context about the email's content structure, allowed elements, and restrictions. It does not explicitly state the return is a single email object, but enough detail is given for an agent to understand what will be retrieved.

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 100% schema coverage, the baseline is 3, but the description adds meaningful semantics for the `kind` parameter by explaining that it maps to a Liquid file path (emails/<kind>.liquid) with a default fallback. It doesn't clarify the `id` parameter beyond the schema's 'Site id.', but the extra detail on `kind` justifies a 4.

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

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

The description opens with 'One site email:' followed by a list of components, but never states the action (e.g., 'Retrieve'). It implies the tool returns an email template, but the missing verb makes the purpose vague and requires the tool name to disambiguate.

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?

No guidance is given on when to use this tool instead of siblings like list_site_emails or preview_site_email. The description focuses entirely on the email's internal structure and content restrictions, not on selection criteria or prerequisites.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful content-scope context about what each mode returns, but says nothing about response size, format, or whether guides are static vs. site-specific.

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 default no-topic behavior is correctly front-loaded, but the long enumeration of eighteen self-descriptive topic names (domains, blocks, editing, theme, pages, site) largely restates the enum without adding meaning, inflating the sentence considerably.

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

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

With one optional enum parameter, full schema coverage, and annotations covering the safety profile, the description provides everything needed to invoke the tool correctly. The absence of an output schema means return values could have been described, but the topic enumeration implicitly covers that.

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 enum already lists all 26 values, so the baseline is 3. The description earns more by explaining what the liquid topics actually cover (files, tags, filters, runtime data-* attributes, forms, dates) and by decomposing the liquid-<part> suffix pattern, which the enum names alone do not convey.

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

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

The description states the resource clearly as a 'styling and authoring reference' and enumerates what content is returned for each topic, so an agent knows this is a documentation lookup rather than a mutation. It does not name a sibling it is distinct from (e.g. set_theme, suggest_palettes), but the purpose is unambiguous on its own.

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 covers the two invocation modes: no `topic` returns the core reference (palette variables, styleGuide tokens, spatial scale, class rules, section skeleton), and passing `topic` returns a focused guide. There is no guidance on when to prefer this over related tools like set_theme or suggest_palettes, which keeps it below 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?

Adds substantial context beyond the annotations: replace deletes existing rows first, upsert matches on an externalId/id column, header/field matching rules, an ~8MB size cap, and that the operation is plan-gated. These disclosures (destructive replace semantics, cap, entitlement) go well past 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?

A single dense paragraph, front-loaded with the input-source rule and mode behavior. Every clause carries information, though the semicolon-packed style is slightly heavy.

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-param mutation tool with no output schema and full annotation coverage, the description covers inputs, modes, limits, and entitlement. It omits what the call returns (e.g. imported-row counts) and pagination/status behavior, which is a minor gap.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by explaining mode behaviors (append default, replace deletes first, upsert keyed by externalId/id), header-key matching with unmatched ignored, and the 8MB cap — genuine meaning beyond the field 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 (Import) and resource (rows into a collection from CSV/TSV/XLSX), and is clearly distinguishable from siblings like create_collection_rows or import_site. An agent immediately knows this bulk-imports tabular data.

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

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

Gives a clear selection rule between the two input sources ('exactly one of csv | mediaId') and explains mode semantics. It doesn't explicitly route to alternative sibling tools (e.g. single-row creation), but the when-to-use 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?

Annotations already cover the safety profile (readOnly=false, destructive=false, openWorld=true, idempotent=false); the description adds what the annotations cannot: that the result is a draft site, the upload-then-import sequencing, and that an importId is returned for get_import_status. It omits auth/plan prerequisites other than the indirect 'a plan's page limit' mention.

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 purpose and then densely enumerates each input mode; almost no wasted words. It is slightly over-compressed — the semicolon-chained clauses take effort to parse and some qualifiers ('local server only') are easy to miss.

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 six-parameter, all-optional tool with no output schema, the description covers every mode of invocation, the inline size cap, the page-limit/upgrade path, and what is returned. An agent has enough to choose the right parameter and chain the calls to get_import_status.

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

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

Schema coverage is 100%, so the schema baseline is 3; the description exceeds it by explaining the relational semantics the schema can't express — that size returns an uploadKey, that uploadKey must follow a successful PUT, that restOf targets an existing importId, and that filePath is local-server only.

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: 'Turn a static HTML site (pages, CSS, JS, images) into a NEW editable PageHub site draft.' The asset types and the 'NEW draft' outcome distinguish it from create_site and edit_site_file without needing to name them.

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

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

It spells out the multi-step workflow per parameter: size returns an upload URL and uploadKey, uploadKey after the PUT starts the import, files sends text inline (≤3MB), restOf reuses an importId after an upgrade. This is strong conditional guidance, though it never states when to prefer this over create_site or when not to use it.

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 it is a non-read-only, non-destructive, open-world write; the description adds genuinely new behavioral context on top: the owner-only authorization requirement and that re-inviting an existing address merely refreshes the invite link rather than erroring. It still does not say whether an email is dispatched or what happens to the previous link's validity window.

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 with zero filler; the operation, the role options and the re-invite caveat are all front-loaded where an agent will see them first.

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 three-parameter mutation with full annotation coverage and no output schema, the description covers operation, authorization, defaults and the re-invite edge case. Minor gaps remain around notification behavior and the resulting invite state, but nothing blocks a correct 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 100%, so the schema already documents id, role (with enum) and email. The description's role list and default duplicate the enum/default already encoded in the schema, adding no syntax or format detail beyond it.

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 ('Invite someone to a site by email') plus the full role set, which makes it easy to separate from revoke_site_invite and list_site_members. It never names an alternative tool explicitly, so it stops short of the top-bar sibling 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?

'Owner-only' gives the permission prerequisite for calling it, and '(default)' tells the agent what happens when role is omitted. It does not state when *not* to use it (e.g. use revoke_site_invite to undo) or what happens if the person is already a member.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real value beyond that by disclosing the return payload: required secret keys per app, plan entitlement, current connection state with last sync, and calendar feedId. No output schema exists, so this return-shape disclosure is the only source of that information.

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?

It is a single sentence with no padding, but it is front-loaded with brand-name enumeration (Hospitable, Hostaway, Guesty, Airbnb, Vrbo...) rather than the core action. The most decision-relevant information — plan availability, connection status, feedId — is buried at the end.

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 one-parameter read-only list tool, the description covers the important unknown (what the rows contain) in useful detail, which compensates for the absent output schema. The remaining gap is that the 'id' parameter's site scoping and the list/array return nature are left implicit.

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

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

Schema coverage is 100% with a single required 'id' (documented as 'Site id.'), so the schema carries the burden. The description adds nothing about what the id scopes — it never says the listing is per-site, which is the one piece of meaning the schema does not convey.

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

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

The description enumerates what kinds of apps exist (rental tools, calendar links, feeds/shops, Airtable) and what the response reveals, so an agent can infer this is a catalog of available integrations. But it never states a verb or object directly — 'Apps that fill a collection' is a fragment, not a statement that the tool lists available apps for a site. It is distinguishable from connect_app/set_integrations by its inventory framing, but only by inference.

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

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

There is no explicit when-to-use guidance and no named alternative. The mention of 'what each needs (secret keys marked), whether the plan has it' hints at a pre-connection discovery step, but the agent must guess that this is the tool to call before connect_app or set_integrations.

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 description's job is to add context — and it does: the ~200 item cap, category grouping, and the returned field set. It does not discuss whether results are cached or how the cap is enforced, 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?

Two compact sentences with zero filler, and the scoping/alternative information is front-loaded ahead of the filter note. Nothing is repeated needlessly.

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

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

For a zero-required-parameter filter tool with full annotation coverage and no output schema, the description is nearly sufficient — it names the returned fields and the result cap. Minor gap: it doesn't address how `id` (site id) interacts with the read, which the schema alone carries.

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

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

Schema description coverage is 100%, so the baseline is 3. The line about `categories` / `styles` arrays OR-matching largely restates the schema's own "OR-filter by several" descriptions, adding emphasis rather than new semantics; the singular-vs-plural merge behavior is also already documented in the schema.

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

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

States a specific verb and resource (list library blocks), the scope (~200 items, grouped by category), and the fields returned (slug, name, tags). It also names the sibling it differs from, search_blocks, so an agent can distinguish the two 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?

"A broad menu; search_blocks ranks and filters" gives an explicit alternative plus the condition that selects it. It stops short of an explicit when-not statement (e.g., avoid when you already know the target block), but the routing signal 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. With no output schema, the description earns real credit by disclosing the pagination contract and the four response keys (rows, nextCursor, hasMore, totalCount), which the agent could not otherwise know.

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 front-loaded fragment with zero filler; every token (the verb and the four response keys) carries information. It leans toward under-specification rather than verbosity, 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?

Adequate for a 4-parameter read tool with full schema coverage and rich annotations, and the return-shape disclosure compensates for the missing output schema. It still omits the pagination loop semantics (iterate while hasMore, feed nextCursor back) and any note on ordering or empty results.

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

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

Schema description coverage is 100% — slug, id, limit (default 50, max 200) and cursor ("nextCursor from the previous page") are all documented in the schema. The description adds nothing beyond that, so this sits at the 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 ("page through") and resource ("a collection's rows"), which separates it from list_collections (collections, not rows) and from create_collection_rows / update_collection_row (writes). It never names a sibling explicitly, so differentiation is inferential rather than stated.

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

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

Usage is only implied: "page through" plus the mention of nextCursor/hasMore signals an iterative read, but there is no statement of when to prefer this over get_collection or the row-creation siblings, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful return-shape context by naming the fields returned, though it does not mention pagination, limits, or auth requirements.

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 efficiently structured sentence with the resource and returned fields front-loaded. There is no filler or repetition.

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

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

For a simple read-only list tool, annotations cover the safety profile, schema covers the single parameter, and the description covers the returned fields. No output schema is present, but the description sufficiently explains what is returned.

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?

There is one optional parameter, and schema description coverage is 100%, with the schema already saying 'Site id.' The description only implies site scoping and adds no extra syntax or format meaning beyond the schema.

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

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

States a specific verb and resource: 'List the site's collections'. It enumerates the returned fields (id, name, slug, row/field counts, public flag), which clearly distinguishes it from get_collection and list_collection_rows.

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

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

Usage is implied by 'List' and by the site-scoped collections resource, but there is no explicit when/when-not guidance. It also does not name alternatives such as get_collection for a single collection or list_collection_rows for rows.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful conceptual context about partials and render locations, but says nothing about pagination, auth, or the shape of results beyond render locations.

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

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

The description is a single front-loaded fragment with no wasted words. It is efficient for a simple list tool, though its terseness contributes to the missing action verb and usage context.

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

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

For a simple read-only list tool with rich annotations and a simple schema, the description is minimally adequate. However, with no output schema, it could do more to explain what the returned 'where each renders' data looks like and whether a site id is needed to scope 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?

The single 'id' parameter is fully described in the schema as 'Site id.', so schema coverage is 100%. The description adds no parameter-specific meaning, which is acceptable under high schema coverage but not above baseline.

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

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

The description identifies the resource as reusable components (partials) and adds that it shows where each renders, which goes beyond the name. However, it never states the verb 'list' and reads as a fragment, leaving the action implied rather than explicit.

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

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

There is no guidance on when to use this versus list_pages, list_site_files, or other list tools, and no prerequisites or site-context requirements are mentioned. The 'HTML-first sites' phrase hints at a domain constraint but does not route the agent to 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety and idempotency are covered. The description adds useful output context, notably the '★ = served' legend for interpreting versions, but says nothing about pagination, limits, or empty-result behavior.

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

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

One front-loaded sentence with no filler, compactly conveying scope and returned fields. The '★ = served' legend is terse but functional, slightly hurting readability without wasting 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?

With no output schema, the description carries the return-value burden and does so by naming link, versions, download count and plan allowance. Combined with annotations covering the safety profile, this is nearly complete, though pagination and ordering 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 100%, so the single 'id' parameter is already fully documented in the schema. The description implies a site scope but adds no syntax, format, or defaulting detail beyond what the schema provides; baseline 3 is appropriate.

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

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

The description identifies a specific resource ('Site's hosted downloads') and enumerates the fields it returns, which cleanly separates it from siblings like list_pages or list_collections. It lacks an explicit verb ('lists') and depends on the title for the action, but the intent 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?

There is no statement of when to use this tool, what prerequisites exist (e.g., a selected site), or when to prefer it over related tools such as set_download or remove_download. The agent must infer usage entirely from the name.

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 read-only/idempotent annotations, the description discloses useful behavior: results are newest first, reading does not mark items read, webhook delivery states are included, and submissionId returns a richer single record with arrival context and notes. These details go well beyond what the annotations and schema provide.

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

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

The description is compact and front-loaded: it leads with the resource and ordering, then explains the single-record mode, filters, and the read side effect. The field list and webhook-status detail are dense but directly useful.

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 key return shape and ordering, plus the special single-submission behavior and read side effect. Pagination details are left to the schema's cursor/limit fields, which is appropriate.

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 meaning by grouping the filters, restating the open default, and explaining that submissionId switches to a full single-submission view. It does not explain limit/cursor/id, but the schema already documents those adequately.

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 resource — the site's form inbox of visitor answers — and specifies ordering, returned fields, and the single-submission mode. It is clearly distinguishable from sibling tools such as list_form_webhooks, even though it mentions webhook delivery status as part of each 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 explains the main usage modes: list with optional state/formName/q filters, defaulting to open, or fetch one full submission via submissionId. It also notes that reading does not mark submissions read. It does not explicitly name alternatives or when not to use it, but the operational 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral facts: results are scoped to the PUBLISHED site (unpublished tags don't appear) and access is restricted to owners. It doesn't describe ordering or pagination, but with no output schema 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?

It is a single compact passage with no filler, and the core definition is front-loaded. It is somewhat overloaded, packing three claims plus a parenthetical example into one sentence, which taxes readability slightly, but every clause carries 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?

With no output schema, the description takes on the burden of describing results and does so: the endpoint URLs, which forms use each, and whether each has a secret. Combined with the owner-only rule and the publish dependency, an agent has enough to call it correctly and interpret the response.

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

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

Schema coverage is 100% for the single `id` parameter ('Site id.'), so the baseline is 3. The description implies the site scope ('the forms on the PUBLISHED site') but does not clarify that `id` is optional or which site is used when omitted — the one bit of added meaning it could have supplied.

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 clear verb+resource ('the webhook URLs the forms on the PUBLISHED site post to') and enumerates the returned fields (forms using each, signing-secret status). It distinguishes itself from set_form_webhook_secret by noting it returns the `endpoint` key that setter consumes. It stops short of explicitly naming a sibling it replaces, but no direct list-alternative exists.

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 a concrete use context: inspect webhooks that go live after publish_site, and obtain the `endpoint` value before calling set_form_webhook_secret — an explicit chaining hint. It adds an eligibility rule ('Owners only'). It does not state when-not to use it, but the tool space is narrow.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes the pagination trait ('paged') and the returned fields, but says nothing about authorisation, scoping to a site, page size, or how the cursor behaves beyond the schema's own wording.

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 compact clauses, front-loaded with what the tool returns followed by the filtering capability — zero padding. It is slightly too telegraphic, dropping the leading verb and an article, which costs a little readability without bloating the text.

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 five optional parameters, no required fields and no output schema, the description carries more burden than it discharges: it gives a partial return-value summary and mentions paging, but never resolves which site is being listed when id is omitted, nor how results are ordered. Adequate for a simple list endpoint, but the ambiguity against list_site_members is unresolved.

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%, which sets the baseline at 3. The description names three of the five parameters (plan, status, q) but adds no semantics beyond the schema, and the two it omits (id, cursor) are only obliquely hinted at by 'paged'. The enum for status is undocumented in both places.

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 the resource and its payload clearly ('Site customers with their plans, status and expiry'), which tells an agent exactly what comes back. However it omits an explicit verb and, critically, does not differentiate itself from the near-duplicate sibling list_site_members, leaving the agent to guess which of the two list tools is intended.

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?

'Filter by plan, status, q; paged' implies how to narrow results, which is a form of usage guidance. But there is no when-to-use vs when-not, no mention of the alternatives (list_site_members, list_membership_plans), and no prerequisite such as needing a site id or selecting a site 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 readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds only the returned field list, with no note on pagination, ordering, auth scope, or whether an unset site id falls back to a selected 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?

A single compact fragment with zero filler, front-loading the resource before the returned fields. It is arguably clipped to the point of being a noun phrase rather than a sentence, 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 simple read-only list tool with annotations covering safety this is nearly sufficient, and the absent output schema is partially compensated by the field enumeration. However, with id optional (0 required parameters) the description never explains which site is used by default, a meaningful gap for correct invocation.

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

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

Schema description coverage is 100% (the single 'id' parameter is documented as 'Site id.'), so the schema carries parameter meaning and baseline 3 applies. The description adds no format or defaulting detail for the optional 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?

The description names the resource (site membership plans) and enumerates the returned attributes (slug, prices, access length, flags), so the agent knows exactly what this call yields. It does not explicitly contrast with set_membership_plan or other plan-related siblings, but the list-vs-set distinction is carried by the name.

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

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

There is no statement of when to call this versus alternatives such as list_site_members or set_membership_plan, and no prerequisite or context guidance. The agent must infer usage purely from the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds real context beyond them: results are ordered newest first and are drawn from the site's own Stripe account. It omits pagination behavior even though a cursor parameter exists.

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?

It is a single compact line with no filler, which is good, but it is a fragment with a colon-led noun list whose status is ambiguous — an agent cannot tell whether 'buyer, paid, refunds...' are returned fields, filters, or order types. The ordering fact is front-loaded well; the trailing list is not self-explanatory.

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 conveying return shape, and its field list gestures at that only cryptically. Pagination via the cursor parameter and the effect of the email filter are left entirely unexplained, which leaves gaps for a list tool that may span many pages.

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 id, email and cursor parameters are already documented in the schema, and the description adds nothing about them. The trailing field list (buyer, paid, refunds, booking, balance, deposit hold, agreement, shipping) appears to describe returned record contents rather than input parameters, so it does not deepen parameter meaning.

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

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

The description names the resource (orders and bookings), the scope (a given site, from its own Stripe account) and the ordering (newest first), which is enough to distinguish it from the singular get_order and update_order siblings. It is written as a sentence fragment rather than a verb-led statement, and it never names the sibling it differs from.

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

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

There is no when-to-use guidance: nothing says to prefer this over get_order for a single record, nor when to apply the email filter versus listing everything. The only usable routing cue is the implicit list-vs-get naming convention.

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 the safety profile is covered. The description adds real value beyond that by disclosing the response shape field-by-field (necessary since there is no output schema) and by revealing that pageId switches the tool from a list into a single-page settings read — a behavioral nuance the annotations do not capture.

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

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

Two dense sentences, front-loaded with the list behavior and its return fields, then the alternate mode. 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?

With no output schema, the description correctly carries the return-value burden by naming the fields returned in each mode. A minor gap remains: it does not state that both parameters are optional or what happens when id is omitted (default/selected site), which matters for a zero-required-parameter tool whose scope otherwise depends on ambient state.

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 exceeds the baseline: it tells the agent that pageId is not a filter but a mode switch that changes the returned payload from page summaries to access policy/theme override details, which the schema's terse 'Show one page's settings' does not make clear. The id parameter's scoping is implied only through 'the site's pages'.

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 the site's pages') and enumerates the returned fields (id, name, url, file, home/404 flags), plus the second mode where pageId yields access policy, body class and theme overrides. It does not explicitly differentiate from close siblings like outline_page or update_page, so it is clear but not sibling-routing.

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?

'Use it to get page ids' gives an explicit invocation context for the no-argument case, which is the primary workflow (list, then act on an id). The pageId mode is described by its output rather than by when to prefer it over update_page or outline_page, and no exclusions are stated.

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 the safety profile is fully structured and the description need not repeat it. The description adds the compact-mode return shape and the linkage to set_theme, but says nothing about mood-filter behavior or whether results are ordered.

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 fragments, front-loaded with the resource definition before the parameter and follow-up hints. No filler, though the telegraphic style (e.g., 'set_theme({ preset }) applies one') leans on the agent parsing notation rather than prose.

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 read-only lister with no output schema, the description adequately covers what a full preset contains and what compact mode trims. It is slightly incomplete on the mood parameter's semantics and non-compact return payload, but nothing critical blocks correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents mood, brief, and compact. The description restates compact's effect ('id + name only') without adding anything the schema lacks, and never clarifies the mood filter or the brief/compact aliasing relationship.

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

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

The description names the resource (curated theme presets) and defines their contents (palette + fonts + tokens), so the agent knows exactly what is returned. It also points at the applying sibling set_theme, which helps differentiate this read tool from the mutation. It stops short of a fully explicit 'list' verb, letting the tool name carry that.

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

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

The mention of set_theme({ preset }) implies the workflow (fetch a preset, then apply it), but there is no explicit when/when-not guidance. It does not distinguish the tool from plausible alternatives like suggest_palettes, suggest_font_pairings, or list_templates, leaving the agent to infer which preset source to use.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description's contribution is the scope note that codes come from the site's own connected Stripe account, plus 'on or off' implying both active and inactive codes are returned. It omits ordering, pagination, and empty-state or disconnected-Stripe behavior.

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

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

A single compact sentence that front-loads the resource and its source before the field list. Nothing extraneous, though the terse fragment style slightly reduces readability.

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

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

With one required parameter and no output schema, enumerating the returned fields is genuinely helpful and largely fills the gap. However, a list operation with an external dependency (Stripe) should at least note what happens when the account is not connected or when no codes exist.

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

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

Schema coverage is 100% for the single required siteId parameter, so baseline is 3. The description only refers to 'the site's' codes and adds no format, default, or scoping detail 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?

The description names a specific resource (promo codes) with a clear scope (the site's own Stripe account) and enumerates the fields returned, so an agent knows exactly what it is retrieving. It does not explicitly contrast with the sibling set_promo_code, but the list-vs-set distinction is obvious from the verb and title.

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

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

There is no explicit when-to-use guidance, no mention of a prerequisite Stripe connection requirement (only an oblique 'from its own Stripe account'), and no named alternative such as stripe_get_product or set_promo_code. The usage is only inferable from the tool name.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and non-openWorld, so the safety profile is covered. The description does add genuine value by describing the returned content shape (pin location, quoted text, conversation, author, status, open/resolved counts), but it omits paging behavior even though a `page` parameter exists, which is the main behavioral unknown left.

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 return shape is front-loaded in the first clause, with filtering and origin context after — good ordering. The final sentence about clients leaving comments on the dashboard review link is useful orientation, though the sentence structure is crowded and could be split for readability.

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

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

For a read-only list tool with all four optional params fully documented in schema, the description supplies what the schema cannot: what a thread actually contains and what the counts mean. The missing piece is pagination/sort behavior, which matters because a `page` param exists and there is no output schema.

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

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

Schema coverage is 100%, so the schema already documents id, page, status and pageSlug — baseline 3. The description goes slightly beyond by tying the two filters to intent ("Filter by status or pageSlug") and explaining that the quoted text encodes the pin location, which helps interpret results per pageSlug.

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 the specific resource (client review comments on a site) and its structure — pinned to a spot on the preview, with quoted text, conversation, author, status, plus open/resolved counts. That is far more precise than a tautology. It stops short of naming the sibling it pairs with (reply_review_thread review for responding), so it doesn't fully differentiate from its one close relative.

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 filter usage ("Filter by status or pageSlug") and contextualizes where the data originates (the review link from the dashboard's Review screen). However, it never says when to call this versus reply_review_thread, nor does it state prerequisites such as needing a site id or an existing review link. Usage is implied rather than prescribed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only a vague hint about entry contents and says nothing about scope (one site vs all sites), pagination, or ordering — minimal added value beyond structured data.

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

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

It is very short with no wasted words, but it is under-specified rather than genuinely concise: the phrase is not front-loaded with an action and reads as a fragment.

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

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

For a simple read-only list tool this could be adequate, but the description fails to resolve the key ambiguities an agent faces: that 'id' is optional, and whether the call returns emails for one site or across sites. With no output schema, that gap goes unfilled.

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

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

Schema coverage is 100% with a single documented 'id' parameter, so the schema carries parameter meaning. The description adds nothing about the id, and notably never explains that it is optional or what omission means.

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 is a noun-phrase fragment ('Transactional emails: customized or default, whether each sends') that never states a verb or that it enumerates them; the operation is only inferable from the tool name. It adds detail about what each entry contains, but that is closer to restating the name than declaring a distinct action.

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

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

There is no guidance on when to call this versus sibling tools such as get_site_email (single email), preview_site_email, or update_site_email. No prerequisites, no exclusions, and no indication of what happens when the optional site id is omitted.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description does add real value beyond them: it scopes results to DRAFT files and notes that each file's serving page is reported, which shapes how an agent reads the output. It stops short of pagination, ordering, or what is returned for non-HTML site formats.

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?

It is short, but the second sentence ('Format: get_style_reference({ topic: "liquid" })') reads as leaked or misfiled boilerplate that does not describe this tool and actively confuses the reader. The useful content is buried in a parenthetical conditional ('format: html') that leads the description.

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

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

With no output schema, the description must convey what comes back — it partially does ('every draft file ... and which page each serves'). However, for a tool with 0 required params and a site-format conditional, the description never resolves what is returned for non-HTML sites or how a caller should pick a site id. Adequate but with clear gaps.

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 id and glob are already documented in the schema, making 3 the baseline. The path examples in the description ('partials/*.liquid', 'assets/*.js') illustrate the file universe but do not clarify glob syntax or default behavior beyond what the schema says. No added semantic value over the structured fields.

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

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

The description identifies a specific resource — draft site files (pages/*.liquid, partials/, sections/, theme.css, site.json, emails/, assets/*.js) — and a notable output trait ('which page each serves'). But the verb is only implied via the name, and the scope is gated on 'HTML-first sites (format: html)' with no statement of what happens for other site formats. It does not differentiate itself from search_site_files, read_site_file, or list_pages.

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

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

No when-to-use instruction is given. The closest thing to guidance is the trailing 'Format: get_style_reference({ topic: "liquid" })', which points at a different tool rather than explaining when to choose list_site_files over search_site_files or read_site_file. An agent must infer the routing from tool names alone.

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/closed-world, so the safety profile is covered. The description adds real value beyond that: result ordering, the fact that each entry reports its provenance (mcp/ai/editor) and whether it is restorable, and that revisionId switches to a diff view rather than a list view.

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?

Tight and front-loaded: the primary list mode comes first, the revisionId mode second, and the prerequisite pointer to restore_site_revision last. The telegraphed shorthand ('+added -removed ~changed') is efficient but borders on cryptic for an unfamiliar agent.

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 enumerating the returned fields and describing what diff output looks like. Combined with full schema coverage for the six parameters and annotations covering safety, an agent has everything needed to call it correctly in either mode.

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

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

Schema description coverage is 100%, so all six parameters are already documented, which sets the baseline at 3. The description mainly restates schema content (diff 'prev', path = one file in full); its only genuine addition is framing revisionId as a mode switch, which is useful but modest.

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: version history of a site, newest first, with an explicit list of returned fields (id, version, action type, actor/provenance, add/remove/change counts, restorability). It also cleanly describes a second mode triggered by revisionId (per-file diffs), so an agent can distinguish it from sibling list tools like list_pages or list_site_files.

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 directs the agent to read history before calling restore_site_revision, and explains the conditional usage of revisionId, diff and path. It lacks an explicit 'when not to use' or a contrast with other listing tools, so it falls just short of the top band.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real value beyond that by disclosing the return content (members with roles, pending invites with ids) and an authorization constraint (owner-only) that annotations do not express.

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

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

Two sentences, no filler: the resource and contents come first, the access constraint is front-loaded at the end. Every clause carries information an agent needs.

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 one-parameter read tool with no output schema, the description covers what is returned and who may call it. The only gap is what happens when the optional id is omitted (does it default to the selected site?), which list_sites/select_site siblings imply but do not confirm.

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

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

The single id parameter is fully documented in the schema as 'Site id.' and the description adds no further semantics such as format, defaults, or behavior when id is omitted (it is listed as not required). With 100% schema coverage, 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?

Specific verb+resource ('List a site's members') plus the extra payload detail that pending invites and their ids are included. It does not, however, distinguish itself from the sibling list_members, leaving the agent to infer that one is site-scoped and the other presumably workspace-scoped.

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?

'Owner-only.' gives a useful precondition for calling, but there is no explicit statement of when to prefer this over list_members or list_membership_plans, which are the obvious alternatives in a crowded list/member tool family.

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 that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful authentication/tenant context and notes that it is remote, but it does not describe response format, pagination, or other behavioral details.

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

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

The description is a single, front-loaded sentence with no wasted words. It conveys scope and authentication context efficiently.

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

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

For a simple zero-parameter list tool with rich safety annotations and no output schema, the description is largely complete. It could add a brief note about the expected return structure or whether results are paginated, but those gaps are minor.

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

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

The tool has zero parameters, so there is no parameter semantics burden. The schema coverage is 100%, and the description appropriately does not invent parameter details.

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: 'List all sites,' and adds the scoping condition 'belonging to the authenticated tenant.' It is clear what the tool does, though it does not explicitly differentiate itself from nearby sibling tools such as select_site or list_site_members.

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

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

The tenant scope implies when this tool is appropriate, but there is no explicit guidance about when to use it versus alternatives. An agent can infer that it is for retrieving sites, but not e.g. whether select_site should be used afterward.

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, closed-world behavior, so the description's only added signal is the word 'stock.' It says nothing about whether multiple filters combine (AND/OR), result ordering, or whether the list is paginated — gaps the annotations do not fill.

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

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

Two short sentences with the action front-loaded and no padding. The second sentence duplicates what the schema already conveys, which is the only small inefficiency.

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

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

For a zero-required-parameter read tool with full annotations and full schema coverage, this is close to sufficient, but an agent still cannot tell whether filters combine, whether results are paginated, or how this differs from pull_template.

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

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

Schema description coverage is 100%, so all three parameters are already documented with examples in the schema. The description merely restates the filter fields and adds no syntax, combination, or precedence guidance 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: 'List stock templates.' An agent can tell it lists a template library rather than site pages, but the description never names or distinguishes the closest sibling, pull_template, which is the natural follow-on action.

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