vibedeploy

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds key behavioral details: the action is not synchronous ('returns immediately'), cleanup is best-effort, and the sweeper will retry on failure. This provides useful transparency.

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

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

The description is extremely concise with two sentences, no fluff, and front-loaded with the primary action. Every sentence adds 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?

Given the presence of an output schema and annotations, the description sufficiently covers the purpose, behavior, and effects. It could mention possible errors or prerequisites, but overall it is adequate for this simple 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% for the single parameter 'deployId', which has a schema description. The tool description does not add additional semantic meaning beyond what the schema already provides, so it meets the baseline expectation.

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 'Discard' and the resource 'a staging session and its scratch dir.' It distinguishes itself from sibling tools like commit_deploy or deploy_site by focusing on aborting a session.

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 that the live site is untouched, implying it's safe to use without affecting production. However, it does not explicitly mention when to use this tool over alternatives or provide exclusion criteria.

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 idempotentHint and non-destructiveHint. Description adds that the tool returns a TXT record and the user must add it at their DNS provider. Also notes the required follow-up step. Could mention potential errors if domain already attached, but overall solid.

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?

Description is concise, front-loaded with the main action, and structured into few sentences. Some redundancy with annotations (idempotent statement), but not wasteful.

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 output schema exists, description adequately covers prerequisites, return value (TXT record), and next steps. For a two-step domain attachment process, it is complete enough.

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 descriptions. Description adds example values and clarifies that domain must be a valid FQDN and siteName is a VibeDeploy site name, but does not significantly enhance 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 clearly states it is the first step of attaching a custom domain to a site, and returns a TXT record for DNS validation. It distinguishes from sibling tools like verify_custom_domain and remove_custom_domain.

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

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

Explicitly specifies prerequisites (site must exist on platform subdomain, else call deploy_site first), recommends calling verify_custom_domain after DNS propagation, and highlights idempotent behavior. Guides the agent on when and how to use.

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

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

Discloses that isFirst truncates and creates directories, isLast returns assembled size, and concurrent chunks corrupt the file. Provides practical chunk size guidance and server limits. No contradiction with annotations.

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

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

Well-structured with problem, alternatives, then detailed procedure. Slightly long but every sentence is informative.

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?

Provides complete guidance for a complex streaming tool, covering usage, behavior, parameters, and limits. Output schema exists (not shown) so return values need no explanation.

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%, but description adds practical advice (e.g., chunk size bounds, encoding per-chunk, alignment check) that goes beyond the schema.

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

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

The description clearly states the tool streams a single file across multiple calls when content exceeds the per-MCP-call output budget. It distinguishes from siblings like add_files, deploy_from_url, and begin_deploy by framing itself as a last resort.

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 lists three alternatives with reasoning and says 'Only chunk when none of those work.' Also advises sending chunks serially to avoid corruption.

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 (idempotent, not destructive), the description reveals: cumulative 500 MB cap, per-call validation with fast fail, file overwrite on re-add, and detailed encoding behavior with compression ratios. It discloses all important behavioral traits without contradicting 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 core purpose and includes multiple paragraphs. While dense, every sentence adds value (usage guidance, encoding advice, comparisons). It is not overly terse but efficiently packs necessary information, slightly exceeding minimum conciseness.

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 (encoding options, sibling comparisons, cumulative cap) and the presence of an output schema (so return values need not be explained), the description covers all essential aspects: purpose, usage guidance, limitations, encoding details, and alternatives. No gaps 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?

With 100% schema coverage, the description adds substantial value: it explains encoding compression ratios (gzip+base64), cumulative file-size cap, path overwrite semantics, and the wire-shape alternatives. It enriches the schema with practical, actionable context.

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 'Append files' and the resource 'open staging session'. It differentiates from sibling tools like add_file_chunk by explaining when to prefer add_files over chunking, and also mentions begin_deploy's uploadUrl for large payloads. The verb-resource pair is specific and distinct.

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 and when-not-to-use guidance. It advises preferring add_files over add_file_chunk for files compressible to ~250 KB or less, and only chunking when necessary. It also notes begin_deploy's uploadUrl as a faster alternative for large tarballs. This helps the agent choose correctly.

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

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

Beyond annotations (destructive hint), the description adds that edits are atomic, validation runs first, writes only proceed if all count checks pass, and count semantics, providing valuable 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?

Two sentences, front-loaded with purpose, no wasted words, and well-structured for quick comprehension.

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

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

Given the tool's complexity (batch, atomic, count logic), the description covers validation, atomicity, and sibling reference. An output schema exists, so return values are handled.

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

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

Schema coverage is high (67%), and the description reinforces batch semantics and constraints (max 25 files/200 edits) but adds limited new parameter-specific 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 clearly states 'Apply find/replace edits across MANY files in one tool call' and identifies it as the batch sibling of update_file_content, distinguishing it from the single-file 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?

The description explains when to use this tool (batch edits) and provides details on validation and atomic behavior, though it could explicitly state to use update_file_content for single-file edits.

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 critical behavioral context beyond annotations: session limits, TTL, that it does not create sites, and the staging nature. No contradiction with annotations (readOnlyHint=false matches 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?

Four sentences, front-loaded with purpose, then usage sequence, then constraints. Every sentence adds value without 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 the multi-step deploy complexity, the description covers: when to use, required next steps, constraints, and output (uploadUrl). Output schema exists, so return values are already documented. Complete for the tool's role.

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 both parameters with descriptions already. Description adds clarity: explains 'replace' vs 'patch' modes in detail and clarifies 'name' must refer to an existing site. Adds meaningful context beyond schema.

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

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

The description clearly states the tool opens a staging session for multi-call deployments, distinguishing it from single-call tools like deploy_site or update_site. It identifies the specific use case of large sites.

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

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

Explicitly provides when to use (site too large for single call), step-by-step pairing with add_files or tarball then commit_deploy, and constraints (session limit, TTL). Lacks an explicit when-not-to-use for small sites, but overall strong guidance.

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

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

Beyond annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description adds critical behavioral details: hardened one-shot pod, no SA token, no DB/Vault reach, NetworkPolicy-restricted egress, and atomic swap. These details enhance the agent's understanding of the tool's security and operational characteristics.

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 (4 sentences) with front-loaded action. Each sentence adds value: the process, isolation guarantees, and state persistence. No redundant information.

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

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

Given complexity (6 params, no required ones, output schema present), the description covers the core process, statefulness, and security context. It lacks details on output format or error handling, but the presence of an output schema mitigates the need to describe return values. Slight gap: no mention of rollback or failure scenarios.

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 67% schema description coverage, the description adds meaning by explaining that buildCommand and outputDir can be omitted in subsequent calls after the first run persists them into Site.sourceManifest. This clarifies the stateful nature of the tool. However, parameters name and siteId are not elaborated beyond the schema.

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

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

The description clearly states the tool's action: build the editable source tree in a hardened pod and atomically swap into the live dist. It distinguishes from siblings like 'commit_deploy' and 'begin_deploy' by specifying the isolation guarantees and the integration with source writing 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 implicit guidance: use after writing source files via write_source_files or list_source_files autoPromote. It mentions that the first run persists settings for subsequent calls. However, it lacks an explicit comparison to alternatives like deploy_from_url or commit_deploy, and does not specify when NOT to use 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds critical details: the price is indicative, gross (21% VAT), and the exact list of TLDs for alternatives. No contradictions.

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

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

The description is three sentences, front-loaded with purpose, and every sentence provides essential information without redundancy. Perfectly concise.

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 tool, the description covers purpose, behavioral caveats, parameter usage, and authentication context. It leaves no gaps.

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

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

Schema description coverage is 100%, and the description enriches parameters by specifying the exact TLD list for 'alternatives' and providing an example for 'domain'. This adds value beyond the schema.

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

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

The description explicitly states the verb 'check' and the resource 'domain availability with indicative price', clearly distinguishing it from sibling tools that perform mutations like 'add_custom_domain' or 'deploy_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?

The description clarifies this is a read-only lookup, does not register domains, and explains when to use the 'alternatives' parameter. It also mentions token requirements. However, it does not explicitly contrast with other tools, but the sibling set makes the distinction 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 destructiveness (destructiveHint: true) and non-idempotency. The description adds atomicity, preflight/scan steps, session preservation on failure, and dryRun preview behavior. Missing details like return values or rate limits, but output schema covers returns.

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, each conveying essential information: atomic apply, scan/failure behavior, and replace-mode confirm requirement. No redundancy or filler.

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

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

Covers core behavior well. Assumes familiarity with 'staging session' (sibling begin_deploy) but output schema exists to explain returns. Could mention that deployId comes from begin_deploy, but overall sufficient for a well-structured 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 schema already documents all parameters. The tool description adds no significant extra meaning beyond what schema provides; it merely reiterates confirm constant and dryRun preview. 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 clearly specifies the action (atomically apply staging session to live site), distinguishes from siblings like abort_deploy and begin_deploy by mentioning staging session and preflight/scan behavior. It also addresses replace-mode specifically.

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

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

Provides clear context on when to use (after begin_deploy, for committing) and notes the confirm requirement for replace-mode. However, it does not explicitly mention alternatives (e.g., abort_deploy for failure handling, build_and_deploy for direct deployment) or exclude certain 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?

The description adds meaningful behavioral context beyond annotations: it notes the tool is additive, runs retention cleanup, restricts viewers, and returns NO_VOLUME if the site has no volume. While annotations indicate destructiveHint=true, the description clarifies the primary action is non-destructive to served files, though cleanup may delete old snapshots. This is a nuanced addition.

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 at four sentences, each adding distinct information: action, additive nature, side effects, restrictions, and error condition. Some repetition exists between the first two sentences, but overall it's efficient and 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 description covers the tool's core behavior, side effects, and a specific error condition. However, it omits details about the output schema (though present but not shown) and leaves the parameter semantics incomplete. For a backup creation tool, it provides adequate but not thorough 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?

With only 33% schema description coverage, the description should compensate for undocumented parameters. It adds no information about the 'name' or 'siteId' parameters, and the 'label' parameter is already described in the schema. The description fails to explain the purpose or constraints of these 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 clearly states the tool creates a point-in-time Longhorn snapshot of a site's served files. It distinguishes itself from sibling tools by specifying it's a manual backup, is additive, and does not alter served content. The mention of viewer restrictions further clarifies its purpose.

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

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

The description implies usage for creating backups but provides no explicit guidance on when to use this tool over alternatives or when not to use it. It mentions a return condition (NO_VOLUME) but lacks comparative context with other tools like list_snapshots or deploy.

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 non-readonly, but the description adds detailed behavioral context: immediate soft-delete, freed hostname, pending purge, and response fields (accepted, purgesAt). Fully discloses what happens 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?

Two sentences with no filler, efficient and front-loaded with the core action and key constraints. 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?

Covers the deletion flow, immediate and long-term effects, and response fields. For a soft-delete tool with an output schema (mentioned), this is sufficiently complete for an agent to use 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 only 33% (confirm has description). The description explains confirm=true is required and its role, but does not explain name or siteId. It adds value for confirm but leaves other params undocumented, partially compensating for low coverage.

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

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

The description clearly states it is a soft-delete for a site, describes immediate effects (hostname freed, stops serving) and eventual purge. It distinguishes from other deletion tools like delete_source_file by specifying it's for the entire site.

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

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

Explicitly says 'Use this for the normal remove this from my dashboard flow', providing clear context for when to use this tool. Though it doesn't mention alternatives, the sibling list includes many tools, and the usage context is well-defined.

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 destructive and idempotent hints; the description adds that the served dist is unaffected, which is non-obvious behavioral context 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?

Two concise sentences with no unnecessary information, effectively front-loaded with purpose and key behavioral note.

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 delete tool, the description covers core behavior and consequence (dist unchanged); missing permission or reversibility details but acceptable given 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 has 3 parameters with only path described; the description adds no parameter information, leaving ambiguity about 'name' and 'siteId' despite low schema coverage (33%).

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 'Remove one file from the site's editable source tree' and distinguishes it from affecting the served dist, which is unique among 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?

No explicit when-to-use or alternatives, but the clarification that the dist is unchanged implies a distinction from other deletion operations.

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 open-world behavior. The description adds value by detailing the server-side fetch, max size/timeout, and hostname allowlist. No contradiction with annotations.

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

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

The description is concise (~100 words) and front-loaded with the main action. Each sentence adds distinct information without 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?

Given the presence of output schema and annotations, the description covers the essential behavioral details, use case, and parameter constraints. It could briefly mention authentication or site existence prerequisites, but overall is sufficient for an agent to use 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%, baseline 3. The description adds meaning by explaining the mode semantics ('replace wipes live dist, patch merges') and providing extensive host allowlist context for archiveUrl. This goes beyond the schema descriptions.

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

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

The description clearly states 'Publish a website to a live URL from a public archive link' and distinguishes from sibling tools by noting it combines three steps into one call. It also specifies the exact use case of bypassing upload endpoint restrictions, making the purpose 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 provides context on when to use (when sandbox can't reach upload endpoint) and the alternative workflow (begin_deploy + POST + commit_deploy). However, it lacks explicit exclusions or when-not-to-use guidance, though the positive guidance 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 mark destructiveHint=true and idempotentHint=true. The description adds critical behavioral details: it replaces every file, deletes omitted files, requires a specific confirm string to proceed, and explains large file handling (gzip+base64). All consistent 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 lengthy but well-structured and information-dense. Every sentence serves a purpose (purpose, switching sibling, destructive behavior, confirm requirement, large file tip, post-deploy step). Slight redundancy in the subdomain mention, but overall 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?

Given the tool's complexity (create vs replace, destructive, large files, custom domain post-deploy, dry run), the description covers all essential usage patterns. It also references the output schema implicitly (return shape mentioned for dryRun). No gaps for an agent to misuse the tool.

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

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

Schema coverage is 100% (all parameters documented). The description adds value beyond the schema: it clarifies the two forms of the 'files' parameter (array vs. map) with binary vs. text guidance, provides large file optimization advice using 'gzip+base64', and explains when 'confirm' is required with a pointer to update_site.

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 deploys a static site or SPA to a platform subdomain with SSL, and distinguishes between creating a new site and replacing an existing one. It explicitly names a sibling tool (update_site) for patch updates, eliminating 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?

Explicit guidance on when to use this tool (for new or full-replace deploys) versus when to use update_site (for adding/updating individual files). Also recommends dryRun:true before destructive operations and explains the confirm parameter requirement for existing 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by mentioning the per-token MCP rate-limit ceiling and the response header for live remaining, enhancing transparency 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?

Two sentences: first states return values, second gives usage guidance and extra detail on rate-limit header. Both sentences are essential and front-loaded, no wasted words.

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

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

Given output schema exists and no parameters, description covers purpose, usage context, and an additional detail (rate-limit header). Complete for a simple read-only 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?

No parameters, so schema coverage is 100%. Description doesn't need to explain parameters, but it effectively explains return values and usage, compensating for the lack of parameter info.

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?

Description clearly states it returns the team's plan, limits, and current usage, with specific verb 'Return' and resource. Distinguishes from siblings by advising to use before deploy_site or add_custom_domain to check limits.

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 'Use this BEFORE deploy_site or add_custom_domain' to avoid provoking PLAN_LIMIT_EXCEEDED, providing clear context. No exclusions mentioned, but not necessary for a read-only check 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the response format and rate limits for submissions (relevant to the returned endpoint), which goes beyond 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 lengthy and includes extraneous details about submission format (POST JSON, rate limits, honeypot) that are not directly about reading the config. This dilutes the core message and could be more concise.

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 simplicity (one param, read-only) and presence of an output schema, the description provides sufficient detail about what is returned. The submission-related details, while tangential, add context for using the returned endpoint, making it nearly 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 no extra meaning beyond the parameter's schema description (siteName is the site to read). The parameter is straightforward, and the description doesn't enhance understanding.

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

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

The description explicitly states that it reads the form-to-email relay config of a site, listing specific components (delivery mode, From address, DNS records). This clearly distinguishes it from sibling tools like set_forms_config (write) and verify_forms_sender_domain.

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

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

The description implies usage for reading config but does not explicitly state when to use it versus alternatives like set_forms_config or verify_forms_sender_domain. The submission details are about the returned endpoint, not about this tool's invocation, providing indirect 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 declare readOnlyHint true and destructiveHint false; description adds value by listing specific return fields (name, url, plan, etc.), but no additional behavioral context beyond that.

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

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

Single sentence is concise and front-loaded with purpose, but could be slightly more structured (e.g., separate parameter usage).

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

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

With an output schema present, the description adequately covers return values for a simple read tool, but lack of parameter guidance and no contextual tips reduces completeness.

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

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

Schema description coverage is 0% and the description provides no information about parameters (name, siteId) – their purpose or usage – leaving the agent without guidance.

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 'Return' and lists exact fields (name, url, plan, last deploy time, recent deploy history), clearly distinguishing from sibling 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?

No guidance on when to use this tool versus siblings (e.g., list_sites for all sites, get_site for one). Implicit from name but not explicit.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds value by stating the tool is 'privacy-safe' and 'never exposes raw visitor IPs or user-agents,' providing behavioral guarantees beyond the annotations. No contradiction exists.

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

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

The description is two sentences, front-loading the core action and listing key outputs concisely. Every sentence adds value: the first details what is returned, the second adds a privacy guarantee. No unnecessary 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?

Given the tool has annotations for safety and an output schema, the description fully covers what the tool does, including specific metrics and the privacy constraint. It is complete for a read-only, idempotent analytics query 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 schema already describes all three parameters. The description mentions the 'period' parameter with its default, matching the schema. It does not add new meaning or constraints for 'name' or 'siteId'. 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 clearly specifies the tool returns a 'traffic summary' for a site, listing detailed metrics like page views, visitor count, and breakdowns. The verb 'Return' and resource 'site traffic analytics' are explicit. The tool is unique among siblings, as none other provide analytics 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?

The description implies usage for obtaining site traffic analytics, but does not explicitly exclude alternatives or specify when not to use it. Given the unique nature of the tool among siblings, the context is clear enough, but lacks explicit when-to-use versus other tools.

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. The description adds that each entry has a recordId, which is useful behavioral context for chaining operations. No contradictions.

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

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

Two sentences, no fluff, front-loaded with the main purpose. Every sentence adds 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?

Despite having only one parameter and an output schema, the description covers the tool's purpose, output structure (recordId), and how to use the result with sibling tools. Complete for a simple list operation.

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

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

Schema coverage is 100% (the only parameter siteName is described). The description does not add additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Return' and the resource 'all custom domains attached to a site'. It distinguishes this tool from siblings like verify_custom_domain and remove_custom_domain by mentioning the recordId in the output.

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 user what to do with the output (pass recordId to verify_custom_domain or remove_custom_domain), providing clear usage context. It would benefit from explicitly stating when not to use this tool, but the context is sufficient for a listing 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 readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by disclosing limit (up to 50 rows), default filtering (active only), and team scoping. No contradictions.

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

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

Two sentences, no wasted words. Front-loaded with the primary action and scope. Every sentence adds essential information.

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

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

For a simple one-parameter list tool with an output schema, the description covers purpose, default, limit, and scoping. No additional details needed.

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 parameter, providing a baseline of 3. The description adds context by explaining the default behavior (active statuses) and how to inspect history, which goes beyond the schema's enum listing.

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

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

The description clearly states the tool returns staging sessions (verb+resource) and specifies the scope ('for the team this token belongs to'). It also mentions the default and limit. However, it does not explicitly distinguish itself from sibling list tools like list_sites or list_snapshots.

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: use this tool to list staging sessions, especially active ones, and pass a status for historical views. However, it does not provide explicit when-to-use or when-not-to-use guidance or compare with alternatives like search tools.

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 (readOnlyHint, idempotentHint, destructiveHint), the description adds crucial context: it only retrieves records managed by VibeDeploy, orders them oldest first, and explicitly states that viewers can read. This enriches the agent's understanding of behavior and access control.

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 long, with the primary action and scope stated first. Every sentence adds value: scope, return fields, permissions, and safety assurance. No unnecessary 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?

Given the tool's simplicity, good annotations, and presence of an output schema, the description covers all necessary aspects: what it does, what it returns, who can use it, and its non-destructive nature. No gaps 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 coverage is 100%, so the baseline is 3. The description does not add additional meaning beyond the schema's parameter descriptions (name and siteId). It says 'Provide name or siteId' but that is already implied by the schema's optionality.

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 'Read', the resource 'DNS records VibeDeploy tracks for a site', and specifies the return fields (host, type, value). It distinguishes this tool from any sibling tools, as no other DNS-related tools exist among the siblings, making its purpose unique and clear.

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

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

The description provides clear context by stating that any team member (including viewers) can use this tool and that it is read-only, preventing unintended mutations. While there are no alternative DNS tools for comparison, the guidance is adequate for safe usage.

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

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

Annotations already declare this as read-only and idempotent. The description adds valuable behavioral context, such as that it returns every file currently served and is used for diffing before deployment. 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 concise with three sentences, each providing essential information. No fluff; every sentence adds value, and the use case is front-loaded.

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

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

Given the tool's simplicity, the presence of an output schema, and good annotations, the description is complete. It explains the purpose, usage context, and relationship with other tools sufficiently for an AI agent to use 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 50% (only 'name' has a description in the schema). The tool description does not add any parameter-specific information. The 'siteId' parameter remains undocumented, and the description does not compensate for this gap.

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

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

The description clearly states the tool returns SHA-256 and size for every file on a site, using specific verb and resource. It distinguishes from sibling tools like list_deploys or list_sites by focusing on file hashes for deployment optimization.

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 when to use the tool: 'before re-deploying to skip files whose content hasn't changed'. It provides a concrete workflow and references sibling tools like update_site and begin_deploy, offering clear alternatives.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds value by specifying the 50-entry limit, newest-first ordering, and the included fields (source, label, snapshot name, file count, secrets). It also notes access control ('any team member'), which annotations don't cover.

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 clear sentence that front-loads key information. It is concise and contains no unnecessary words, though a slight restructure could improve 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?

Given the presence of an output schema (so return values need not be described), the description adequately covers ordering, limit, and included fields. However, it could clarify the optionality of parameters (none are required) and how they affect the query.

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 two parameters ('name', 'siteId') with no descriptions, and schema description coverage is 0%. The description mentions 'for a site' but does not explain which parameter identifies the site or whether both are needed. It fails to add meaningful semantic context 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 uses a specific verb ('Return'), identifies the resource ('deploy and snapshot history entries'), and includes constraints (most recent 50, newest first) and field details. It clearly distinguishes from siblings like list_deploys and list_snapshots.

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 that any team member can read history but provides no explicit guidance on when to use this tool versus alternatives such as list_deploys or list_snapshots. The usage context is implied but not spelled out.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows it's a safe, read-only operation. The description adds no additional behavioral traits (e.g., pagination, rate limits). Since annotations are rich, a score of 3 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 one sentence with no fluff. It is front-loaded and every word serves a purpose. It could not be more concise.

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 presence of annotations and an output schema, the description is nearly complete. It explains the scope (team). A slight gap is not mentioning the return type, but the output schema handles that. Minor improvement could add 'returns a list of sites'.

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 parameter description for 'includeDeleted' is thorough in the schema itself. The tool description does not add parameter info beyond what the schema provides, so the baseline score of 3 is used.

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

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

The description clearly states the verb 'list' and resource 'sites', and specifies the scope 'for the team this connection belongs to'. This distinguishes it from sibling tools like 'get_site' (single site) or '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?

No explicit guidance is provided on when to use this tool versus alternatives (e.g., 'get_site' for a single site). The parameter description for includeDeleted gives some context, but the main description lacks usage context.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the description adds value by explaining snapshots are point-in-time backups and that it returns NO_VOLUME if no volume exists. No contradiction with annotations.

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

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

The description is three concise sentences: purpose, explanation of snapshots, and error condition. No unnecessary words, front-loaded with 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?

Given an output schema exists and annotations cover safety, the description provides helpful context (snapshot definition, error condition). However, parameter descriptions are missing, slightly reducing completeness.

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

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

Schema description coverage is 0%, meaning parameters (name, siteId) have no descriptions in schema. The tool description does not explain these parameters or provide additional meaning, leaving a gap.

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

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

The description clearly states 'List the Longhorn volume snapshots for a site', specifying the verb (list), resource (snapshots), and scope (for a site). It distinguishes from sibling tools like create_snapshot by focusing on listing.

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 mentions that any team member can list snapshots and notes the NO_VOLUME error condition, but does not explicitly state when to use this tool vs alternatives or provide 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 indicate readOnlyHint=true, but the description reveals autoPromote can copy dist to source on the fly, which is a side effect. This contradiction degrades transparency. The description does add context about when autoPromote has no effect.

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 cover purpose, usage, and conditional behavior efficiently. Every sentence adds value, and the structure is front-loaded with the most important information.

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

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

Given the output schema exists (not shown), the description covers the core behavior and special parameters. It could mention what happens if the source tree is empty without autoPromote, but overall it's fairly complete for a 4-parameter tool.

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

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

Schema coverage is 50%, and the description adds meaning for autoPromote and forcePromote beyond their schema descriptions, explaining their use cases and implications. However, name and siteId parameters lack additional semantic guidance.

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

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

The description clearly states the tool returns SHA-256 and size for every file in the editable source tree, distinguishing it from the served dist. The verb 'return' and resource 'file info' are 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 explicitly advises to use the tool 'BEFORE editing' to learn existing paths and changes. It explains conditional behaviors for autoPromote and forcePromote, though it doesn't name alternative tools for related tasks.

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 annotations: it specifies the file size cap (5242880 bytes), the failure mode (FILE_TOO_LARGE rather than truncation to avoid corruption), and the workflow dependency on get_site.filePaths. Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description aligns with these, adding useful constraints.

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 with a clear front-loaded purpose: 'Return the bytes of one file currently served by the site.' Each sentence adds value: usage workflow, size limit, and discovery method. No unnecessary words 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 the tool has 4 parameters (1 required), 100% schema coverage, and an output schema (not shown but present), the description covers the essential context: return type (bytes), usage pattern, size limitations, and path discovery. It is complete enough for an agent to select and invoke correctly without additional clarification.

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 does not detail individual parameters beyond what the schema provides, but it adds workflow context (e.g., 'use list of paths from get_site.filePaths' for the path param) and clarifies the maxBytes behavior. This is adequate but not exceptional.

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 'Return the bytes of one file currently served by the site.', identifying the verb 'return' and resource 'bytes of one file'. It distinguishes from sibling tools like read_files (plural) and read_source_file by emphasizing 'one file' and the deployment context, and it references get_site.filePaths for discovery.

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 a concrete use case: 'inspect or edit existing content (call read_file → modify → update_site mode:''patch'')' and explains the iterative workflow benefit. It also notes when not to use (for files larger than 5242880 bytes) and recommends using get_site.filePaths for discovery. However, it does not explicitly contrast with other read-related siblings like read_source_file.

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 and idempotent, but the description adds crucial details: the batch budget cap of 8388608 bytes and the specific error BATCH_BUDGET_EXCEEDED, which is not in 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?

Two sentences, front-loaded with purpose, no wasted words. Every sentence provides essential information: batching, limit, budget, and error handling.

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 output schema exists, the description covers key behavioral constraints (batch budget, independent fetching, per-file rules) and references read_file for further details, though it could mention that siteId and name are optional.

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 mentions the path limit of 50 and 'same per-file rules as read_file', adding meaning beyond the schema for paths and maxBytesPerFile, but does not clarify the name and siteId parameters, which have no schema descriptions.

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

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

The description clearly states the tool as a batched version of read_file for reading multiple files, and distinguishes it from the sibling read_file by specifying the batch capability.

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 indicates when to use this tool (when needing multiple files) and the batch budget constraint implying re-request behavior, though it does not explicitly exclude single file use.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds context that it returns bytes and the file is the 'editable copy' of pre-build code, which is helpful but not critical given annotation coverage.

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

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

Two sentences, zero waste. Essential information is front-loaded and concise.

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 presence of an output schema and comprehensive annotations, the description fully covers purpose, usage guidance, and context. No gaps 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 50% (2 of 4 parameters have descriptions). The description adds no parameter-specific information beyond what the schema already provides, failing to compensate for the uncovered 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?

Clearly states 'Return the bytes of one source file', specifying verb (return) and resource (source file). Distinguishes from sibling 'read_file' by referencing the served dist.

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 to use 'list_source_files first to discover paths' and to use 'read_file instead' for served dist, providing clear when-to and when-not-to guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant detail: batch limits, independent per-file errors, a cumulative byte cap (8388608 bytes), and the error code BATCH_BUDGET_EXCEEDED. 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?

Three concise sentences, front-loaded with the core purpose. Every sentence adds essential information about constraints and behavior. No redundancy or unnecessary 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?

Given the 4 parameters, 0% schema description coverage, and existing output schema, the description covers batch behavior well but omits parameter explanations (e.g., what 'siteId' or 'maxBytesPerFile' do). Lacks completeness for parameter semantics.

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

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

Schema coverage is 0%, so the description must compensate. However, it only implicitly references the 'paths' array (via 'up to 50 paths') and a cumulative cap (related to overall bytes). It does not explain 'siteId', 'maxBytesPerFile', or 'name' parameters, leaving significant gaps.

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 performs a batched read of source files, with specific limits (up to 50 paths) and error handling (independent failures). This distinguishes it from siblings like read_file (single file) and read_files (likely broader 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 description implies use for batched reads of the editable source tree but does not explicitly state when to use this tool versus alternatives like read_source_file or read_files. No exclusions or alternative recommendations are provided.

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 significant detail beyond annotations: SSRF-guarded, size/count/time capped, atomic patch mode, and skipping vibedeploy.be images. No contradiction with annotations (destructiveHint=true, readOnlyHint=false, etc.).

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: first states action, second gives timing/usage, third adds behavioral details. Every sentence is meaningful. No unnecessary 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?

Given a single required parameter, clear usage instructions, behavioral safeguards, and the presence of an output schema (complete coverage of return values), the description covers all essential aspects.

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

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

Only one parameter ('name') with 100% schema coverage. The description does not add new meaning beyond the schema's description; it implies the site's HTML is scanned. Baseline score 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 uses a specific verb ('Download and store') and resource ('external images for a site') and clearly states the outcome: rewriting HTML references. It distinguishes itself from sibling tools (which include deploy, file operations, etc.) by focusing on image rehosting post-deployment.

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

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

Explicitly states when to call: 'once AFTER deploying a site rebuilt with the Website Converter.' It also notes that images already hosted on vibedeploy.be are skipped, implying idempotent use. Does not explicitly state when not to use, but the context is clear.

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

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

The description adds context beyond annotations by clarifying that the site itself is unaffected and the default subdomain continues serving. This complements the destructiveHint=true annotation without contradiction. It explains the behavioral scope effectively.

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 long, front-loaded with the core action, and includes a clarifying detail. Every sentence is essential and there is no verbosity.

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

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

Given the presence of an output schema, the description adequately covers the tool's effect. It explains the key behavioral nuances (site unaffected, subdomain remains). Could mention prerequisites like domain being added, but overall it's complete for a removal 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 schema already explains each parameter. The tool description does not add significant extra meaning beyond what is in the schema, thus 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 name, title, and description clearly state the action: removing a custom domain from a site. It specifies that the site is unaffected and the subdomain remains, distinguishing from sibling tools like add_custom_domain. The description uses a specific verb and resource.

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

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

The description implies usage for detaching domains but does not explicitly state when to use this tool versus alternatives like add_custom_domain or verify_custom_domain. No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already declare read-only and idempotent. Description adds valuable behavioral details: regex limitations (BusyBox grep), match cap with budgetExceeded reporting, and glob filtering mechanism. No contradictions.

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

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

Three sentences, front-loaded with key action, no fluff, each sentence adds value. Highly concise and 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?

Given the complexity (8 parameters, 1 required) and presence of output schema (not shown but assumed), the description covers purpose, usage, key parameters, and behavioral traits. Complete for a read-only search 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 75%, but description adds meaning beyond schema: for target, it mentions the requirement for sourceStored; for pattern, explains literal vs regex; for maxMatches, gives default, cap, and truncation behavior; for caseInsensitive, says adds -i. Some parameters like siteId lack extra context, but overall adds 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?

Clearly states the tool does a grep search across files, specifying literal or regex, and distinguishes from sibling read tools by emphasizing it's for finding candidates before reading.

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 advises using this before batch-reading to avoid wasted round trips. Also clarifies when to use target: 'source' vs 'dist'. Could be improved by mentioning when NOT to use, but overall 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?

The description adds substantial behavioral context beyond the annotations. It discloses that the tool is destructive (can disable the relay) and idempotent (setting config replaces existing). It includes submission details (endpoint, content type, field constraints, rate limits, honeypot), which are not captured in annotations. This helps the agent understand side effects and constraints.

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 main purpose and is well-structured into logical sections. However, it is relatively long and includes some details (e.g., submission format, rate limits) that could be considered beyond the tool's core responsibility. Still, it remains focused and each sentence adds 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?

Given the tool's complexity (many config options, multiple behaviors like enabling/disabling, SMTP relay, branding), the description is remarkably complete. It covers when to use it, required roles, follow-up steps, submission details, and response format. The output schema is not shown but the description summarizes the response structure, making the tool self-contained.

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 is fully described (100% coverage), so the schema already provides detailed parameter explanations. The description adds value by explaining the effect of passing null for config and linking the sender configuration to the verification workflow. While the schema covers individual fields, the description provides higher-level context for the most important behaviors.

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: 'Configure the built-in form-to-email relay, fully self-service.' It distinguishes from siblings like get_forms_config and verify_forms_sender_domain by specifying its role in enabling, updating, or disabling the relay. The verb 'configure' plus the resource 'forms relay' is specific and actionable.

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

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

The description provides clear guidance on when to use the tool, including the required team role (owner or admin) and how to disable the relay (pass config:null). It also explains a follow-up action (call verify_forms_sender_domain) when setting a custom sender without an SMTP relay. However, it does not explicitly state when not to use this tool or compare it to siblings like get_forms_config for reading.

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?

Discloses atomicity (all-or-nothing), no writes on match count mismatch, and immediate vs deferred deployment. Annotations already indicate destructiveHint=true, but description adds context 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?

Three sentences, no redundancy. Front-loaded with purpose. Every sentence adds necessary information.

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

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

Comprehensive: covers usage, edge cases (mismatch abort), deployment paths, and differentiation from siblings. Output schema exists but description doesn't need to detail return values.

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%, but description adds value by explaining behavior of 'count' parameter (specify expected matches, abort on mismatch) and 'target' enum (dist vs source implications). Reinforces literal vs regex for find.

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

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

Clearly states verb 'apply', resource 'literal find/replace edits to a single file', and scope 'in one tool call'. Differentiates from sibling tools like 'add_files' by focusing on surgical edits rather than full upload.

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 'Designed for tiny edits where uploading the full file would be wasteful'. Mentions when to use (tiny edits) and implicit alternatives (full upload via other tools). Also explains dist vs source deployment requirements.

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 indicate destructive and idempotent behavior. The description adds crucial context: default patch mode, replace wipes the site, delete removes specific files, dryRun previews changes, and large file encoding. No contradictions.

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

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

The description is concise, front-loading the core behavior and mode selection. Each sentence serves a purpose, though a bit dense for first-time readers. Could be slightly more structured with bullet points.

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 complexity (6 parameters, multiple modes, encoding options), the description covers all essential aspects: mode behavior, file operations, delete, dryRun, large file handling, and error conditions. Output schema exists so return values are covered.

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 good descriptions. The description adds value by explaining defaults, preferred array form, encoding trade-offs, and dryRun semantics. Slightly above baseline due to extra context.

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 title and description clearly state the tool's purpose: updating an existing site. It distinguishes between patch and replace modes and contrasts with sibling tools like begin_deploy and add_file_chunk by mentioning streaming alternatives for large files.

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

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

Provides explicit guidance on when to use patch vs replace, how to delete files, and how to use dryRun. Recommends gzip+base64 over streaming for large files. Lacks explicit when-not-to-use alternatives, but covers key 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?

Beyond annotations (idempotent, not read-only), the description details the verification process, DNS check, ingress attachment, and HTTPS setup timing (~30s). It also explains common failure cause and retry advice, adding significant 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?

Three concise sentences with front-loaded main action. No superfluous words; every sentence adds 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?

Given the presence of an output schema and annotations, the description fully covers the purpose, workflow step, behavior, failure modes, and side effects. It is complete for correct usage.

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 provides full descriptions (100% coverage) for both parameters. The description does not add further parameter-specific meaning, so it meets the baseline.

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

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

The description clearly states the tool checks a TXT record and attaches the domain to the site's ingress, using specific verbs and resources. It distinguishes from sibling tools by referencing 'step 2 of 2' and the prior step.

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 after add_custom_domain by mentioning 'the user added at step 1' and provides common failure handling (DNS delay, retry). It does not explicitly list when not to use or alternatives, but the context is clear.

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

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

The description elaborates on behavior beyond annotations: it checks DNS, marks domain verified once DKIM record observed, switches to custom From with DKIM, falls back to platform address, and mentions DNS propagation delay. No contradiction with annotations.

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

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

The description is concise: three sentences that each add value. First sentence states purpose, second details verification process and fallback, third gives propagation advice. No unnecessary 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?

Given the existing output schema and annotations, the description covers all necessary behavioral context: DNS check, verification effect, fallback, and retry guidance. It is complete for an idempotent DNS-checking tool.

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

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

The schema has 100% coverage with a single parameter 'siteName' described as 'The site whose custom sender domain to (re)check.' The description echoes this with minimal added nuance (e.g., 'to (re)check'), so baseline score of 3 is appropriate.

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

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

The description clearly states that the tool checks DNS records for a custom sender domain (DKIM TXT + SPF include). It distinguishes itself from siblings like verify_custom_domain by focusing on forms-specific sender domain verification.

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

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

The description explains when to use the tool (for custom sender domains) and when not needed (when using custom smtpRelay). It also advises re-running if DNS propagation fails, providing clear context but not explicitly naming alternative tools.

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 value beyond annotations: it discloses that re-writing overwrites previous source (destructive), notes file caps (5 MB per file, 50 MB per call, 200 files per call), and explains source storage requirement. No contradiction with annotations (idempotentHint: true, destructiveHint: true). Could mention side effects like schema changes.

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

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

The description is concise with four sentences, front-loading the core purpose. It efficiently covers usage, error cases, and constraints without extraneous details. Could be slightly more structured but acceptable.

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 explains the workflow (list, write, deploy), error handling, and file caps. However, it omits information about the 'name' and 'siteId' parameters, which are essential for invocation. Given the presence of an output schema (not shown), the description could be more complete regarding parameter roles.

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

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

Schema description coverage is only 33% (files property described, not name or siteId). The main description does not explain the 'name' and 'siteId' parameters, leaving their purpose unclear. The files parameter is well-described in the schema, but the description fails to compensate for the missing 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's purpose: staging edits to a site's editable source tree (not live dist). It uses a specific verb-resource combination ('stage edits') and distinguishes from live deployment via update_site. However, it does not explicitly differentiate from sibling tools like add_files or apply_edits, leaving some 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?

The description provides usage guidance: lists a prerequisite (use list_source_files first), explains that the dist is unchanged until redeploy, and describes an error condition (SOURCE_STORAGE_NOT_ENABLED) with remediation. It implies when not to use the tool (if immediate dist changes are needed). Missing explicit alternatives or exclusions.

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