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?

Annotations already mark this as destructive and not read-only, so the safety profile is known. The description adds useful behavioral context beyond annotations: atomicity across files, validation-before-write ordering, and the count-check semantics. Some of this repeats the schema's all-or-nothing note, but the count semantics are a genuine 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?

Three dense sentences, front-loaded with the core purpose, immediately followed by the sibling relationship and the most decision-relevant semantics. No filler or redundant phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 atomicity, count behavior, and multi-file scope, and output schema makes return-value documentation unnecessary. However, the unexplained required `name` parameter is a real gap for a destructive tool: an agent cannot reliably construct a valid call without knowing what name refers to.

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

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

The description adds meaning not present in the schema, including count semantics (1 default, -1 all, positive asserts exact count) and the 25-file/200-edit call limit. However, the required `name` parameter is never explained in either the schema or the description, leaving an agent to guess what identifier it expects.

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

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

The description states a specific verb ('Apply'), a clear resource ('find/replace edits across MANY files'), and explicitly positions itself as the 'Batch sibling of update_file_content.' This distinguishes it from the closest single-file sibling without needing to open the schema.

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

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

The description gives clear context for when to use it: when editing many files in one call, rather than using the single-file update_file_content. It does not explicitly state 'use update_file_content for a single file,' but the batch-vs-single distinction is strongly implied.

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

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

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 declare destructiveHint=true and openWorldHint=true. The description adds valuable context: atomicity, preflight/scan, failure leaves session open, confirmation requirement, and dryRun behavior (skips scan for preview but real commit will scan). This exceeds annotation coverage and fully informs the agent about side effects.

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

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

Two sentences pack core behavior and safety warnings, with no filler. Parameter descriptions are detailed the moment they appear. Front-loaded with the main action, then flows logically to conditions and mitigations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 being complex (destructive, multi-modal, confirmation gate), the description covers failure paths, preflight outcomes, dryRun preview, and what the real commit does (scan). All four params are covered. Output schema exists, so return values need no description. Exceptionally complete without being bloated.

Complex tools with many parameters or behaviors need more documentation. 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 enhances parameters: clarifies delete applies to live site paths, explains dryRun returns diff and tells agent to use it for replace-mode, and specifies exact confirm string. This adds genuine 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?

Clearly identifies the tool's action (atomically apply staged files to live site), the resource (staging session), and its distinctive characteristic (atomic, with preflight/scan, failure keeps session open). It distinguishes from siblings like apply_edits (edits vs staged files), deploy_site (direct deploy), and begin_deploy (starts session, this commits).

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

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

Explicitly states when to use: commit a staging session, and mentions related tools and actions: abort, re-attempt, dry-run before replace-mode, and how to handle renames via delete + add_files. While it doesn't name sibling tools directly, it describes the workflow context and guidance clearly.

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

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

The annotations (destructiveHint: true, readOnlyHint: false) are meaningfully elaborated: the description clarifies that the destructive aspect refers to 'retention cleanup may remove older backups' rather than altering served content, discloses the authorization requirement, and flags the NO_VOLUME error condition. This goes well beyond what the annotations alone convey, with no contradiction between the text and the annotation flags.

Agents need to know what a tool does to the 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 earning its place: the core action, the safety/side-effect clarification, and the role requirement plus error condition. The most important information is front-loaded and there is zero filler or repetition of schema content.

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

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

For a mutation with side effects, the description covers purpose, what gets affected, required permissions, and a notable edge error. An output schema exists, so return values need not be described in prose. The remaining gap is parameter semantics (name and siteId), which prevents full 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 coverage is only 33% — name and siteId are bare strings with no schema descriptions, and the description does not compensate. It never explains what 'name' means or clarifies the role of siteId, leaving two of three parameters effectively undocumented across both schema and description; the fact that zero parameters are required makes this gap riskier because an agent may not know which arguments are actually necessary for the operation.

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

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

The description opens with a specific verb-object pair: 'Take a point-in-time Longhorn snapshot of a site's served files,' which precisely identifies the operation and its resource. The title reinforces it as a 'manual snapshot (backup),' and among the siblings only list_snapshots overlaps — the description makes clear this creates rather than lists, so there is no confusion with deploy, delete, or update 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?

Provides clear context: it is a manual backup that 'does not change served content,' requires 'an owner or admin team role,' and only succeeds for deployed sites (else NO_VOLUME). It stops short of explicit when-not-to-use guidance or naming alternatives, though no sibling is a close substitute, so the omission is minor.

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 declare destructiveHint:true and readOnlyHint:false, and the description reinforces this with a prominent 'DESTRUCTIVE on existing sites' warning, explaining that files not in the call are deleted. It adds beyond annotations by specifying the confirm requirement, the file encoding trade-offs, and the subdomain publishing detail. 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?

Packed with essential information yet efficiently organized: purpose, then usage guidance, destructive warning, alternative mention, encoding tip, and custom-domain follow-up. Every sentence adds value; no filler. Despite length, it remains front-loaded with the primary action and differentiators.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tool with four parameters, two of which are required, a destructive operation, multiple usage modes, and sibling tools, the description covers all critical aspects: purpose, behavior, alternatives, prerequisites (confirm), safety (dryRun), and support for large files and custom domains. It is arguably over-complete for a simple tool but perfectly suited to this complex deploy 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% with per-property descriptions, but the tool description enriches these by explaining the destructive consequence of 'files' (deleting unspecified files), why 'confirm' is required, and that 'dryRun' is strongly recommended for existing sites. It also clarifies the encoding option's benefit (3-5x compression) beyond the schema's basic description.

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

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

The description opens with a specific verb+resource ('Publish a website to a live URL'), then clearly distinguishes deploy_site from update_site by explaining full-replacement vs. patch. It also mentions added value like automatic SSL and custom domain support, making its role unmistakable among the many sibling deployment 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?

Explicit guidance is provided: 'Use update_site (default mode: patch) if you want to add or change individual files without removing the rest' and 'Use dryRun:true to preview the diff.' It also instructs to call add_custom_domain for custom domains and warns against splitting large files across multiple calls, giving concrete when-to-use and when-not-to-use context.

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

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

The annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds meaningful behavioral context: it also returns the per-token MCP rate-limit ceiling and points to the X-RateLimit-Remaining response header for live remaining usage. This matches the kind of rate-limit and side-effect transparency that helps an agent invoke the tool correctly.

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

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

The description is two sentences with no filler. The first sentence states the core return value, the second gives targeted pre-flight usage guidance and an additional behavioral detail about rate-limit headers. Every clause 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?

For a zero-parameter, read-only tool with an output schema and annotations covering safety and idempotency, the description is fully sufficient. It explains what the tool returns, when to use it before related operations, and where to find live rate-limit data, leaving no meaningful gap for selection or invocation.

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

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

The tool has zero parameters, so the input schema is empty and there is nothing for the description to clarify about arguments. Per the baseline for zero-parameter tools, this is effectively complete; the description instead clarifies what the response contains, which is the relevant semantic information.

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

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

The description opens with a specific verb and resource: 'Return the team's plan, its limits, and current usage.' This clearly distinguishes it as a read-only account/limits inspection tool, and the title reinforces the same message. The naming of deploy_site and add_custom_domain in the usage guidance further separates it from those action-oriented siblings.

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

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

The description explicitly states when to use this tool: 'Use this BEFORE deploy_site or add_custom_domain to know whether a deploy would trip a plan limit, instead of provoking PLAN_LIMIT_EXCEEDED.' This gives the agent a concrete decision rule and names the relevant alternative 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 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's 'Return' phrasing aligns with a safe read operation. The description adds some output behavior but does not disclose how site selection works, error behavior, or any auth requirements. It neither contradicts nor substantially extends the annotations.

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

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

The description is one concise sentence that front-loads the action and immediately lists what is returned. Every word adds value and there is no redundancy.

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

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

An output schema exists, so the return fields are further specified elsewhere, and the tool is conceptually simple. However, the description omits how to identify the target site, especially since neither parameter is required and there is no parameter guidance. This leaves a meaningful gap for an agent deciding how to invoke the tool.

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

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

Schema description coverage is 0%, and the description does not mention the input parameters 'name' or 'siteId' at all. It only lists return fields, leaving the agent to infer which identifier is needed and whether one, both, or neither is acceptable. Since there are no required parameters, this ambiguity is more significant.

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

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

The description states a clear action ('Return') on a specific resource ('site') and enumerates the output fields (name, url, plan, last deploy time, recent deploy history). This helps distinguish it from siblings like get_site_analytics or list_deploys, though it stops short of explicitly naming those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the tool is used when you need details about a single site, but it does not state when to prefer get_site over list_sites, get_site_analytics, or get_account. There is no explicit when/when-not guidance or mention of 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations with the privacy guarantee: 'Never exposes raw visitor IPs or user-agents.' This is a meaningful behavioral trait not encoded in the schema or annotations.

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

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

The description is two sentences with no filler. The first sentence front-loads the action, scope, default period, and the exact list of returned metrics. The second sentence adds a meaningful privacy constraint. Every clause earns its place, and the structure is easy for an agent to parse quickly.

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

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

Given the tool's modest complexity, fully described parameters, and an existing output schema, the description is complete. It clarifies the aggregation period, the nature of the data returned, and the privacy boundary. There is no obvious missing information an agent would need to decide whether or how to invoke this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the `period` default and aggregation window, but it does not add meaning beyond what the parameter descriptions already provide for `name` and `siteId`. The schema already explains the 'provide this or siteId' relationship.

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

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

The description starts with a specific verb ('Return') and a specific resource ('a privacy-safe traffic summary for a site'), then enumerates the exact metrics included. This makes the tool's purpose unmistakable and clearly distinct from sibling tools like get_site, which would return site configuration rather than analytics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 makes the usage context clear: call this when you need traffic metrics for a site over a period. It also specifies the default and range behavior for `period`. It does not explicitly name alternatives or exclusions, but none of the sibling tools are analytics functions, so the routing ambiguity is minimal.

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?

The description goes well beyond the annotations by disclosing critical behavioral traits: 'mismatches abort the whole call with NO writes,' 'literal find/replace' (not regex), and the difference in deployment behavior between dist and source edits. This adds real safety context on top of destructiveHint=true, and it does not contradict any annotation.

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

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

Four tightly written sentences with no filler. The first sentence front-loads the core action, the second gives concrete use cases, the third states the safety guarantee, and the fourth explains deployment implications. Every sentence earns its place.

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

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

The schema is rich and a separate output schema exists, so return-value details are already covered. The description adds the missing contextual pieces: atomic whole-call aborts, expected-count semantics, and dist/source deployment flow. There is no critical invocation context left unexplained.

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

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

Schema description coverage is 100%, so the baseline is 3 because the schema already thoroughly documents name, path, edits, and target. The description restates the literal-match and count-expectation semantics, but it adds no new parameter-level detail beyond what the schema provides. It provides use-case context but not additional parameter meaning.

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

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

The description clearly states a specific verb and resource: 'Apply one or more literal find/replace edits to a single file on the site, in one tool call.' It distinguishes itself from uploading the full file, but it does not explicitly differentiate from the sibling tool apply_edits, which is likely an overlapping alternative. The scope of 'tiny edits' is conveyed but sibling differentiation is incomplete.

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

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

The description gives clear context on when to use the tool: 'Designed for tiny edits where uploading the full file would be wasteful' with concrete examples. It also explains the post-edit workflow difference between dist and source edits, and that build_and_deploy is needed for source changes. It does not explicitly name alternatives like apply_edits or state an explicit when-not-to-use beyond 'tiny edits,' so it stops short of full routing guidance.

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

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

Annotations already flag destructiveHint and readOnlyHint, but the description goes much further: it warns about the destructive wipe-and-replace legacy behavior, explains that only listed files change in patch mode, details the encoding trade-offs with gzip+base64, and notes that delete is rejected in replace mode. There is no contradiction between annotations and the text; both align that this is a write-capable, destructive-capable tool.

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

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

The description is dense but well-organized: mode breakdown, deletion, dry-run, large-file strategy, and error behavior are each mentioned in a single focused sentence. Every clause adds value; there is no repetition or filler. The front-loading of 'Patch or replace files' allows the agent to quickly understand the core action even before reading the details.

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

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

Given the tool has six parameters and a rich output schema, the description fills the most important usage gaps that raw schema cannot provide: when to choose replace over patch, how to preview changes with dryRun, how to handle large files efficiently, how to perform atomic renames, and the side-effect of deletion. It gives the agent complete operational context for a powerful and destructive operation.

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

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

The schema already provides 100% coverage with detailed inline descriptions for parameters. The description adds meaningful context beyond that, such as large file recommendations (100-250 KB text files with gzip+base64), the delete-only deploy flow, and atomic rename semantics. This extra guidance helps the agent choose encodings and batch operations more effectively.

Input schemas describe structure but not intent. Descriptions should explain 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 begins with a clear verb and resource: 'Patch or replace files on an existing site.' It then specifies the operational modes (patch vs replace), making it immediately distinct from siblings like update_file_content, write_source_files, or begin_deploy. The scope is unambiguous and the tool's purpose is not just stated but fully operationalized.

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

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

The description explicitly tells the agent when to use each mode ('Defaults to patch mode', 'Pass mode:v replace'), how to target deletions, and when to use 'dryRun: true' to avoid destructive mistakes. It even names an alternative approach for large files and recommends preferring this tool over begin_deploy + add_file_chunk, which is excellent alternative 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 (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 annotations already signal a destructive write, and the description adds important behavioral context: changes are not immediately live, they only take effect after redeployment, and legacy sites may fail with SOURCE_STORAGE_NOT_ENABLED with a clear resolution path. This goes well beyond what the annotations provide.

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

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

Three tight sentences that front-load the core purpose, then cover prerequisite discovery, deployment timing, and a specific failure mode. No filler or redundancy.

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

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

Covers the core workflow: discover via list_source_files, stage edits, redeploy to affect dist, and handle legacy source-storage failure. The presence of an output schema reduces need to document return values. Minor gaps remain around ambiguous parameters, but overall the agent has enough to use the tool safely and effectively.

Complex tools with many parameters or behaviors need more documentation. 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%; name and siteId are undocumented in the schema and the description does not clarify them. The required files parameter is well described in the schema, but the description itself adds no parameter-level meaning, leaving the agent to guess how siteId and name are 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 states a specific action ('Stage edits') on a specific resource ('a site's editable source tree') and explicitly contrasts it with the live dist. This makes the tool's job immediately clear and distinguishes it from deployment-related siblings.

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

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

Gives clear usage context: use list_source_files first, edits are staged, and the dist only changes after update_site or build_and_deploy. It also explains the legacy-site failure path. It does not explicitly name alternatives like add_files or apply_edits, but the staging-vs-dist distinction provides solid selection guidance.

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