SnapHost

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

With annotations already covering read-only, destructive, and idempotent traits, the description adds useful behavioral context: it returns the DNS records the owner must add, and the domain only serves after records resolve and verification completes. It also details workspace alias resolution behavior. There is no contradiction with the annotations.

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

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

The description is front-loaded with the user-facing trigger and is dense with relevant behavioral detail. The workspace alias examples are useful rather than filler, and the closing statement about DNS records and verification 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 multi-mode tool with no output schema, the description covers return value (DNS records to add), activation condition (records resolve and are verified), and the workspace alias details. It does not specify the exact shape of the DNS records or failure/error cases, but the schema plus description is largely sufficient.

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?

Though schema coverage is 100%, the description adds meaning beyond the schema. It explains that site_id binds one specific Pro site, that target: 'workspace' makes the host a full alias of the workspace subdomain, and that site_id on target workspace names the root site at the bare path. This significantly clarifies the target and site_id parameters.

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 an explicit use case ('Use when the user wants the site on their own domain') and clearly identifies the resource and action: pointing a custom domain at SnapHost. It also distinguishes the site-binding and workspace-alias modes, which separates it from sibling tools like remove_custom_domain, verify_custom_domain, and list_custom_domains.

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 states a clear triggering condition and explains the two target modes (site vs workspace), giving the agent enough context to select the tool. However, it never explicitly says when not to use it or points to alternatives like verify_custom_domain for checking status or remove_custom_domain for teardown, so exclusions are missing.

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

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

Annotations already mark this as non-read-only, idempotent, and non-destructive. The description adds valuable context: the operation is additive ('never replacing'), returns the full updated render options, is a paid capability, and imposes the bare https format. This goes beyond the annotations without contradicting them.

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

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

Dense but efficient: every sentence contributes distinct value—additive behavior, trigger scenario, approval requirement, format constraint, cost, alternative tool, and return value. Front-loaded with the core purpose.

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

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

For a 3-parameter tool with no output schema, the description covers invocation context, constraints, side effects, the alternative tool, and the return value. Nothing essential is missing for an agent to select and call it correctly.

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

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

Schema coverage is 100% and schema descriptions are already decent. The description adds meaningful semantics not in the schema: each origin must be a bare https://host[:port] with no path, and origins are added rather than replacing the existing allowlist. This enhances the agent's ability to construct valid parameters.

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: 'Trust one or more external https origins for a site' while clarifying that it adds to, never replaces, the CSP allowlist. Clearly differentiates the tool's additive scope from replacement via set_render_options.

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

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

Explicitly says when to use it: as the follow-up when publish_site or update_site reports blocked origins and the owner confirms approval. Also names set_render_options as the alternative for removing or replacing origins, and warns to only pass owner-approved origins.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description reinforces idempotency and adds critical side effects: invite emails sent to new entries, the optional message inclusion, and the Pro-plan refusal behavior. It also clarifies that domain entries receive no email. This goes beyond annotations and does not contradict them.

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

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

The description is long but every sentence carries information: use cases, behavior, alternatives, prerequisites, plan requirements, and side effects. It front-loads the core purpose before diving into details. No filler or repetition; it is dense but well-structured.

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

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

The tool is a write operation with multiple nuances: idempotency, invite emails, plan gating, and a private-site prerequisite. The description covers all of them, plus alternatives. No output schema exists, but for a mutation tool this is acceptable; the description provides everything an agent needs to decide whether and how to call it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it explains that `message` is a personal note in the invite email (schema only says optional), that `allowlist` entries are appended and duplicates ignored, and that domain entries don't get emails. It also clarifies the `site_id` must point to a private site. This is useful semantic enrichment.

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: 'Adds email and/or domain entries to a private site's allowlist.' It distinguishes itself from set_allowlist (replace) and remove_from_allowlist (take off), so an agent can tell them apart. The phrase 'WITHOUT removing anyone already on it' makes the scoped behavior unambiguous.

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

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

Gives explicit triggers ('when the user wants to let one more person in, invite a client, or share it with the team') and names the exact alternatives: 'use `set_allowlist`' for replacement and 'use `remove_from_allowlist`' to remove. It also states the prerequisite (site must be private) and the Pro-plan restriction, leaving no ambiguity about when to invoke.

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/destructive/idempotent traits, and the description adds valuable context beyond them: it provisions a collection and returns an HTML block for insertion. Stating the 'Needs Pro' and ownership constraints also clarifies authorization conditions beyond annotation 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?

Three dense sentences, with the trigger front-loaded and no filler. Each sentence adds distinct information: when to use, what it does, and constraints/dependencies. There is no redundancy 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?

The description covers when to use, what action occurs, what is returned, the prerequisite (Pro), ownership scope, where to get recipe ids, and the follow-up publish step. Since there is no output schema, the explicit note about returning the HTML block is especially important for an agent knowing the result.

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

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

The input schema has 100% description coverage, so the schema already documents all three parameters. The description adds minimal parameter-level meaning beyond pointing to list_data_recipes for recipe_id and the site-ownership constraint for site_id, but it doesn't carry significant extra semantic weight beyond the schema.

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

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

The description opens with an explicit trigger ('Use when the user wants a contact form, waitlist, RSVP, guestbook, counter, or leaderboard') and then states the outcome: provisions a recipe's collection and returns an HTML block. This clearly identifies the verb (apply data template), the resource (data recipe), and how it differs from generic site-editing 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?

It gives an explicit when-to-use trigger and useful constraints ('Needs Pro; scoped to a site you own'). It also points to list_data_recipes for recipe ids and mentions a follow-up step (publish with update_site), providing enough context. However, it doesn't explicitly describe when not to use it or contrast it with alternatives like set_site_data or define_collection_schema.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context: the requester is added to the allowlist, the effect is view access, and rejected requests (forbidden, plan_limit, not_found) make no change. This goes beyond the annotations and clarifies the tool's side effects and no-op cases. It doesn't fully describe all possible failure modes or permission errors, but it is strong for a mutation tool.

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

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

The description is two sentences, front-loaded with the core action and effect, then the discovery workflow and permission/edge-case notes. Every sentence earns its place; there is no fluff or repetition of schema content.

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

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

For a mutation tool with no output schema, the description covers the action, effect, prerequisite discovery step, permission restriction, and no-op cases. It doesn't describe the response format or what happens on success beyond the allowlist addition, but the annotations cover idempotency and non-destructiveness. The main gap is the lack of explicit error/response details, but the description is otherwise complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the purpose of request_id (find it via list_access_requests) and the workspace_id semantics are already well-covered in the schema. The description doesn't repeat parameter details, but it does connect request_id to a concrete discovery workflow, which is useful.

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 ('approve'), a specific resource ('pending access request'), and the concrete effect ('requester is added to the site's allowlist and can then view it'). It also distinguishes itself from the sibling deny_access_request by focusing on approval. This is a clear, non-tautological definition.

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

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

The description explicitly tells the agent when to use this tool: to approve a pending access request, and how to find the required request_id via list_access_requests. It also states the admin/owner-only restriction and notes that rejected requests make no change, which helps the agent decide whether to call this tool or handle the request differently.

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

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

Annotations already mark the tool as destructive and idempotent. The description adds useful unannotated behavior: edit access is requiredaine, and rejected requests ('forbidden', 'not_found') leave the stored password unchanged. This clarifies failure semantics beyond the annotations.

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

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

The description is two sentences with the action and outcome front-loaded, followed by access requirements and error behavior. Every clause earns its place and there is no redundancy or padding.

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

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

For a two-parameter mutation with no output schema and good annotation coverage, the description supplies the operation's intent, preconditions, and failure mode. Nothing an agent needs to invoke it correctly is missing.

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

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

The input schema already documents both parameters at 100% coverage, including detailed workspace_id behavior. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Remove') and resource ('a site's view password') and states the result ('viewers with the link can open it without a password'). This clearly differentiates it from set_view_password and other site mutation tools.

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

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

The description gives clear context for when to use the tool—removing a view password—and a necessary precondition (edit access). It doesn't name an alternative or state 'when not to use', so it misses the most explicit guidance level but is still unambiguous.

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

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

Annotations only give the non-destructive, non-idempotent, non-open-world profile. The description adds the traits an agent actually needs: the upload is single-use and expires, it is bound to the workspace the call acts in, the same workspace_id must be reused for every part and the publish, and the tool-call network is isolated from the shell's network.

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

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

Purpose and the two transports are front-loaded and every sentence carries real information, but the prose is dense and parenthesis-heavy (~250 words for a session-creation call), which makes it harder to scan than it needs to be.

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

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

No output schema exists, yet the description names what comes back (upload_id, upload_url, storage_url, max_part_bytes) and how each is consumed, plus expiry and workspace-binding caveats. An agent has everything needed to call this correctly and follow up.

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 nonetheless adds operational meaning: filename is given once and remembered across parts and publish, and workspace_id must be passed identically to every upload_bundle_part and to the publish. Some of this restates the schema, but the cross-call consistency requirement is new.

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 ("Start a bundle upload") with the exact scope of what qualifies (multi-file/media-heavy site, or one non-zip file by type). It explicitly distinguishes itself from siblings: publish_site/update_site consume the returned upload_id, and upload_bundle_part is named as the alternative transport.

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

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

Explicit when-to-use: instead of inline html/zipBase64. Explicit branch conditions between the two transports (upload_bundle_part for any client incl. sandboxes with no network; HTTP PUT when the shell can reach the host; storage_url for one request at any size). It even gives the failure-handling rule (a 403 on PUT says nothing about upload_bundle_part, so switch rather than changing network settings).

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 are all false, so the description carries the burden of behavioral disclosure. It discloses default behavior for shared folders (open to team), the effect of open_to_team: false (restricted), the constraint that a nested folder must share its parent's drive, and the slug derivation from name, including the marketing folder requirement. No contradictions with annotations. Strong behavioral context.

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

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

The description is several sentences long but each sentence carries information: purpose, space semantics, nesting, open_to_team behavior, and return slug. It is front-loaded with the main purpose and flows logically through parameters and constraints. No filler; though slightly long, it's efficient and well-organized.

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

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

There is no output schema, so the description must explain the return value; it does: 'Returns the new folder, with the slug derived from its name; in the website workspace the landing-page folder must end up slugged `marketing`, so check the returned slug.' It also covers key creation constraints (nested folder drive match, open_to_team default and restriction). It doesn't mention error cases or permission requirements, but for a creation tool with these details, it is largely 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 baseline is 3. The description adds meaning beyond the schema: it explains the 'space' values (personal/shared, Pro workspaces only), indicates parent_id should come from list_folders, and details the behavior of open_to_team (including the marketing folder exception). It also hints at workspace_id behavior indirectly through 'the website workspace' example. This adds genuine value.

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

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

The description clearly states the tool's purpose: 'Create a folder to organize sites.' This is a specific verb plus resource, and given the sibling set (delete_folder, rename_folder, move_folder, set_folder_slug), it distinguishes itself as the creation operation. No ambiguity about what it does.

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

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

The description provides concrete usage context: it explains how to create top-level versus nested folders via parent_id (from list_folders), notes that shared drive is 'Pro workspaces only', and clarifies the open_to_team behavior. It also mentions a specific use case in the website workspace (slug must be 'marketing'). However, it does not explicitly state when not to use this tool or name alternatives, though the sibling listing implies them. Adequate 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 only say readOnly=false and destructive=false, so the description carries a heavy burden and it delivers extensively: it states nothing is deleted, version history and collected records remain untouched, prior visibility is restored, and the page may not become live until set_visibility is called. It also covers subdomain address behavior and the lapsed-plan refusal case, going far beyond the annotations.

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

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

All sentences carry useful information, and the main use case is front-loaded, but the content is one dense wall of text with many nested clauses and edge cases. It could be tightened or structured into separate points without losing meaning.

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

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

Given the tool's complexity and lack of an output schema, the description covers the necessary behavior, follow-up requirements, address output semantics, and refusal condition. The agent has enough context to call the tool correctly and interpret what it returns.

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 site_id and workspace_id, meaning the description does not need to compensate. It mentions output fields like landing_url and share_url, but adds little parameter-level 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?

The description opens with a specific use case: a site lost its link and the user wants it back, then clearly states the tool creates a fresh share link when none exists. It distinguishes this recovery operation from everyday publishing by noting every site gets a link when published and that an active link is kept and not replaced.

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

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

Explicitly says when to use it ('a site lost its link and the user wants it back') and when it will not act ('a site that already has an active link keeps it and gets no second one'). It also names a required follow-up call, set_visibility, for restricted pages, and describes the one refusal case. It does not contrast with sibling tools like set_link_status, but the usage 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 idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds value by explaining the mutation semantics ('Define or clear'), the server-side validation effect, and the Pro requirement. It does not contradict annotations and provides behavioral details beyond them.

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

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

Three sentences with no redundancy. The core action and the null option are front-loaded, followed by the Pro requirement and scope. Every sentence carries information, and the structure is clear.

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

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

Given the simple parameter set and no output schema, the description covers the essential behavior, scope, and prerequisite. It does not detail error handling or return values, but these are less critical here. The description is complete enough for an agent to call the tool correctly.

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

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

Schema coverage is 100%, so parameters are fully documented. The description adds minor context by explaining that schema=null clears the schema (already in schema description) and that a schema validates records. It does not significantly enhance parameter understanding beyond the schema.

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

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

The description states a clear verb-resource pair ('Define (or clear) a JSON Schema on a collection') and scopes it to 'a site's data store'. It also clarifies the effect (server-side validation, typed backend) and distinguishes itself from sibling tools like delete_collection or set_collection_access by focusing on schema definition.

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

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

The description gives actionable context: it mentions the Pro requirement and that it is scoped to a site you own. It implies when to use (when enforcing a schema on a collection) but does not explicitly name alternatives or when-not-to-use. The Pro caveat and ownership scope are helpful guardrails.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds useful behavioral context beyond that: irreversibility, site-ownership requirement, and the full set of things destroyed (records plus access-mode and schema settings).

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 short sentences, front-loaded with the core action, and every sentence earns its place. No fluff, no repetition of schema 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, irreversible operation with no output schema, the description covers the essential facts: what is deleted, that it cannot be undone, and the ownership scope. It does not mention idempotent behavior or error cases, but those are not critical for a caller deciding whether to invoke it.

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

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

Schema description coverage is 100%, so the schema already documents site_id, collection, and workspace_id. The description adds some meaning around collection-level scope and ownership, but not per-parameter 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 and resource: 'Delete an entire collection,' and spells out exactly what that includes: records, access-mode settings, and schema settings. This clearly differentiates it from sibling tools like delete_site_record and delete_site.

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

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

Clear contextual guidance: it is the tool for deleting a whole collection rather than a single record, and it is scoped to a site you own. It does not explicitly name alternatives or exclusions, but the scope is evident from 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?

The annotations already mark it destructive and non-read-only, but the description goes further: it details that content is preserved, subfolders get new slugs, addresses are lost, and permission is required. It also covers the special Marketing-folder case and explains address changes.

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 front-loads the action and packs necessary side effects into a few sentences. It is longer than the minimal, but each clause earns its place, including the workspace-specific exception. No redundancy.

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

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

Given no output schema, the description mentions that the result names every address that ended and started, giving a clue to return value. It covers permissions, content preservation, slug behavior, and special workspace case. It is nearly complete for a delete 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 coverage is 100%, and the description adds no direct parameter-level semantics for folder_id or workspace_id. It implies that some folders (Marketing) may not be deletable and permission matters, which is context about folder_id, but not a full parameter explanation. 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?

Clearly states 'Delete a folder' – a specific verb and resource. The following explanation that sites and sub-folders are kept and moved up distinguishes it from delete_site or move_folder by describing exactly what is and isn't removed.

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

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

Provides conditions (permission to manage folder) and an exclusion (Marketing folder is never deleted), but does not explicitly compare with alternatives like move_folder or set_folder_slug. So the guidance is mostly implied rather than explicit.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description adds critical behavioral context: the operation is irreversible, nothing can read the data back afterwards, content and version history are purged, records/collections are deleted, and the share link becomes non-viewable. This fully discloses the destructive consequences.

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

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

The description is dense but every sentence earns its place: scope, effects, irreversibility, pre-read guidance, and an alternative are all included. Key consequences are front-loaded before the cautionary and alternative statements.

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 no output schema and rich annotations, the description is complete: it explains what gets destroyed, what cannot be recovered, what to do first, and which sibling to use instead. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents both site_id and workspace_id thoroughly. The description adds no parameter-level detail beyond 'by id', which is consistent with the baseline of 3 for high schema coverage.

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

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

The description states a specific verb and resource: deletes a site by id, and enumerates exactly what happens (marks deleted, purges content and version history, deletes records and collections, makes share link non-viewable). It also distinguishes itself from the sibling create_share_link, so an agent can tell it apart.

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 says when NOT to use it ('Not a way to fix a broken address') and names the alternative (create_share_link) that should be used instead. It also provides concrete pre-call steps with sibling tools (list_site_collections, get_site_content, export_site_data) before performing the destructive action.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description does not need to repeat that this is destructive. It adds valuable context beyond the annotations: records are normally append-only/immutable, this is a moderation exception, and deletion is scoped to a site the user owns.

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 tightly written sentences with no filler. The core action comes first, followed by the moderation context and the ownership constraint, all in the most efficient order.

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

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

For a straightforward single-record deletion with a complete schema and rich annotations covering idempotence and destructiveness, the description provides the necessary behavioral framing. Nothing critical is missing for an agent to correctly invoke this tool.

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

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

Schema description coverage is 100%, so the input schema fully documents site_id, record_id, and workspace_id. The description reinforces the ownership scoping tied to site_id, but it does not add materially new parameter meaning beyond what the schema already provides.

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

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

States a specific verb and resource: 'Delete one record from a collection (moderation).' The description clearly distinguishes this from deleting an entire collection or site, and the ownership qualifier further pins down the scope.

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

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

The '(moderation)' framing and the statement that 'Records are otherwise append-only and immutable' give clear context for when this tool is appropriate as an exception. It does not explicitly name alternatives or say when not to use it, but the distinction from the sibling delete_collection and delete_site tools is strong enough.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds the concrete consequence (not added to allowlist, remains unable to view site) and reiterates idempotency with 'rejected requests make no change'. It also adds the permission requirement (admin or owner). This adds value beyond annotations without contradiction.

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

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

Two sentences, front-loaded with the core purpose and immediate consequence, then the necessary context (how to get the ID, permission, idempotency). Every sentence serves a distinct function with no redundancy.

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

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

Given no output schema, the description covers the outcome (requester not added, stays unable to view), the idempotent behavior for rejected requests, and the required permissions. It also tells how to find the required request_id. For a simple denial action, this is fully sufficient.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds a specific hint: 'Use list_access_requests to find the request_id', clarifying how to populate that parameter. It doesn't elaborate on site_id or workspace_id, but those are well-documented in the schema. This extra guidance lifts it to 4.

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

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

The description clearly states the action: 'Deny a pending access request' and its consequence ('requester is not added to the allowlist and stays unable to view the site'). It distinguishes this from sibling approve_access_request by explicitly saying what happens instead of approval. The verb-resource pair is specific and unambiguous.

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

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

The description tells the agent to use list_access_requests to find the request_id, providing a direct workflow. It also states the admin/owner-only restriction and that rejected requests make no change, which guides when to call and what to expect. This is explicit and actionable.

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 valuable behavioral context beyond the annotations: the 5000-record cap, the truncation behavior with `truncated: true`, the meaning of `count`, and the scoping constraint ('Scoped to a site you own'). It does not describe the exact response shape, but with no output schema and the annotations covering safety, the description carries a substantial share of the behavioral burden and does it well.

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: the core action and limit come first, then the truncation/count semantics, then the sibling comparison, then the use case and scope. Every sentence earns its place, and there is no repetition of schema or annotation content.

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

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

For a read-only export tool with 3 parameters, 100% schema coverage, and annotations covering safety, the description is complete. It explains the limit, the truncation signal, the count semantics, the alternative tool, the intended use case, and the ownership scope. An agent has everything it needs to decide when to call this tool and what to expect from the result.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds meaning by explaining the relationship between `count` and `truncated`, and by clarifying the workspace_id semantics ('Required on a write when the connection reaches more than one workspace'). It doesn't add per-parameter syntax details, but the schema already covers the basics, and the description's extra context about the result fields is genuinely useful.

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 ('Export'), a resource ('the records in a collection'), and a concrete limit (5000). It also distinguishes itself from query_site_records by naming the sibling and the key difference (200-record cap, no paging). An agent can tell exactly what this tool does and how it differs from the closest 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 description explicitly says when to use this tool ('Use for backup or analysis') and contrasts it with query_site_records, which 'reads at most 200 records and cannot page past them, so it can never total a collection.' This gives the agent a clear decision rule: choose export_site_data when a full collection or a total count is needed, and query_site_records when only a small read is needed.

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/closed-world, so the safety profile is covered structurally. The description adds genuine behavioral context beyond that: this is a precondition step in a build sequence, and its output includes a rubric and design_warnings that must be resolved. It stops short of saying anything about the size or format of the returned guide.

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 tool's identity before the workflow and parameter notes, and every sentence carries actionable content. The topic enumeration in the first sentence is long and run-on, but it maps to the guide's actual scope rather than being 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 carries the burden and mostly does: it says what the guide covers, when to call it, how to parameterize it, and how to act on the result. Only the concrete shape of the returned document (sections, ordering) is left unstated, which is minor for a reference-retrieval tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by defining each trait enum in the agent's terms — printable (downloadable PDF that keeps the look), live (self-updating numbers), kiosk (an office screen) — which the enum list alone does not convey. workspace_id semantics live only in the schema, keeping this from a 5.

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

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

Names a specific verb and resource (get the design guide) and unpacks exactly what the artifact contains — brief questions, build-and-review procedure, rules for rhythm/type/charts/accessibility/locale, and the scoring rubric. It is clearly distinguishable from siblings like get_page_recipe (document recipes) and get_brand_kit, which it routes to instead of duplicating.

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 timing rule ('Call it BEFORE building any of the three'), states which inputs to supply, and then names the downstream siblings and actions (list_page_recipes, publish with document_kind/printable, fix design_warnings). An agent knows when to call this and what to do after, without inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds one genuinely useful behavioral detail — links are returned already absolute for the site and token references must be preserved — but says nothing about failure modes for an invalid id or permissions.

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?

What the tool returns and the id cross-reference are front-loaded in the first clause; the second sentence gives practical post-retrieval handling. It is short and mostly earns its space, with only mild bleed into usage guidance rather than tool specification.

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 characterizes the payload (HTML with absolute links, token placeholders to keep). Combined with the fully documented schema and clean annotations, an agent has enough to call it correctly; only error/edge behavior is unaddressed.

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

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

Schema description coverage is 100%: recipe_id's source (list_page_recipes) and workspace_id's full semantics are documented in the schema itself. The description only restates 'by id' and adds no format or constraint detail, so the baseline 3 applies.

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

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

The description names the resource ('one page recipe'), the lookup key ('by id'), and what is returned ('The HTML'), and it cross-references list_page_recipes so the agent knows where ids come from. It is distinguishable from the sibling list_page_recipes, though it relies on a noun phrase rather than an explicit verb.

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 points to list_page_recipes for obtaining a recipe_id and sketches the follow-on workflow ('paste it into the page... replace the copy'), which implies when to use it. It never states when NOT to use it or contrasts it with other retrieval siblings such as get_site_content or get_design_guide.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the bar is lower. The description adds real behavioral content: that link_expires_at is ISO or null, that link_status is derived, and that allowlist names who can view a private site. It omits auth/permission needs, but the annotation coverage makes that 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?

Front-loaded with the core action, but the remainder is one long run-on sentence enumerating roughly a dozen return fields, some with parenthetical explanation. Since there is no output schema the enumeration has value, but the wall-of-text structure makes it hard to scan.

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

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

With no output schema, the description carries the burden of describing returns and does so fairly thoroughly for this read tool. Combined with 100% schema coverage on inputs and annotations covering safety, an agent has nearly everything needed to call it correctly.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, so baseline is 3. The description adds only 'by id', which the schema already conveys via site_id; it adds no syntax or format detail beyond the structured fields.

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

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

States a specific verb and resource ('Get a single site's ...') and scopes it to one site, which distinguishes it from list_sites. It does not explicitly name sibling tools like get_site_content or list_versions, so the differentiation is only implicit.

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 explicit when-to-use, prerequisites, or alternatives are stated. The enumerated return fields imply the tool is for inspecting a site's status/visibility/metadata, which is enough to infer usage but not to route confidently away from get_site_content or list_sites.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), so the description's burden is lighter. It still adds real behavioral context beyond annotations: the encoding dual-mode (utf-8 vs base64 by content type), the rendered-vs-uploaded distinction for non-HTML sites, and the `note` field disclosure. It does not mention pagination or size limits, but the richer return-shape detail outweighs that gap.

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

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

Front-loaded with the core action and sibling differentiation, which is good. However it is quite long and packed with clause-heavy sentences (encoding, content_kind, update_site round-trip, original). Every sentence carries information, but the density reduces scannability for an agent parsing quickly.

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

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

The tool has no output schema, so the description must explain returns – it does so thoroughly (inline UTF-8 vs base64, content_type/content_kind/content_hash, note, original_included). An agent has what it needs to invoke and interpret the result. Minor gap: no mention of maximum content size or streaming.

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 does reinforce `original` (uploaded file vs rendered page) and the workspace write-context constraint, adding modest value, but the schema already documents all three parameters with 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 (fetch) and resource (a site's current entry document by id), and explicitly distinguishes itself from siblings get_site and list_sites by noting 'the read half of the round-trip get_site and list_sites omit (they return only metadata, never the body).' An agent can route between these tools without opening schemas.

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

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

Explicitly frames its place in a workflow ('so you can edit it and push the result back with update_site') and describes the alternative path for non-HTML sites ('To change such a site, send a new file to update_site'). The `original` parameter's when-to-use condition is 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 cover the read-only, non-destructive, idempotent nature of the operation. The description adds valuable behavioral context beyond those annotations, including the auth requirement, the plan limitation, and the fact that entries represent pending approval rather than full allowlist membership.

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 sentences with no filler: the first states the core purpose, the second summarizes the return fields, and the third covers auth, plan limitation, and the relevant sibling tools. Every sentence earns its place.

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

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

For a read-only list tool, the description is complete: it explains what is listed, what each entry contains, who may call it, and what plan requirement applies. The absence of an output schema is partially mitigated by the explicit field list, and no pagination or sorting details are strictly necessary 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 fully documents both site_id and workspace_id. The description doesn't add parameter-specific detail beyond defining the resource scope ('for an allowlist site'), which is fine given the schema carries the burden.

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

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

The description states a specific verb and resource: 'List pending access requests for an allowlist site', and clarifies exactly what these are ('people who asked to view it and are waiting for approval'). It goes on to name the approve/reject sibling tools, which makes its purpose unambiguous against the large 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 description gives clear context for when this tool applies: pending requests awaiting approval, with explicit prerequisites ('Admin or owner only; requires a plan with access requests enabled'). It names approve_access_request and deny_access_request as follow-up actions, though it does not explicitly contrast this with list_allowlist for already-approved members.

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 readOnlyHint and idempotentHint annotations, the description reveals meaningful behavior: stale allowlist entries persist on public sites and can be cleared via set_allowlist with an empty array. This adds practical, non-obvious operational context directly relevant to using the tool correctly.

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

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

Every sentence earns its place: purpose is front-loaded, the public-site caveat is explained, and the actionable call-before instruction is included. No filler or redundancy.

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

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

For a simple read-only list tool with no output schema, the description covers what is returned, how public visibility interacts with the allowlist, and when to call it. Combined with the annotations, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already fully documents site_id and workspace_id. The description adds conceptual context about what is being inspected but does not need to repeat parameter-level 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 states a clear, specific action: 'Show who a site is currently shared with' including both visibility and allowlist entries. It distinguishes itself from sibling write tools like set_allowlist, add_to_allowlist, and remove_from_allowlist by framing this as the read-only inspection counterpart.

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

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

Explicitly instructs the agent to 'Call this before adding or removing people' to avoid overwriting the existing list. It also covers an important nuance—public sites ignore the allowlist—which helps the agent decide when this tool's results are relevant.

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 useful scope context (site-bound vs workspace-bound) and confirms the returned information (verification status), but does not go further into behavior like pagination or result shape. This is a solid but not exceptional addition beyond annotations.

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

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

A single sentence front-loads the action and then delivers the key conditional in a compact, readable way. There is no fluff or repetition; every clause earns its place.

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

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

With no output schema, the description still conveys the general return concept ('domains with their verification status') and covers the two invocation modes. It does not detail exact response fields or pagination, but for a straightforward read-only list tool the description is sufficiently complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful nuance beyond the schema by explaining the consequence of omitting site_id (return workspace-bound domains), which is not present in the site_id schema. This elevates it 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 uses a specific verb ('List') and resource ('custom domains'), and adds a clarifying qualifier ('with their verification status') that differentiates this read tool from siblings like add_custom_domain, verify_custom_domain, and remove_custom_domain. It also clearly identifies the two scopes (site-bound vs workspace-bound), leaving no ambiguity about what the tool does.

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

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

The description gives clear context for choosing between the two invocation modes: pass site_id for site-bound domains, omit it for workspace-bound aliases. It does not explicitly name alternatives or state when-not-to-use, but the parameter-level guidance is actionable and unambiguous for the main usage scenarios.

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 goes further and reveals a non-obvious behavioral quirk: the accessMode field is largely ignored on the marketing site, where collections are created append_only, and recipes that read their own collection show nothing until public_read is explicitly requested by name. This is exactly the kind of context that prevents a mistaken agent from assuming the listed mode is honored. It also notes that no site context is required.

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, information-dense paragraph. It front-loads the purpose and usage, then adds the accessMode nuance and the 'No site needed' note. Every sentence contributes meaning; there is no filler. It is slightly long, but the complexity of the behavioral quirk justifies the length. It could arguably be split into a second sentence for readability, but it remains efficient.

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 operation with no output schema, the description provides the essential behavioral context (accessMode nuance) and the usage pairing with apply_data_template. It does not specify the return format, but for a list tool the examples given are enough for an agent to infer what the list contains. The annotations cover safety, so nothing critical is missing. A brief note on the structure of the returned list would have made it a 5, but it is sufficiently 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?

The schema documents the only parameter, workspace_id, with 100% coverage, including its optionality and the rules about which workspace it applies to. The description adds nothing about this parameter, which is acceptable because the schema already fully explains it. Baseline 3 applies when 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 opens with a specific verb ('List') and a concrete resource ('ready-made data features'), then enumerates examples (contact form, waitlist, etc.) that make the scope unmistakable. It also names the companion tool (apply_data_template) that this one feeds into, which distinguishes it from the many other list_* 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?

The description explicitly instructs 'Use with apply_data_template to add one to a site end-to-end,' giving a clear when-to-use context. It also states 'No site needed,' which clarifies the prerequisite. It does not explicitly name alternatives or exclusions, but the pairing with apply_data_template is sufficient guidance for an agent deciding whether to call this tool.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the bar for additional behavioral context is lower. The description adds useful context about workspace scope and the special role of the `marketing` folder, which goes beyond the structured annotations.

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

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

The description is three sentences with no filler. The main purpose is front-loaded, followed by practical usage guidance and a useful special-case note about the marketing folder.

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 only one optional parameter and robust annotations, the description covers the essential return fields, how to interpret them, and how to use them with related tools. The special note about the website workspace adds important context that is not available from the schema or annotations.

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 optional `workspace_id` parameter is already well documented. The description echoes the workspace concept but does not add significant new meaning beyond what the schema provides.

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

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

The description clearly states the tool lists folders in the workspace, including their ids, names, parent folder, and drive space. It uses a specific verb and resource, and the mention of `space: 'personal' or 'shared'` helps distinguish it from site-listing tools.

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

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

The description explains how to use the returned `folder_id` with `move_site_to_folder` or `publish_site`, and contrasts this with a site's own `folder_id` from `get_site`/`list_sites`. It gives clear context but does not explicitly name when not to use this tool versus a sibling.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine context about the listed artifacts (brand-token styling, bracket placeholders, waitlist collection provisioning), but says nothing about this tool's own behavior: no return shape, no ordering, no note on how workspace scoping affects the result.

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

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

The purpose is front-loaded, but the body sprawls into tangential operational detail about waitlist collections, the data SDK, apply_data_template, and blog rendering that belongs to other tools. Sentences are long, multi-clause, and repeatedly change subject, so the agent must sift the listing tool's job out of unrelated 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?

With no output schema, the description should describe returns; it enumerates the recipe names, which partially compensates. But it omits structure, ordering, and whether workspace_id filters the result, and it spends most of its length on behavior that applies to downstream tools rather than to this listing 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% for the single workspace_id parameter, so the schema already carries its meaning and the baseline is 3. The description never mentions workspace_id, though it does differentiate recipe sets by workspace type, which indirectly signals why the parameter matters.

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

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

The opening sentence states a specific verb and resource: 'List the ready-made documents and parts to build from,' and the body names the sibling get_page_recipe for fetching a single recipe. It is clearly distinguishable from get_page_recipe and list_data_recipes, though the wall of downstream detail buries the core purpose and never states what the list actually contains (names, ids, categories).

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

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

It gives explicit ordering and next steps: 'Read get_design_guide first' and 'Fetch one with get_page_recipe and edit its copy.' It also scopes which recipes apply to which workspace (report/presentation/dashboard vs. the website workspace). It stops short of any when-not guidance 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 establish readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond those by stating the returned information (schema, access mode, paused state) and the ownership constraint. It does not cover pagination or error behavior, but the description does not contradict the annotations.

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

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

One concise sentence with no filler. The verb, resource, output details, and scope are all front-loaded, making the description immediately scannable.

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 low-complexity, read-only listing tool with rich annotations and a fully documented schema, the description covers the essential selection and invocation information. A bit more about the return shape would help since there is no output schema, but the stated returned fields are sufficient for an agent to understand what the tool produces.

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 site_id and workspace_id. The description adds a small nuance by saying the action is scoped to a site the user owns, but otherwise does not materially enhance parameter understanding beyond the schema.

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

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

The description states a specific verb ('List'), a specific resource ('a site's data collections'), and the key output dimensions (schema, access mode, paused state). The scope line 'Scoped to a site you own' further distinguishes it from site-level list tools like list_sites.

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

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

The description gives clear context: it is for listing collections on a site the user owns. It does not explicitly name alternatives or when-not-to-use conditions, but the resource scoping makes the intended use reasonably unambiguous.

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

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

Annotations already declare this is a safe, idempotent, read-only, closed-world operation. The description adds the non-deleted scoping constraint and the workspace-confinement rule ('sites live in exactly one workspace') which is not obvious from annotations. Doesn't cover pagination or result caps, but that's a modest gap given the safety profile is already covered.

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

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

A single dense sentence crams the full field list, the field semantics parenthetical, and the filter semantics into one block. It is front-loaded correctly but overly packed – the enumerated return fields arguably belong in an output schema and make this hard to parse.

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 filter-list tool with full schema coverage and an existing annotations safety profile, the description covers workspace scoping, filter combination, and field inventory. No output schema exists, so enumerating return fields adds value, though pagination behavior remains unstated.

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

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

Schema coverage is 100%, so all five parameters are documented including enums for status, visibility, link_status. The description adds the AND-combination rule for filters and the workspace default behavior, but doesn't add syntax beyond what the schema provides. Baseline 3 for high-coverage 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+resource with explicit scope: lists sites in a single named workspace, non-deleted only. Distinguishes from get_site (singular) and list_workspaces by stating exactly which entities are returned and the workspace scoping rule.

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

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

Clear context: workspace_id is optional, defaults to personal space. Filter semantics are explained ('all combine with AND'). However, no explicit routing to alternatives among the many sibling list_* tools (list_workspaces, list_site_collections), leaving some 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 readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat safety. It adds useful behavioral detail: the sort order (newest-first) and the list of returned fields, which helps an agent understand the output. It does not contradict annotations, and it adds value beyond them, but it doesn't disclose potential pagination or limits. Given the annotations cover safety, a 4 is appropriate.

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 that states the action, the resource, the ordering, and the returned fields without any fluff. Every word contributes.

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 two well-documented parameters and no output schema, the description provides all necessary information: what it lists, the ordering, and the fields returned. It does not need to explain return format since there is no output schema. The only minor gap is the lack of mention of pagination, but that is not critical for a version list. Overall it is complete.

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

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

Both parameters are fully described in the schema (100% coverage), including the meaning of site_id and workspace_id. The description adds no additional parameter-specific semantics beyond what the schema provides, so the baseline 3 applies.

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

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

The description clearly states the tool lists a site's published versions, specifying the sort order (newest-first) and the exact fields returned (content hash, content kind, entry path, size, file count, timestamp). This is a specific verb+resource, and while there are many list tools among siblings, 'versions' is a distinct resource, so it 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?

The description implies usage when you need to inspect a site's published versions, but it does not explicitly mention when not to use it or point to alternatives. However, since no sibling tool lists versions, the context is clear enough, but the lack of explicit alternatives or exclusions keeps it at a 3.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description adds meaningful behavioral context beyond those: connection ownership, workspace scope, personal vs team kind, caller role, the older single-workspace note, and the refusal rule for writes without workspace_id. No contradictions with annotations.

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

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

The description is dense and somewhat long, but every sentence earns its place: scope, entry fields, usage guidance, and edge-case note. The main verb and resource are front-loaded; the later sentences provide necessary detail rather than filler.

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

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

For a one-parameter, read-only tool with no output schema, the description is complete: it covers what the result entries contain, how to use the result, what omitting the parameter means, and the special older-connection note. An agent has enough to call this correctly and decide when to pass workspace_id onward.

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 explains workspace_id thoroughly, including when it is required and what happens when omitted. The description reinforces this read/write nuance but does not materially add new parameter semantics beyond what the schema provides.

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

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

First sentence names the specific operation ('List the workspaces') and the resource ('this connection can act in'). It then defines exactly what each entry containsholistic and distinguishes workspace listing from sibling site/folder/allowlist tools without needing to open any schema.

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

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

The description clearly says the returned workspace_id should be passed to other tools trickles and explains when to omit it on reads and why writes fail without it on multi-workspace connections. It doesn't name an alternative tool to choose instead, but none is truly needed for this foundational listing operation.

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

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

It discloses slug reassignment, publishing and address side effects in the Marketing folder, permission changes, the immutable Marketing folder, and the recovery path. Since annotations only provide idempotent and non-destructive hints, the description carries the behavioral burden and does so thoroughly. No contradiction with annotations.

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

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

There is no filler, but the middle is a run-on, parenthetical-heavy paragraph that is hard to scan, and the critical self/descendant constraint is buried near the end. The purpose is front-loaded, but the side-effect list would be much easier for an agent to parse as structured bullets.

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 write tool with no output schema, the description covers the operation, return value, result naming, recovery instructions, constraints, and workspace-specific side effects. Combined with the schema's already thorough workspace_id description, an agent has what it needs to call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by telling the caller to source folder_id and parent_id from list_folders and by tying parent_id omission to drive-root movement. It does not add new meaning for space or workspace_id, but those are already well described 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 opens with the specific operation 'Re-parent a folder' and elaborates through parent_id and root-moving, making it clearly a folder-move tool rather than rename_folder or set_folder_slug. It is not a 5 because it never names a sibling such as move_site_to_folder, so the agent must infer the boundary from the word 'folder'.

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 clear context: how to supply IDs from list_folders, omit parent_id to move to the root, and the prohibited self/descendant move. It also distinguishes shared-drive behavior from website-workspace behavior. It does not explicitly list alternatives, but the context is strong enough to guide selection.

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

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

The description adds significant behavior beyond annotations: share links are preserved, personal/shared moves change visibility, only the creator can move, and the public /lp URL can change for landing pages. None of this contradicts the readOnly/destructive/idempotent hints.

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

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

Every sentence earns its place: purpose, usage, visibility effect, permission, return value, and the URL caveat. It is front-loaded and dense without being padded.

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

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

For a mutating tool with no output schema, it explains the return value, the permission precondition, the behavioral consequences, and the folder_id sourcing. The complex landing-page URL implication is explicitly called out, leaving no critical gap.

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

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

The schema already documents every parameter in detail (100% coverage), so the baseline is 3. The description adds operational meaning for folder_id (source list_folders, omission equals root) and contextual semantics for personal vs shared moves, warranting 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 'File a site into a folder, keeping its share link', naming a specific verb, resource, and effect. It also clarifies the no-folder case (drive root) and distinguishes site filing from sibling folder operations such as move_folder.

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 clear operational guidance: fetch folder_id from list_folders, omit folder_id to move to root, and notes the creator-only restriction. There is no explicit when-not-to-use or alternative-tool comparison, 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 only give the safety profile (readOnlyHint false, destructiveHint false); the description goes far beyond, disclosing sandboxing, what is suppressed from Office files, that include_original is off by default because notes/hidden slides/comments leak, the window.SNAPHOST data-usage scan, the external-origin security blocking, and the required owner confirmation.

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 use case, then organized roughly input-by-input, and nearly every sentence carries operational content. It is nonetheless a very dense block with some overlap between the prose and the already-verbose schema (slug, filename, include_original are described twice), so it is not maximally tight.

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 15-parameter write tool with no output schema, the description still reports return values (content_kind, link_expires_at, has_view_password, original_included, render_notices) and explains all modes of input. An agent has everything needed to call it correctly and to relay results.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds cross-parameter and cross-tool meaning: html vs zipBase64 vs upload_id selection, slug idempotency semantics, landing-page slug = address under /lp, and the folder_id/workspace_id coupling. It mostly restates rather than deepens a few fields (allowlist, printable), keeping it out of 5.

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

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

Opens with a concrete verb+object ('Publishes a document or bundle to SnapHost and returns its stable share URL') plus the user-facing intent it serves. It is immediately distinguishable from siblings like update_site, create_bundle_upload, and create_share_link 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?

Explicit triggers ('put a page online, share this with a client or teammate, or get a link they can send') and explicit routing to alternatives: large apps go through create_bundle_upload + upload_id, lone non-zip files via create_bundle_upload with filename, existing sites via update_site, slug for idempotent republish.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds valuable behavioral context: records are append-only, newest-first by default, and each carries a server-stamped actor. It also notes the site scope. These go beyond the annotations without contradicting them.

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

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

The description is four sentences, front-loaded with the most important use cases. Every sentence earns its place: purpose, mechanism, filtering/ordering, actor info, and scope. There is no redundancy or fluff.

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

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

With 7 parameters and no output schema, the description covers the key behaviors (filter, order, limit, actor stamp) but does not describe the response format. The schema explains workspace_id and latest_per_key in detail, so those are covered. The lack of output shape is a minor gap, but the description gives enough context for a query tool, especially with annotations covering 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%, so the baseline is 3. The description adds the default ordering (newest-first) and clarifies that `where` uses field/value equality, which is partially in the schema. It also mentions the `limit` parameter but adds no new semantics beyond the schema. The added default behavior is useful, raising it to a 4.

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

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

The description clearly states the tool's purpose: 'Use when the user asks who signed up, what was submitted, or wants to see the responses' and 'Queries a collection's append-only records'. It identifies the resource (site records) and differentiates from siblings like delete_site_record or set_site_data. The scope 'Scoped to a site you own' further clarifies what it operates on.

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

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

The description gives explicit when-to-use context ('Use when the user asks who signed up...'), but does not mention when not to use it or explicitly name alternatives. It lacks exclusions, but the usage context is clear enough to guide an agent to select this tool over others.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds 'stop serving it', which clarifies the effect. However, it does not mention whether the domain record is deleted or merely detached, nor any side effects or prerequisites, which would be useful context beyond the annotations.

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

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

The description is a single, front-loaded sentence with no redundant words. It conveys the essential action and outcome without any filler, making it highly concise and effective.

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

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

For a simple two-parameter destructive operation with annotations covering safety and no output schema, the description captures the core action but omits details like whether the domain is deleted or just detached, and whether it can be re-added. This minor ambiguity prevents a higher score.

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

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

The input schema already documents both parameters with full descriptions (100% coverage), so the description adds no additional parameter semantics. The baseline of 3 applies because 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 clearly states the verb 'detach' and the resource 'custom domain', along with the consequence 'stop serving it'. It distinguishes from siblings like add_custom_domain and list_custom_domains by explicitly describing the removal 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?

The description offers no guidance on when to use this tool versus alternatives. It does not mention any conditions, exclusions, or contrasts with related tools such as add_custom_domain or verify_custom_domain, leaving the agent to infer usage from the name 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 indicate destructive and idempotent characteristics; the description adds specific context by stating that absent entries are ignored, which clarifies the idempotency behavior and that the operation is non-fatal. This goes beyond the hints and provides useful operational detail.

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 concise sentences with no fluff. The core action is front-loaded, the behavior for absent entries is clearly stated, and the alternative for clearing the list is provided. Every sentence earns its place.

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

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

The description covers purpose, key behavior, and alternative usage. It mentions the scope ('private site's allowlist') and does not rely on an output schema. It could theoretically mention error conditions or required permissions, but for a simple removal tool this is adequate and complete relative to its complexity.

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

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

Schema coverage is 100% and the schema already documents the allowlist parameter as 'Entries to remove'. The description reinforces this by mentioning email/domain (matching the kind enum) and adds the idempotency semantics ('entries that are not present are ignored'), which adds value beyond the schema.

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

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

The description clearly specifies the verb 'remove' and the resource 'specific email and/or domain entries from a private site's allowlist', and distinguishes it from set_allowlist by noting that it leaves everyone else on the list. This makes the purpose unambiguous and distinct from sibling tools like add_to_allowlist or set_allowlist.

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 directs when to use an alternative ('To clear the whole list, use set_allowlist with an empty array') and implies this tool is for targeted removals. It does not explicitly mention conditions like when not to use it or prerequisites, but the given guidance is sufficient for common use cases.

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 annotations, the description discloses meaningful behavior: the slug and every address under the folder remain unchanged, only the dashboard-facing name changes, a manage-level permission is required, and the tool returns the updated folder. This gives the agent a precise mental model of side effects.

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 no filler. The key scoping statement about the slug is front-loaded, and every sentence adds distinct value: what to pass, what stays unchanged, permissions, and return value.

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?

Complete for this tool. It covers required inputs, side-effect scope, authorization, and return value despite no output schema. An agent has everything needed to invoke it correctly and know what to expect.

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

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

Schema description coverage is 100%, so the schema already explains folder_id, name, and workspace_id. The description adds little beyond restating 'pass folder_id and name', though it does reinforce that folder_id comes from list_folders. 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 and resource ('Rename a folder') and clarifies exactly what changes (the dashboard-facing name) and what does not (the slug and addresses). This distinguishes it from siblings like set_folder_slug and rename_site without needing to open their schemas.

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

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

Clearly conveys when to use it: rename the display name while preserving the slug and all addresses, and it sets the permission prerequisite ('Only someone who can manage the folder may rename it'). It implies the alternative for slug changes but does not explicitly name a sibling tool like set_folder_slug.

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

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

Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description goes beyond these by clarifying the specific behavioral nuance that the change is cosmetic and does not affect slugs/links, and explains the edge case about landing page titles depending on the document's <title>. However, it doesn't mention response format or error conditions, but given the annotations, the added value is substantial and no contradictions exist.

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

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

The description is front-loaded with the core purpose and key scoping constraints ('Cosmetic only'), followed by alternative routing. While the landing-page edge case adds some length, it's directly relevant to avoiding incorrect assumptions. The structure is clear and mostly efficient, though the final sentence about return value is somewhat redundant with the schema's implied return.

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

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

The description covers the scope, effects, alternatives, and the tricky workspace_id prerequisite. Since the tool is a write operation but non-destructive, and the output schema is absent, the description could mention the exact structure of the returned 'updated site,' but that's a minor gap. Overall, the definition is comprehensive for the tool's complexity.

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

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

Schema coverage is 100%, so parameters are well-documented in the schema. The description adds value by explaining the workspace_id parameter's nuanced behavior (required on write when multiple workspaces are reachable) and the semantics of the title parameter ('display title' vs. a slug or path). This goes beyond the schema's minimal descriptions, making the tool easier to use 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?

The description clearly states the verb and resource: 'Rename a site's display title by id.' It also explicitly differentiates from siblings by stating what this tool does NOT change (slug, permalink, existing links) and naming the alternative tools (set_site_slug, update_site) for those actions. This makes the purpose unambiguous and distinct from the 40+ sibling tools.

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

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

The description provides explicit when-to-use guidance: it explains that this tool is for cosmetic title changes only, and explicitly states when to use alternatives ('To change the site's link path, use set_site_slug' and 'change that with update_site'). It also clarifies the scope of the effect (what changes, what doesn't), which is critical for correct usage.

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

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

The description states that the rollback 'records a new version' each time it is called, indicating a side effect that changes the site's version history. This directly contradicts the annotation idempotentHint=true, which claims the tool has no side effects when called multiple times with the same parameters. Therefore, the description contradicts the annotations, requiring a score of 1 and an annotation contradiction flag.

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

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

The description is a single, well-organized paragraph that front-loads the usage trigger, then explains the behavioral nuance (content only, address unchanged) and points to list_versions. Every sentence adds value, and there is no unnecessary verbosity.

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

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

The description covers the key behavioral aspects: it restores content, records a new version, leaves slug/folder/visibility unchanged, and notes the share URL behavior. It also provides the version_id source. It does not explain the return value or potential errors, but for a mutation tool without an output schema, this is acceptable. However, the contradiction with idempotentHint leaves a gap in clarity about idempotency, so it is not 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?

The schema already provides full descriptions for all three parameters, including the note that version_id comes from list_versions. The description does not add new meaning beyond what the schema states; it merely repeats the reference to list_versions. Since schema coverage is 100%, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: undo the last update or go back to a previous version by restoring prior content. It uses a specific verb (rollback) and resource (site version), and the behavior of recording a new version distinguishes it from other site-modifying tools like update_site or delete_site.

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

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

Explicitly states when to use: 'when the user wants to undo the last update or go back to the previous version.' It also directs the agent to list_versions to obtain the version_id, providing a clear path to the prerequisite action. This differentiates it from alternatives and gives actionable context.

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

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

The description surfaces important side effects the annotations do not: overwriting drops anyone not in the supplied list, new emails receive invite emails, and a Pro-plan restriction exists except for clearing. These are exactly the behaviors an agent needs to warn the user about. The overwrite language is consistent with idempotentHint=true and readOnlyHint=false, so there is no annotation contradiction.

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

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

The description is front-loaded with the primary use case and every subsequent sentence adds a distinct, non-redundant fact: consequence of overwrite, alternatives, clearing behavior, invite emails, and plan limits. The capitalization of REPLACES/OVERWRITES emphasizes the critical warning without extra fluff.

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

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

For a write operation with no output schema, the description covers selection, side effects, alternatives, edge cases, and plan/gating. An agent has everything it needs to decide to call set_allowlist and to explain the impact to the user.

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 schema already describes both key parameters at 100% coverage, so the baseline is 3. The description adds meaningful extra semantics: the allowlist parameter means the full replacement set, 'Pass an empty array to clear it,' and entries are email/domain kinds. This goes beyond the schema, though it does not need to restate site_id or workspace_id behavior.

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

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

States a precise verb and resource ('set ... allowlist') and immediately clarifies the core semantics: replacing the entire list with the provided entries. It also differentiates from siblings by naming add_to_allowlist and remove_from_allowlist as alternatives, so an agent cannot confuse 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?

Leads with the explicit trigger condition ('Use when the user wants to set exactly who can view, replacing the current list') and gives direct when-not instructions: prefer add_to_allowlist for additions and remove_from_allowlist for removals. Also covers the empty-array clear case and plan constraints.

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 mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), but the description goes well beyond them: it discloses replacement semantics ('Replaces guidelines the workspace has'), a validation step ('SnapHost checks that it answers with a page or a PDF'), and persistence ('every build in the workspace reads it from then on'). Permission/plan gating is spelled out as well.

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 dense paragraph, but it is front-loaded with the core action and every clause carries information (validation, persistence, replacement, permissions, alternative path). Minor cost: the parenthetical enumerations and stacked conditions make it harder to scan than a bulleted form.

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 write tool with full annotation coverage and no output schema, nothing an agent needs is missing: prerequisites, replacement behavior, validation, persistence via get_brand_kit, and the out-of-scope fallback are all stated. Return values need not be described since no output schema exists.

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

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

Schema description coverage is 100%, so the baseline is 3, and the schema already defines both the url and workspace_id semantics. The description still adds real meaning about what the url must point to (a page/PDF constraining logo clear space, imagery, chart drawing, brand voice) and the constraint that offline PDFs are out of scope for this 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?

The description states a precise verb and resource ('Link the active workspace's brand guidelines') and pins down exactly what the resource is ('the https URL of a public web page or PDF that says what the kit cannot hold'). It also names the read-side sibling (get_brand_kit), so an agent understands where the linked value surfaces. The only unaddressed relative is set_brand_kit, but the operation itself 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?

It gives explicit preconditions (workspace owner only, on Pro, in a team workspace, including the otherwise-fixed website workspace) and an explicit alternative path for the case it does not cover ('a PDF that is not online is uploaded on the General page of the dashboard instead'). It even adds a procedural guardrail: 'Confirm the link with the person before calling this.'

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

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

Beyond the annotations, it discloses ownership and plan requirements ('Needs Pro; scoped to a site you own'), the refusal behavior when records_carry_no_personal_detail is false, and the override where waitlist remains append_only. This is valuable behavioral context that annotations alone do not 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: the purpose in the first sentence, then mode semantics, then caveats. Every sentence earns its place and no repeated schema boilerplate appears.

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

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

For a mutating access-control tool with no output schema, it provides everything needed to call correctly: modes, use cases, constraints, requirements, and exception behavior. The optional workspace_id detail remains in the schema, so nothing essential is missing from the description.

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

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

Because schema coverage is 100%, a baseline of 3 applies, but the description goes well beyond it: it explains the access_mode enum with use cases, defines the privacy implication of append_only, and clarifies the sensitive records_carry_no_personal_detail parameter and its owner-confirmation requirement.

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: 'Set who can read a collection from the published page and pause/resume writes.' It then defines the two access modes with concrete examples, making the tool's scope distinct from sibling setters like set_visibility or set_site_data.

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

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

It gives clear context for when each access_mode is appropriate (scoreboard/guestbook vs contact form/waitlist) and states hard constraints: public_read is refused on the marketing site without confirmation, and waitlist stays append_only. It doesn't explicitly name alternatives among sibling tools, but the use-case guidance is sufficient for selection.

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

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

Annotations already indicate write (readOnlyHint=false) and non-destructive (destructiveHint=false) plus idempotent. The description adds significant behavioral context: uniqueness among siblings, the side effect that changing the slug renames every /lp address that ended with the old slug and every one that starts with the new one, and that setting it back restores them. This goes well beyond the annotations.

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

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

The description is dense but not wasteful; every sentence adds value (path explanation, scope constraints, uniqueness, special case, side effects, return). It is front-loaded with the primary action and then details constraints. Slightly long, but all content is relevant.

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 write operation with constraints and side effects, the description is remarkably complete. It covers the path structure, scope restrictions (shared-drive only, Pro only), uniqueness, the special Marketing folder case, the full impact on /lp addresses, and the return value ('Returns the updated folder'). No output schema exists, but the return is stated. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100% with detailed descriptions for all three parameters (folder_id, slug, workspace_id), including optional semantics for workspace_id. The description adds minimal parameter-specific detail beyond what the schema already provides; it focuses on behavioral context instead. 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 states a specific verb ('Rename a folder's link slug') and resource, and provides the full path context (<handle>.snaphost.ai/<folder-slug>/<site-slug>). It clearly distinguishes this from sibling tools like rename_folder (which renames the folder display name) and set_site_slug (which sets a site's slug), even though it doesn't name 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?

The description gives explicit conditions: shared-drive folders only, not personal (My drive) folders, and Pro workspaces only. It also notes the special case of the Marketing folder in the website workspace, which cannot be changed. This provides clear when-to-use and when-not-to-use guidance, effectively routing 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?

The description goes well beyond the annotations (which already indicate a non-read, non-destructive, idempotent operation). It discloses the side effect on landing page and campaign links, plan restrictions, the requirement for edit access, and the fact that rejected requests leave the stored expiry unchanged. This is rich behavioral disclosure that the annotations alone do not 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 a single dense paragraph that front-loads the use case and then delivers the necessary details in a logical order: action, parameters, plan restrictions, permissions, and failure behavior. Every sentence adds value; there is no fluff or redundancy.

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

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

For a write operation with multiple constraints, the description is remarkably complete. It covers when to use it, how to set and clear, plan limitations, permission requirements, effects on related resources, and error behavior. Given there is no output schema, it still gives the agent enough to know what to expect on failure.

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

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

Although schema coverage is 100%, the description adds substantial meaning: it explains the exact ISO 8601 format with an example, clarifies that null removes the expiry, and elaborates on workspace_id usage (when required, when to omit). This goes beyond the schema's terse parameter descriptions, helping the agent use the parameters 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?

The description opens with a specific use case ('stop working after a date, or to keep it up indefinitely') and states the exact action ('Sets or clears an expiry on a site's share link'). It names the resource (site's share link) and the verb clearly, and it is distinct from sibling tools like set_link_status or create_share_link.

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

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

The description explicitly states when to use the tool: 'Use when the user wants the link to stop working after a date, or to keep it up indefinitely.' It also provides plan-specific guidance (Pro only for setting, all plans for clearing) and permission requirements. However, it does not explicitly name alternatives or state when not to use it, so it falls 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?

The description adds significant behavioral context beyond the annotations: enabled:false makes the link 'not available' for everyone, makes /lp answer 404 inside the marketing chrome, suspends custom domains, and does not delete the site; enabled:true republishes it. This aligns with destructiveHint=false and idempotentHint=true, with no contradiction.

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

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

The description is compact and front-loaded with user-facing trigger phrasing. There is slight redundancy between 'Use when...' and 'Takes a site offline or brings it back,' but each sentence contributes either behavioral detail or routing guidance, so it remains efficient.

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 boolean state-changing tool with no output schema, the description covers the essential outcome, side effects, non-destruction, and the fact that this is the only unpublish path. The workspace_id nuance is already fully covered by the schema, and a return-value description is not necessary 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%, so the baseline is 3. The description adds operational meaning to the enabled parameter by detailing what false and true actually do, including the non-deletion and domain-suspension effects. It does not add to site_id or workspace_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 clear action and resource: 'take it down, unpublish it, pause the link, or bring it back' and 'Takes a site offline or brings it back.' It also distinguishes itself from siblings by asserting it is the single way to take a site offline and that no separate unpublish tool exists, so an agent can route to it without ambiguity.

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 specifies when to use the tool ('Use when the user wants to take it down...') and provides an exclusion ('This is the single way to take a site offline; there is no separate unpublish tool'). It does not compare directly with publish_site, but the main alternative confusion is resolved.

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

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

Annotations cover safety (idempotent, non-destructive), but the description adds substantive behavior beyond them: which options are free vs paid (external_origins is Pro), that rejected requests (forbidden/plan_limit/validation_failed) leave stored options unchanged, that omitting a field leaves it unchanged, and that include_original=true is refused.

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

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

Front-loaded with the core purpose before per-field detail, and nearly every sentence carries operational information. It is a dense single block, though, with some overlap against the equally detailed schema descriptions, so it is information-rich but not maximally lean.

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

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

For an 8-parameter mutation tool with no output schema, the description covers defaults, paid-vs-free gating, access requirements, the omit-to-leave-unchanged contract, and named error codes. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description genuinely adds meaning: external_origins entries must be 'bare https://host[:port] with no path', an empty array clears the list, auto_refresh defaults off, and include_original=false re-renders rather than withholding. It exceeds the schema but partly restates existing field docs.

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 (configure how a site is delivered) and scopes it with the qualifier 'without touching its sandbox', which cleanly separates it from content/mutation siblings like update_site and publish_site. Per-field clauses make the tool's remit concrete enough to distinguish from any sibling.

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

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

Names alternatives with the condition that selects them: 'use add_external_origins to add origins without replacing the list' and 'update_site with the file and include_original true instead'. Also states prerequisite access ('Needs edit access... its creator or an editor grant').

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

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

With annotations already indicating readOnlyHint=false, idempotentHint=true, and destructiveHint=false, the description adds useful context: the data is mutable KV read by the published page, values are arbitrary JSON, and writes are 'scoped to a site you own.' This supplements the annotations without contradicting them.

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

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

The description is concise and front-loaded with the trigger condition. Each of its five short sentences contributes a distinct point: use case, operation, storage semantics, value type, and scope, with no filler or redundancy.

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

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

Given a fully documented schema, useful annotations, and no output schema, the description provides enough context for an agent to select and invoke the tool correctly. It covers when, what, and scope, and explains the store's role. Minor omissions such as explicit error behavior or overwrite semantics keep it from being fully comprehensive.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only modest parameter-level context, such as 'value is any JSON' and illustrative examples like 'a price, a deadline, a switch,' which slightly enrich the schema but do not substantially change 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 clearly states a specific verb and resource: 'Sets a key-value item in a site's data store (SnapHost Data).' It also frames the tool's purpose with the use case 'when the page should read a setting or value the owner controls,' which distinguishes it from sibling setters like set_site_slug or set_visibility.

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 opening sentence gives explicit when-to-use guidance: 'Use when the page should read a setting or value the owner controls.' It also explains that the store is 'mutable config/state the published page reads.' However, it does not explicitly name alternatives or state when not to use this tool, 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?

The description discloses several behaviors beyond annotations: the share permalink continues to work, old slug address and campaign links break, slug normalization rules, uniqueness constraint, and the Pro workspace requirement. This is rich behavioral context that goes beyond the provided annotations.

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

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

The description is concise (three sentences) and front-loaded with the main action. Each sentence provides unique information without filler, making it efficient for an agent to parse.

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

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

The description covers the purpose, effects, constraints, and prerequisites. With no output schema, return values are not expected. The description is complete enough for an agent to invoke the tool correctly without additional context.

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

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

The schema already describes each parameter (100% coverage), but the description adds meaning to the slug parameter by explaining normalization and uniqueness, and to workspace_id by mentioning the Pro requirement. This adds value beyond the schema.

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

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

The description clearly states the action ('Change a site's slug') and defines the slug's role in the URL, distinguishing it from sibling tools like rename_site and set_folder_slug. It is specific about what the tool does and what the slug is.

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

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

The description provides context on when to use it (changing a slug) and explains the effects (old URLs stop, permalink continues). It also mentions a prerequisite (Pro workspace). It does not explicitly name alternatives, but the context is sufficient for an agent to understand when to apply this tool.

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

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

Annotations provide only basic flags (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description adds substantial behavioral context: password is hashed at rest and never returned/logged/echoed, re-running changes the value (consistent with idempotent hint), rejected requests leave the stored password unchanged, and specific error types are named. This goes beyond annotations and gives the agent a clear picture of side effects and failure 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 moderately long but every sentence carries relevant information: use case, mechanism, security properties, change behavior, plan constraints, and error handling. It is front-loaded with the primary purpose. While it could be slightly more concise, the density of useful details justifies the length. Structure is logical and clear.

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

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

The tool has 3 parameters (2 required), no output schema, and moderate complexity. The description covers the purpose, when to use it, prerequisites (edit access, Pro plan), behavioral guarantees (hashing, no echo), idempotency, and error outcomes. There is no obvious missing information an agent would need to correctly invoke this tool. It is complete for the given context.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (site_id, password, workspace_id) with their descriptions. The tool description does not add new meaning about parameters beyond what is in the schema, such as the fact that password is never echoed (already in schema) or the workspace_id semantics (also in schema). Baseline 3 is appropriate since the schema handles parameter documentation.

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

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

The description clearly states the tool sets a view password on a site/page, distinguishing it from siblings like clear_view_password and set_visibility. It uses a specific verb ('put a password'), names the resource (page/site), and explains the effect ('Anyone with the link must enter this password before they can view the content'). This leaves no ambiguity about what the tool does.

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

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

The description states the primary trigger ('when the user wants to put a password on the page') and provides practical usage details: re-running with a new value changes the password, Pro plan requirement is noted, and edit-access prerequisites are explained. It does not explicitly contrast with clear_view_password or other alternatives, but the purpose is distinct enough that an agent can infer when to use it. The 'Pro only' and permission conditions are important usage constraints that are clearly 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=false, destructiveHint=false, and idempotentHint=true, so the description doesn't need to restate those. The description adds useful behavioral context by explaining the effect of each visibility value ('public' lets anyone with the link view; 'allowlist' restricts to verified people on the allowlist) and notes that 'allowlist' is Pro only. It does not mention side effects like whether existing share links are affected, but the annotations cover the safety profile and the description adds meaningful value beyond them.

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

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

The description is compact and front-loaded: it opens with the user-intent trigger, then states the action, then explains the two enum values. Every sentence earns its place, and there is no redundant restating of the tool name or schema fields. The 'Pro only' note is a valuable constraint included without bloat.

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-required-parameter tool with full schema coverage and annotations covering safety and idempotency, the description is nearly complete. It explains the visibility values and the Pro restriction, which are the main non-obvious details. It does not describe the return value, but there is no output schema and the tool is a simple setter, so that is a minor gap. The workspace_id nuance is already fully documented in the schema.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the semantic difference between 'public' and 'allowlist' in plain language, which goes beyond the schema's terse '`public` or `allowlist`' enum description. It also clarifies the user-intent mapping, which helps the agent select the right enum value. The workspace_id parameter is fully documented in the schema, so no additional description is needed.

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

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

The description states a specific verb ('Sets a site's visibility') and resource, and clearly distinguishes the two visibility values ('public' lets anyone with the link view; 'allowlist' restricts to verified people). It also opens with user-intent phrasing ('when the user says only certain people should see it, make it private, or open it to anyone with the link'), which makes the tool's purpose immediately recognizable. It is distinct from siblings like set_allowlist and set_collection_access because it focuses on the site-level visibility setting.

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

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

The description explicitly states when to use the tool: 'Use when the user says only certain people should see it, make it private, or open it to anyone with the link.' It also explains the meaning of each visibility value, which helps the agent choose between 'public' and 'allowlist'. It does not explicitly name alternative tools, but the when-to-use guidance is strong enough to route the agent correctly.

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

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

The description discloses the key behavioral nuance beyond the annotations: omitting site_id clears the root and makes it return 404 again, while all other paths continue resolving folder and site slugs. Annotations mark the operation idempotent and non-destructive, and the description aligns with those hints, adding concrete outcome context rather than contradicting them.

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

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

Three tight sentences carry the entire behavioral model: what the tool does, how to clear, and what is unaffected. The most important action is front-loaded and every sentence earns its place.

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

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

For a simple, idempotent write with one required parameter and no output schema, the description is complete: it explains the action, the clearing behavior, and the scope of effect. The one contextual parameter (workspace_id) is already fully described in the input schema, so nothing necessary is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics for site_id by stating that omission clears the root and resets it to 404. It also clarifies domain_id is about a workspace-bound domain; workspace_id is already well 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 opens with a specific verb phrase, 'Choose or clear the ROOT site of a workspace-bound domain,' and pins down the exact resource as the site served at the domain's bare / (e.g. share.acme.com/). This makes it immediately distinguishable from sibling slug/domain operations like set_site_slug or add_custom_domain without needing to open schemas.

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

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

It clearly states the operation's context: setting or clearing the root site of a workspace domain, and explains how to clear by omitting site_id. It does not explicitly name alternative tools or exclusion conditions, but the domain-root use case is distinct enough that the context is unambiguous.

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

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

Goes well beyond the annotations by disclosing what is preserved (URL, visibility, allowlist, link expiry, view password), that a new version is recorded, refresh behavior for open viewers, security-policy scanning of external references, missing-file reporting, and the warning when html replaces a file-rendered site. Idempotency and non-destructiveness are consistent with the annotations.

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

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

The description is long and dense; the final two sentences about collection setup, external origins, and missing files are useful but buried and verbose. Front-loading the user triggers is good, but the run-on structure hurts scannability.

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

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

For a mutation tool with no output schema, the description covers behavioral consequences, preservation guarantees, and failure/reporting paths thoroughly. It doesn't explain the return structure, but the description already references result fields (content_kind, original_included, render_notices) which compensates.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it summarizes the accepted content kinds, notes that filename is for lone non-zip files, explains include_original behavior on update ('leave it out to keep the live version's choice'), and describes content_kind changes. This is meaningfully beyond the schema.

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

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

The description opens with explicit user-intent triggers ('push the new version', 'ship the changes', 'update the page while keeping the same link') and states the core mechanic: 'Replaces a site's content in place by id.' It clearly distinguishes itself from publish_site by emphasizing URL preservation and in-place replacement.

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 opening sentence gives clear when-to-use triggers phrased in user language, and it repeatedly anchors 'same inputs as publish_site', implicitly the alternative. It doesn't explicitly state when NOT to use it (e.g., first-time publishing), but the context is clear.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive, closed-world, but the description goes further: nothing publishes until publish_site/update_site runs, a rejected/damaged part costs only that part, re-sending an index replaces it, and the same workspace_id must be reused. That is genuine failure/recovery and state semantics beyond the annotations.

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

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

Front-loaded with the core action and the routing rationale, and every sentence carries operational content (slicing rule, ordering, publish gate, error recovery). It is, however, one dense paragraph that could be split for scanning; slight verbosity keeps it off a 5.

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

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

There is no output schema, but the description covers validation (bytes verified at publish), failure handling, ordering, the filename/zip distinction, and workspace consistency. An agent has everything needed to call this multi-part writer correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter constraints the schema does not: slices must be base64'd individually, sent as 0,1,2 with no gaps, and part 0 must be the archive's opening bytes unless filename names a lone non-zip file. It also ties workspace_id to create_bundle_upload.

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

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

States a precise verb+resource: 'Send one numbered slice of a .zip, or of a single non-zip file, into an upload opened by create_bundle_upload.' It names the opening sibling and the exact artifact being uploaded, so an agent can distinguish it from create_bundle_upload and publish_site 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 says when to use it ('the route that needs no network beyond the one carrying this tool call, so it is how a sandboxed client publishes...') and names the siblings that bracket the workflow (create_bundle_upload opens, publish_site/update_site finish). Nothing is left to inference.

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

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

The annotations already indicate readOnlyHint=false (write operation), idempotentHint=true (safe to retry), and destructiveHint=false. The description adds the activation aspect, which is useful but doesn't provide additional behavioral detail beyond what annotations state. It doesn't disclose what happens if DNS doesn't resolve or if activation fails, but that's minor given the idempotent and non-destructive hints.

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

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

The description is concise: two sentences, with the action first and a direct usage instruction. Every word adds value, and it is front-loaded with the core purpose before the usage note. No fluff or repetition of schema 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?

The description is sufficient for a two-parameter tool with a clear schema and idempotent annotations. It covers the action, the trigger, and the source of parameters. It lacks details on failure handling or return values, but no output schema exists, so that's expected. It's complete for most agent use cases.

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

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

Schema description coverage is 100%, so the schema already provides full parameter details, including the source of domain_id and workspace_id semantics. The description adds the context that domain_id is from add_custom_domain or list_custom_domains, which reinforces the schema. Since coverage is high, the baseline is 3, and the description's emphasis on the follow-up role earns a 4.

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

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

The description clearly states the tool's purpose: to re-check DNS records and activate a custom domain once they resolve. It uses specific verbs ('Re-check', 'activate') and a specific resource ('custom domain's DNS'). It distinguishes itself from add_custom_domain by implying it is a follow-up action, though it doesn't explicitly name the sibling.

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

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

The description provides clear guidance on when to call this tool: 'Call after adding the DNS records that add_custom_domain returned.' This gives a strong contextual trigger. It doesn't explicitly state when not to use it or mention alternatives like remove_custom_domain, but the primary usage condition is well-defined.

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