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 declare it is a non-readonly, non-destructive, non-idempotent write; the description adds the operational facts an agent actually needs: the upload is single-use and expires, it is workspace-scoped and the same `workspace_id` must be reused across parts and the publish, the return value is an `upload_id` consumed by publish_site/update_site, and that tool calls and the shell do not share a network. No statement conflicts with the annotations (single-use/expiring is consistent with idempotentHint=false).

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

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

Purpose is front-loaded and most sentences carry load-bearing operational detail, but the body is a dense wall of run-on sentences mixing selection criteria, HTTP mechanics, dashboard URLs, and human-fallback instructions. The no-shell dashboard procedure (with full URLs and "Upload a new version" quoting) is long for a section that mostly tells the agent to stop and ask a person, and it dilutes the core call-and-then-publish path.

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 tool with no output schema, this covers everything an agent needs: what content qualifies, what gets returned, which tools consume the result, both byte-transfer mechanisms with their limits (`max_part_bytes`, bundle cap), the expiry/single-use lifecycle, and the workspace-consistency requirement. Nothing material is left to inference for a correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `filename` is "given here once" because the upload remembers it, so parts and publish need not repeat it, and `workspace_id` must be echoed on every upload_bundle_part and the publish call. That cross-tool propagation rule is not derivable from the schema alone.

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

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

Opens with a concrete verb+resource ("Start a bundle upload") and immediately bounds scope to bytes that `html` or `files` cannot carry, enumerating the qualifying cases (built site with binaries, single PDF/docx/pptx/xlsx/image/video/audio) and the disqualifying ones (text, CSS/JS, Markdown, CSV, code). It also names the sibling handoffs (upload_bundle_part, publish_site, update_site) so an agent can place it in the workflow without opening a schema.

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

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

Explicit when-to-use (binary content), when-not-to-use (anything textual belongs in `html`/`files`; without a shell, do not open an upload and do not build base64), and concrete alternatives with selection criteria: upload_bundle_part for no-network shells, PUT to `upload_url` for fewer larger requests, `storage_url` when a single unbounded request is needed. It even tells the agent what failure signals (403 naming the host, a request that never leaves) do NOT mean, and to fall back rather than renegotiate 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?

Annotations only declare destructive/idempotent/readOnly hints; the description goes well beyond them. It discloses that no content is lost, that sub-folders move up and take the next free slug, that old addresses forward until reassigned, and that the response names every ended and started address — genuinely rare, decision-relevant detail for a destructive tool.

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

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

The core consequence is front-loaded well, but the paragraph is dense and somewhat sprawling, and the address-tracking idea is stated twice ('old workspace-host address forwards to its new one' and 'names every address that ended and every one that started'). It is information-rich but not 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 destructive, no-output-schema tool, the description covers preservation semantics, slug reassignment, address forwarding, permission requirements, and the workspace scoping needed to call it correctly. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, with folder_id and workspace_id fully documented in the schema, including the multi-workspace requirement. The description adds no syntax or format detail about the parameters, so the baseline 3 applies where the schema does the heavy lifting.

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

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

States a specific verb+resource up front ('Delete a folder') and immediately scopes it by explaining that contents survive and move to the parent. An agent can distinguish this from move_folder, rename_folder, set_folder_slug, and delete_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?

It provides a permission prerequisite ('Only someone who can manage the folder may delete it') and notes the Marketing-folder special case, which is useful usage context. However, it never says when to choose this over alternatives like move_folder or move_site_to_folder when the goal is reorganization rather than removal, so routing guidance is only implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them by naming what is destroyed (content, version history, records, collections, share-link viewability, address forwarding) and stressing irreversibility ('nothing can read any of it back afterwards'). That is precisely the extra context annotations cannot convey.

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

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

Effects are front-loaded in the first sentence, guidance and the alternative follow in order of need, and no sentence is filler. The length is justified by an irreversible destructive operation.

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

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

With no output schema and only two parameters, the description carries what matters: full blast radius, irreversibility, pre-deletion reads, and the correct tool for a superficially similar problem. Nothing an agent needs before calling a destructive delete is missing.

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

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

With 2 parameters at 100% schema description coverage, the schema already fully documents site_id and the workspace_id scoping rules. The description adds only the phrase 'by id' and no additional syntax or format detail, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource ('Delete a site by id') and immediately enumerates the concrete consequences (marks deleted, purges content and version history, removes records/collections, breaks share links and forwarding). An agent can distinguish this from sibling mutations like delete_collection, delete_folder, or rollback_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?

It gives explicit prerequisites ('read what matters first: list_site_collections ... then get_site_content and export_site_data') and an explicit when-NOT clause with a named alternative ('Not a way to fix a broken address: create_share_link ...'). This is exactly the when/when-not/alternative guidance the dimension asks for.

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 declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety is covered. The description still adds value annotations cannot: it specifies what is destroyed (everything queued, no further posts) and the authorization requirement ('Workspace owners and admins only'). It does not cover reversibility or error/partial-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?

Very short and front-loaded: destruction behavior first, then usage, then permissions. The middle sentence is an elliptical fragment, which slightly hurts readability but wastes no words.

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

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

For a destructive, no-output-schema tool, the description covers the essentials an agent needs: scope of deletion, irreversible effect on queued items, alternative ordering with register_webhook, and the permission gate. Only minor gaps (reversibility, failure modes) remain.

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 webhook_id and workspace_id are already fully documented, including the multi-workspace requirement. The description adds no parameter-level 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?

States a specific verb+resource ('Removes a webhook') and adds scope ('everything queued for it; nothing is posted to it again'), making it distinguishable from register_webhook/list_webhooks in the sibling set. 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?

Gives concrete situations ('To stop a disabled webhook for good, or to replace an endpoint') and routes the agent to the correct sibling order ('register the new one first'). No explicit when-not-to-use, and the second sentence is a fragment rather than framed as guidance, but 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 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 readOnly/idempotent/non-destructive, yet the description adds substantial context beyond them: the two kit kinds and their token namespaces, the `guidelines` fallback with precedence rules ('let the kit win where they disagree'), the non-blocking nature of `brand_warnings`, and the no-kit return shape. This is rich behavioral disclosure for a read tool.

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

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

Purpose and the 'call before building' directive are front-loaded, and the dense sentences each carry distinct information about return shape and precedence. It is long, but the length is earned by an undocumented return structure; slight trimming would still help readability.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: both kit kinds, their fields, tokens_css usage, guidelines, warnings, and the empty case. An agent has everything needed to call it and act on 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?

Only one optional parameter and schema description coverage is 100%, so the schema already fully documents workspace_id (including personal-space fallback). The description adds a mild contextual hint ('the workspace_id you were asked to publish in') but no syntax or format detail beyond the schema, which is the baseline-3 case.

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

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

States a specific verb+resource ('the active workspace's brand kit') and immediately differentiates from the write sibling by describing the read shape, including the empty case (`has_brand_kit: false`). An agent can tell this apart from set_brand_kit/set_brand_guidelines without opening either schema.

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

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

Explicitly instructs when to call it ('BEFORE building or restyling any page, report, deck or dashboard') and with which argument ('the workspace_id you were asked to publish in'). It also gives downstream actions: read guidelines where the kit is silent, fix every `brand_warnings` entry before reporting done. 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?

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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds no behavioral context beyond that — no permissions, error conditions, or visibility scoping rules — its content is entirely return-field enumeration.

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 in the first clause, which is good, but everything after it is a single sprawling sentence packing a dozen returned fields with parenthetical asides. It would read far better as a short purpose line plus a structured list of returned fields.

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

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

With no output schema, the description carries the full burden of telling the agent what comes back, and it does so thoroughly — field names, types (ISO or null), and derived values like link_status are all disclosed. It falls short only on error/permission behavior and on not distinguishing itself from get_site_content.

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

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

Schema description coverage is 100%, so both site_id and workspace_id are already documented, including the multi-workspace write rule and personal-space default. The description adds no parameter-level meaning beyond the schema, making the baseline 3 correct.

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 verb+resource is unambiguous ("Get a single site's status, visibility, current version metadata..."), which cleanly separates it from list_sites and from content-oriented siblings like get_site_content. It never names a sibling explicitly, so an agent must infer the boundary rather than being told it, which keeps this short of a 5.

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

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

There is no when-to-use, when-not-to-use, or alternative-naming guidance anywhere in the text. The schema hints at list_workspaces for the workspace_id value, but the description itself offers no routing help between get_site, get_site_content, and 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 already declare readOnly, idempotent, non-destructive, but the description adds substantial context beyond them: the inline vs base64 encoding split by content type, the presence of `content_type`, `content_kind`, and `content_hash`, and the important caveat that a non-html `content_kind` returns a rendered page rather than the source file, surfaced in `note`. It also discloses the refusal behavior for `original`.

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

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

The purpose and the sibling distinction are front-loaded in the first clause. The remainder is dense with long parenthetical lists (Markdown, notebook, Word, PowerPoint, Excel...) that border on exhaustive but each conveys a distinct behavioral fact. Slightly heavy, but nearly 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?

There is no output schema, so the description carries the full burden of explaining return values, and it does: encoding, content_type, content_kind, content_hash, note, and the rendered-vs-source distinction. An agent has everything needed to call it and interpret the response, including the follow-up path via update_site.

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

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

Schema coverage is 100%, so baseline is 3, but the description meaningfully enriches `original` by explaining what it returns (the uploaded .pptx/image/CSV rather than the rendered page), its precondition, and its failure mode. The `site_id` and `workspace_id` parameters are left to their schema descriptions, which is reasonable given full 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?

States a specific verb and resource ('Fetch a site's current entry document by id') and immediately distinguishes itself from get_site and list_sites, which 'return only metadata, never the body'. An agent can select this tool without ambiguity among the three read siblings.

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

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

Explicitly frames the tool as 'the read half of the round-trip' and directs the agent to update_site to push changes back, with guidance on how to send text vs binary sources. It also gates the `original` parameter on a condition (the page offering the file for download, signalled by get_site's `original_included`) and states it is refused otherwise. Lacks only explicit when-not-to-call guidance for the plain-page case, which is implicitly covered.

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

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

Annotations already 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 declare the safe read-only profile, and the description adds valuable context beyond them: secrets are never returned (data-exposure behavior), the disabled-after-failed-deliveries state and consecutive-failure count are surfaced, and access is restricted to owners/admins (auth requirement). These are exactly the behavioral disclosures the annotations do not carry.

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

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

A single sentence that front-loads the verb and resource, then the returned fields, then the two key constraints (no secrets, admins only). Zero filler; every clause earns its place.

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

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

No output schema exists, so the description carries the return-value burden and does so by enumerating the fields and states returned. Combined with the annotation safety profile and permission gating, an agent has everything needed to call and interpret this read 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?

Only one optional parameter (workspace_id) and its schema description is fully detailed at 100% coverage, so the schema already carries the semantics. The description's 'in this workspace' phrasing mildly reinforces scope but adds no new parameter 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?

States a specific verb (List), resource (webhooks), scope (this workspace), and even enumerates the returned fields (address, events, active/disabled state, failure count). An agent can immediately tell this apart from register_webhook and delete_webhook without opening any schema.

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

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

Usage is implied by the listing verb and the 'Workspace owners and admins only' audience constraint, which does gate use. However, there is no explicit when-to-use guidance or reference to alternatives such as register_webhook/delete_webhook or when to prefer a filtered query.

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?

Annotations only say it is a non-destructive, idempotent write; the description goes far beyond, disclosing slug re-generation on collision, page address re-hosting with old-address forwarding, and the Marketing-folder side effect (pages published live, folder opened to the whole workspace as editors, addresses ending). It even explains recovery ('move it back to restore them'), which is exactly the behavioral depth an agent needs for a mutation.

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

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

The scoping sentence is front-loaded, but the body is one very long, dense paragraph bundling slug, forwarding, and Marketing side effects, which is hard to parse and buries the actionable constraints. Much of it earns its place, but the structure costs readability.

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

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

For a mutation tool with no output schema, it covers return ('the updated folder'), required workspace context on writes, destination semantics, and irreversible-looking side effects with their remedy. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents space, folder_id, parent_id, and workspace_id. The description adds only the provenance hint (both ids from list_folders) and restates the parent_id-omission rule already in the schema, so baseline 3 applies.

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

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

The opening verb+resource phrase 'Re-parent a folder' is precise and immediately distinguishes this from rename_folder, delete_folder, and move_site_to_folder. An agent can tell what it does without opening the schema.

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

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

It states concrete preconditions and edge cases: pass folder_id and parent_id both from list_folders, omit parent_id to move to the drive root, and it cannot be moved into itself or a descendant. It never explicitly routes to a sibling alternative, 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?

Well beyond the annotations (which only say non-destructive, idempotent, closed-world), the description discloses the creator-only permission gate, visibility reconciliation across personal/shared folders, forwarding of the old address, automatic numbered-slug fallback on address collisions, and the public landing-page consequences. These are exactly the side effects an agent could not infer from structured fields.

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

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

The core action and its scope are front-loaded in the first sentence, and each subsequent sentence carries non-redundant information. The final sentence is dense and slightly convoluted in its /lp/<folder>/<slug> aside, which costs some readability.

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

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

With no output schema, the description compensates by stating what is returned (the updated site read model with new folder_id) and where the tool reports a slug reassignment or new /lp address. Permissions, collisions, and side effects are all covered for a mutation tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning about what folder targeting does — visibility reconciliation between drive types and the /lp/<slug> address implications of filing into the marketing folder. It does not mention the `space` or `workspace_id` parameters directly, so it only partially exceeds 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?

"File a site into a folder, keeping its share link" gives a specific verb, resource, and a preserved-invariant, making it trivially distinguishable from move_folder, rename_folder, and set_site_slug. An agent can identify the operation from the first clause alone.

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

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

Explicit conditions are given: pass a folder_id from list_folders, or omit it to return the site to the drive root, and "Only the site's creator can move it" rules out cases an agent cannot perform. No sibling tool is named as the wrong alternative (e.g. move_folder for folders), so it stops just short of a 5.

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

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

The description provides extraordinary behavioral transparency, detailing operational mechanics like sandboxing, content kind detection, Drive placement logic, and security scanning for external references, none of which are covered by the schema or 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?

While the critical information is present, the description is overly verbose and dense, mixing high-level operational goals (e.g., sharing with a client) with highly specific, technical constraints (e.g., control character byte counts). It suffers from information overload and lacks a logical flow for quick reference.

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

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

Given the high complexity and the large number of interacting parameters, the description is highly complete. It addresses persistence, accessibility, and security policies, providing all necessary context for a correct invocation.

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

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

The description adds vital semantic meaning to several parameters, especially `html`, `files`, and `zipBase64`, specifying technical constraints like file size limits, encoding nuances, and required component libraries for specific formats. This is critical context that the schema alone cannot convey.

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

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

The description immediately defines the core purpose (publishing a page, creating a shareable link) and clearly sets it apart from sister tools by focusing on content submission and URL generation. It successfully establishes the primary 'why' for this complex tool.

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

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

It provides exceptional usage guidelines by contrasting the four primary content input methods (`html`, `files`, `zipBase64`, `upload_id`) and explicitly guides the user on when to use them versus when to update an existing site via slug idempotency.

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?

Goes well beyond the annotations (write, non-idempotent, non-destructive) by disclosing the one-time signing secret, the required permission level, the HMAC-SHA256 signature scheme and headers, the retry schedule (five retries over ~15 hours), and automatic disabling of persistently failing webhooks. These are exactly the behavioral traits an agent cannot infer from structured fields.

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

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

Front-loads the use case before diving into mechanics, and every sentence carries actionable content (secret handling, signature verification, retry/dedup semantics). It is dense and long, but nothing reads as filler; the length is justified by the integration details a caller needs.

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

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

With no output schema, the description carries the return-value burden and does so: it explains the one-time secret in the result, the delivery payload shape, and failure/retry behavior. Nothing essential for calling or consuming this webhook registration correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents url, events, and workspace_id, and the baseline is 3. The description mentions subscribed events and the site.viewed payload fields but adds no syntax or format detail for the parameters themselves 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?

States a specific verb (registers) and resource (an https endpoint for webhook deliveries) plus the exact triggering condition (user wants their system told when someone opens a site). An agent can distinguish it from list_webhooks and delete_webhook 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?

'Use when the user wants their own system told when someone opens a site in this workspace' gives a clear when-to-use context, and the owners/admins-only restriction narrows applicability. It stops short of explicitly naming the sibling alternatives (list_webhooks, delete_webhook) it is mutually exclusive with.

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

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

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?

Annotations already flag destructiveHint=true and idempotentHint=true, and the description goes well beyond them: it states exactly what breaks ('Links to the address stop opening the site'), that the effect is irreversible except by re-assigning the address, and it instructs the agent to confirm with the user first. This is precisely the extra context annotations cannot convey.

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

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

Two sentences, front-loaded with the action and effect, followed by sourcing and the irreversibility warning. Every clause earns its place 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?

With annotations carrying the safety profile and no output schema needed for a void-return mutation, the description supplies everything an agent needs: what the tool does, where the input comes from, that the effect is destructive and non-reversible, and that user confirmation is expected.

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 genuine meaning by defining what qualifies as an 'old address' and pointing to get_site/set_site_slug as the sources, which the schema alone does not establish, though it adds nothing about the workspace_id parameter.

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

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

States a specific verb ('stop') and resource ('old address forwarding to a site') and immediately names the effect ('leaving the address free for any site to take'). An agent can distinguish this from siblings like rename_site, set_site_slug, and remove_custom_domain 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?

Tells the agent where the old addresses come from ('the `old_addresses` of get_site, and what set_site_slug reports after a rename'), which is the key precondition for calling it correctly. It does not explicitly name a competing tool 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?

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?

Goes well beyond the annotations by disclosing that only content is restored while slug, folder, visibility and /lp address are untouched, that a new version is recorded, and how the share URL and open viewers behave (Refresh prompt, landing page on next load). This is exactly the extra context annotations cannot convey.

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

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

Front-loaded with the trigger, then the semantic constraints. Sentences are dense and long in the middle section, but each carries non-obvious behavior (address forwarding, viewer refresh) 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?

With annotations covering the safety profile and no output schema required, the description supplies everything an agent needs: when to call it, what state changes, what is preserved, and the prerequisite lookup for version_id.

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

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

Schema coverage is 100% and both required parameters plus workspace_id are documented in the schema. The description's only parameter note ('use list_versions to find the version_id') restates the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Restores a prior version's content as the site's current content') and clarifies the mechanism (records a new version). It is clearly distinguishable from update_site, delete_site and list_versions.

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?

Opens with an explicit trigger ('Use when the user wants to undo the last update or go back to the previous version') and routes the agent to `list_versions` for the version_id and to `set_site_slug` when the address also needs restoring. Both the when and the alternatives are named.

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

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

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?

Annotations only declare the safety profile (write, idempotent, non-destructive). The description adds genuinely new behavior: SnapHost fetches and re-hosts logo/mark assets so returned asset URLs are never the source, a first save requires a logo while later saves retain existing assets, warnings (low contrast) must be relayed, and the operation is owner/admin gated on Pro. This is substantive disclosure beyond structured fields.

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

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

The core action and its constraints are front-loaded, and the long run-on list of roles/style keys mirrors the schema rather than adding to it. For a 15-parameter tool the length is defensible, but a few clauses (the full colour enumeration, the style read-off) restate structured data and could be trimmed.

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

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

There is no output schema, and the description compensates by telling the agent what comes back (warnings to relay) and what to do with them. Combined with permission requirements, asset-hosting behavior, first-save vs later-save semantics, and defaults, an agent has everything needed to invoke this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: a 1 MB size ceiling on logo/mark URLs, that positive/negative may be omitted and receive sensible defaults, that font names are system or Google Fonts families, and the neutral default for a missing `style`. It does repeat the colour-role and style-enum semantics already present in the schema, which caps it at 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 a specific verb+resource+scope: 'Save the active workspace's brand kit, replacing the one it has', then enumerates exactly what the kit contains. It explicitly distinguishes itself from the sibling set_brand_guidelines ('the brand guidelines themselves... are set apart'). An agent can separate it from get_brand_kit and set_brand_guidelines 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?

It gives explicit when-to-use ('Build it from what the person gives you... show it to them as a table and get a yes BEFORE calling this'), names the alternative for the related resource, and states prerequisites ('Owner or admin only, on Pro'). Nothing about selection or preconditions 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?

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?

Adds substantial behavior beyond the annotations: slug uniqueness among siblings, the side effect that every contained page gets a new address while the old one forwards 'until another page takes it', and the reversibility note ('set the slug back to restore them'). Annotations cover safety/idempotency, and the description supplies the real consequential 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?

Purpose and constraints are front-loaded in the first three sentences, and most sentences earn their place. The trailing 'Marketing folder' example is quite long and niche for a general reader, slightly diluting focus.

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 rename-with-redirect-semantics tool with no output schema, the description covers scope, prerequisites, side effects, and reversibility, and notes the return ('Returns the updated folder'). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both required params and the optional workspace_id are already documented in the schema. The description's folder-path illustration lightly clarifies what 'slug' means but adds no syntax or format detail beyond the structured fields, so baseline 3 applies.

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

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

States a specific verb+resource ('Rename a folder's link slug') and immediately disambiguates the concept by defining the slug as the path segment in folder-path addresses. This cleanly separates it from rename_folder (name) and set_site_slug (site), so an agent can pick the right tool without reading schemas.

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

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

Gives explicit when/when-not constraints: 'Shared-drive folders only: personal (My drive) folders... never appear in links' and 'Pro workspaces only'. Strong exclusion guidance, though it never names the adjacent alternative tools (e.g. rename_folder, move_folder) as the selection cue.

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?

Goes well past the annotations (readOnly=false, idempotent=true, destructive=false) by disclosing that the nanoId permalink survives, the old workspace-host address forwards, and that /lp addresses and campaign links to them break. It also documents normalisation rules, the conflict-refusal path, and the plan requirement. Minor tension with destructiveHint=false exists since lp/campaign links stop resolving, but that is an expected consequence of a rename rather than data destruction.

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

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

Front-loaded with the core action and its definition, and every clause carries information (forwarding, breakage, normalisation, refusals, plan). The single dense paragraph is long and clause-heavy, which slightly hurts scanability, but nothing is filler.

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

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

For a mutation tool with no output schema, the definition covers the side effects, conflict handling, retry path, workspace_id scoping, and plan prerequisite an agent needs to call it safely. Nothing material is left unspecified.

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 operational meaning beyond the schema: replace_forward is framed as 'stop that forward' only after user agreement, and slug is characterised by its normalised character set and collision refusal. Useful augmentation on top of an already documented 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 ('Change a site's slug') and immediately defines the slug as 'the last segment of its address on the workspace host', which implicitly separates it from rename_site and set_folder_slug. An agent can identify the operation and its scope without opening the schema.

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

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

Gives clear conditional guidance: ask the user then retry with replace_forward when the address is still forwarding, and notes the Pro-workspace prerequisite. It stops short of explicitly contrasting with sibling tools (rename_site, update_site, set_folder_slug) or stating when a slug change is inappropriate.

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.