vibedeploy

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

The description adds valuable behavioral detail beyond the annotations: it states the operation returns immediately, cleanup is best-effort, and the sweeper will retry failures. It also explicitly clarifies what is destroyed (scratch dir) and what is not (live site), complementing the readOnlyHint, destructiveHint, and idempotentHint 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 two sentences with no filler. The primary action and target come first, followed by the key safety guarantee and the timing/cleanup nuance. Every sentence contributes critical 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 tool with an output schema, the description covers purpose, safety, and asynchronous cleanup behavior, which is nearly complete. It does not formally define what a 'staging session' is or state explicit prerequisites, but the lifecycle context from sibling tools (begin_deploy, commit_deploy) mitigates this minor gap.

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

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

Schema coverage is 100%: deployId is described as 'Session id to abort.' The description does not add further parameter detail, but with full schema documentation and a single obvious parameter, no additional explanation is required. 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 uses a specific verb and resource: 'Discard a staging session and its scratch dir.' It clearly identifies the tool's action and distinct target, and the phrase 'Live site is untouched' differentiates it from deployment or site-deletion operations among the sibling tools.

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

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

The description gives clear context: this is for discarding a staging session, not touching the live site. It implies the appropriate moment to use the tool, but it does not explicitly contrast it with sibling operations like commit_deploy or begin_deploy, so exclusions and alternatives are left to inference.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds concrete idempotency semantics: calling twice with the same (siteName, domain) returns the existing record instead of creating a duplicate. It also discloses the return value (TXT record), the DNS propagation delay, and the prerequisite that the site must exist, adding value beyond the structured annotations.

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

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

The description is compact but information-dense, front-loading the core action and return value before covering idempotency, next actions, and preconditions. Every sentence contributes a distinct, actionable piece of information, and the structure mirrors the workflow an agent must follow.

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

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

With an output schema present, annotations covering safety and idempotency, and a description that covers prerequisites, next steps, and return semantics, nothing an agent needs to correctly select and invoke this tool is missing. The description fully compensates for the tool's moderate complexity.

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

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

Schema description coverage is 100%, so the schema already documents both siteName and domain with examples. The description reinforces the relationship between the two parameters through idempotency wording and the explicit platform-subdomain prerequisite, but it does not materially add meaning beyond the schema's own parameter 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 starts attaching a user-owned domain to an existing site, returns a TXT record for DNS verification, and is explicitly step 1 of a 2-step flow. It distinguishes itself from the sibling verify_custom_domain by naming the next step and the recordId it produces.

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

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

The description gives explicit when-to-use context: attaching a user-owned domain, and it prescribes the sequence — call verify_custom_domain after TXT publication, and call deploy_site first if the site doesn't exist. It also states the site must already exist on a platform subdomain, which is a clear precondition.

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 say readOnlyHint=false and idempotentHint=false, but the description adds crucial behavior: isFirst truncates existing scratch entries and creates parent directories, isLast triggers an assembled-size stat, concurrent chunks interleave and corrupt the file, and expectedByteOffset can fail the call with MISALIGNED_CHUNK before writes. This goes well beyond 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?

The description is dense but purposeful: it front-loads the purpose and the LAST RESORT warning, numbers the alternatives, and packs first/last, serialization, compression, and size-limit guidance into a compact, scannable structure. Every sentence contributes operational 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 tool with 7 parameters, required flags, ordering hazards, encoding options, and a failure mode, the description covers the when, how, pitfalls, and constraints. An output schema exists, so omitting return-value details is acceptable. The remaining parameter details are already fully covered by the input schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds practical parameter guidance: gzip+base64 chunks quadruple byte throughput, ~80 KB of base64 is a safe upper bound per chunk, isFirst/isLast have specific effects, and chunks for the same path must be serial. Not every parameter gets extra treatment, but the added meaning clearly exceeds schema-only documentation.

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

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

The description states a specific verb and resource: 'Stream a single file across multiple calls' and 'Append one chunk of a single file to a staging session'. It also distinguishes itself from add_files, begin_deploy, and deploy_from_url, so an agent can tell exactly what this tool is for.

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 marks the tool as 'LAST RESORT', enumerates three alternatives with concrete conditions, and says 'Only chunk when none of those work.' It also gives operational guidance on serial sends, making it clear when and how to use this tool versus its siblings.

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 rich behavioral detail beyond the annotations: per-call validation, fail-fast behavior, cumulative 500 MB session cap, overwrite semantics for re-added paths, server-side gunzipping, and encoding guidelines. It also clarifies the idempotentHint by explaining what happens when a path is added again.

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

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

The description is long but every sentence carries actionable information. It front-loads the core behavior, then uses a clearly marked LARGE TEXT FILES section for the nuanced guidance. The structure makes the dense content scannable and purposeful.

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 this complexity, the description covers everything an agent needs: the operation, parameters, encoding options, size limits, failure behavior, and clear routing to alternatives. The output schema exists, so return-value details are not needed, and no critical context is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful operational context: it explains how gzip+base64 compression affects wire size, when to use each encoding, and how the files parameter behaves cumulatively across the session. This goes beyond simply restating the schema.

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

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

The description opens with a specific verb and resource: 'Append files to an open staging session,' making the tool's function unmistakable. It also distinguishes itself from siblings by explaining how it differs from add_file_chunk and begin_deploy's uploadUrl, so an agent can select it correctly.

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

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

The description gives explicit when-to-use guidance: prefer this over add_file_chunk for large text, only chunk when a single file exceeds ~250 KB after gzip, and use begin_deploy's uploadUrl when the host is reachable. It also explains that repeated calls are expected and that commit_deploy applies everything at once, covering both usage and 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?

Beyond the destructiveHint annotation, the description discloses meaningful behavioral detail: atomicity across files, validation-first execution, writes only proceeding if every count check passes, and the semantics of count values. This is valuable context that annotations alone do not provide.

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

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

Three tightly packed sentences: scope, sibling relationship, count semantics, and atomic behavior. Every sentence earns its place and the most important batched-purpose information is front-loaded.

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

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

The description covers behavior, batching scope, and atomicity well, and an output schema exists. However, the required 'name' parameter is left completely undocumented both in the schema and in the description, leaving a real ambiguity about what value the agent must supply.

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 67%, and the description adds substantial parameter-level meaning: default count behavior, -1 meaning all, exact-match assertions, and the all-or-nothing nature of the call. The required 'name' parameter remains unexplained, but the description compensates well for most schema 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 states a specific action, 'Apply find/replace edits across MANY files in one tool call,' and identifies itself as the batch sibling of update_file_content, clearly differentiating its purpose from single-file 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?

It explicitly names update_file_content as the sibling and frames this tool as the batch variant, making the primary usage context ('many files') clear. It stops short of explicitly stating when not to use it, but the guidance is strong enough for an agent to select appropriately.

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 non-read-only, non-idempotent, and non-destructive behavior. The description adds valuable operational details beyond these: the active session limit of 5 per token and the default TTL of 1 hour. It also frames the tool as opening a staging session, implying changes are staged rather than immediately applied, which enriches the annotation context.

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

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

The description is compact and front-loaded: the primary purpose appears in the first sentence, followed by a clear usage condition, pairing workflow, and relevant limits. Every sentence contributes meaningful information, and nothing is redundant with the schema or annotations.

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

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

For a two-parameter tool with a rich schema and an output schema available, the description covers the essential context: when to use it, how to complete the workflow, and operational constraints like session limits and TTL. No critical guidance for calling the tool correctly is missing.

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

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

Schema description coverage is 100%, so the parameters name and mode are already fully documented, including mode semantics and the constraint that name must refer to an existing site. The description itself adds no additional parameter-level explanation, so the 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 identifies the tool's function as opening a staging session for multi-call deploys, distinguishing it from single-call tools like deploy_site and update_site. It also explicitly maps the workflow with add_files or tarball upload, so the agent knows exactly what begin_deploy is for.

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 an explicit usage condition: use when the site is too large for a single deploy_site/update_site call. It also spells out the required pairing sequence (add_files or tarball upload, then commit_deploy), leaving no ambiguity about when and how to use the 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?

Beyond the annotations, the description discloses meaningful runtime behavior: hardened one-shot pod, no SA token, no DB/Vault reach, NetworkPolicy-restricted egress, atomic swap into the live dist, and the side effect of writing buildCommand/outputDir into Site.sourceManifest on first run. These are exactly the behavioral details an agent needs to anticipate consequences.

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

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

Three sentences with no filler: the action, the isolation/security guarantees, and the manifest persistence behavior. Technical details are packed efficiently in parentheticals, and the most critical behavior 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?

For a build-and-swap operation, it covers prerequisites, isolation guarantees, atomicity, and persistent manifest behavior; the output schema handles return values. It stops short of describing failure/rollback behavior or how to identify the site when both name and siteId are absent, but nothing critical is missing for selecting and invoking 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?

The schema covers 67% and already documents rootPath, outputDir, buildCommand, and saveManifest. The description adds important cross-parameter semantics: buildCommand and outputDir are persisted into the manifest on first run and can be omitted later. It does not clarify the roles of name or siteId, but those are common identifiers and the description provides enough operational 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 states a specific multi-step action — run a build inside a one-shot pod and atomically swap its output into the live dist — with a clear resource and result. It is unambiguous, though it does not explicitly contrast itself with sibling deploy tools such as deploy_site or begin_deploy.

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

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

It gives clear context: source must first be written via write_source_files / list_source_files, and builds reuse the GitProject git-deploy pod. It also explains the first-run vs subsequent-run manifest behavior. It does not name alternatives or state when not to use this tool, so it falls short of a 5.

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

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

Even though annotations already mark this as read-only, idempotent, and non-destructive, the description adds meaningful behavioral detail: it never purchases or registers, returns gross prices including 21% VAT, prices are indicative only, and the call is not site-scoped. This goes well beyond the annotation hints.

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

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

The description is well-structured and front-loaded with the core purpose and read-only warning. It is slightly longer than necessary because the alternatives sentence largely duplicates the schema description, but every included detail serves a purpose such as VAT, TLDs, and token requirements.

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

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

The tool is simple, has fully documented parameters, an output schema, and strong annotations. The description covers purpose, read-only safety, pricing semantics, TLD behavior, authentication, and site-scoping, leaving no significant gap for correct invocation.

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

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

Schema description coverage is 100%: both domain and alternatives are already fully documented in the input schema. The description restates the alternatives behavior and the TLD set but does not add significant new parameter meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description opens with a specific verb and resource: 'Check whether a domain can be registered and get an INDICATIVE retail price.' It clearly distinguishes this from site-related sibling tools like add_custom_domain by noting it is not tied to a specific site and does not buy or register 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?

The description gives explicit when-to-use and when-not-to-use guidance: it is a read-only lookup and 'does NOT buy, register, reserve, or pay for any domain.' It also adds practical context by stating a valid team token is required and that it is not tied to a specific site, plus guidance for the alternatives parameter.

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

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

Beyond the annotations, the description adds important behavioral details: atomicity, preflight and secret/malware scanning, failure leaving the session open, and the confirmation gate for destructive replace-mode. This substantially exceeds what the destructiveHint annotation alone provides.

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-load the core purpose, then cover failure semantics and the critical confirmation requirement. Every sentence earns its place with no redundant filler.

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

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

Given the detailed schema, output schema, and annotations, the description is complete enough for an agent to know when and how to invoke the tool, what to expect on failure, and what safeguards apply. The behavioral notes about dry-run and confirmation are especially valuable for a destructive operation.

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

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

The input schema already documents every parameter thoroughly, so the baseline is 3. The description reinforces the confirm constraint and replace-mode context but does not add meaning to the parameters beyond what the schema descriptions already state. It neither harms nor significantly extends the schema semantics.

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, resource, and effect: atomically applying a staging session's files to the live site. It also differentiates commit_deploy from siblings like begin_deploy and abort_deploy by emphasizing the final live-site application and the preflight/scan behavior.

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 strong context for when to use the tool, including replace-mode confirmation requirements and dry-run recommendations for populated sites. It does not explicitly name alternative tools or state 'use X instead of Y', but it makes the workflow boundary clear by mentioning session re-attempt and abort behavior.

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 signal mutating and destructive behavior, but the description adds valuable specifics: served content is unchanged, retention cleanup may remove older backups, authentication requirements, and a specific error condition. This goes well beyond the structured 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 compact and front-loaded with the core purpose, then efficiently covers side effects, permissions, and a key error case. Every sentence adds distinct value with no redundancy.

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

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

The description covers the operation's behavior, side effects, authorization, and a notable error. However, the lack of parameter semantics and the fact that no parameters are marked required leaves some ambiguity about the minimum valid call. An output schema exists, so return-value documentation is not a gap.

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

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

Schema description coverage is only 33%, and the description does not compensate. It never explains what 'name' or 'siteId' mean, which parameters are required, or how they relate to the snapshot operation. Only 'label' is documented in the schema, leaving most parameters under-specified.

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 ('Take a point-in-time Longhorn snapshot') on a specific resource ('a site's served files'), and explicitly frames it as a manual backup. This clearly distinguishes it from related tools like list_snapshots 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 provides useful context: it is a manual snapshot, it does not alter served content, it requires an owner/admin role, and it may fail with NO_VOLUME if the site was never deployed. It does not explicitly name alternative tools or when-not-to-use conditions, so it misses the top tier.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses crucial behavior: the site moves to 'deleted' immediately, the hostname is freed, serving stops, and a sweeper purges it after the recovery window. It also explains the response fields 'accepted' and 'purgesAt', giving the agent useful grounding for user-facing messaging.

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

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

The description is compact and front-loaded with the core action, then adds necessary lifecycle, usage, and response details. Every sentence contributes value, and there is no redundant restating of the title or schema.

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

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

The description covers behavior, recovery semantics, and response fields well, and an output schema exists. However, it is incomplete for invocation because it does not explain how to specify the target site via name/siteId. Given openWorldHint=true and the optional schema properties, an agent cannot be fully certain how to construct a valid call.

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

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

With only 33% schema description coverage, the description needed to clarify how name and siteId identify the target site, but it only restates that confirm=true is required. It does not explain whether name, siteId, or both are needed, which one takes precedence, or how the site is selected. This leaves a significant parameter ambiguity.

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

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

The description clearly states the action: 'Soft-delete a site', with a concrete resource and an explicit distinction from a hard delete. It also clarifies the 7-day recovery aspect and positions this tool as the normal 'remove this from my dashboard' flow, making it easy to distinguish from siblings like delete_source_file or update_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 provides an explicit use case: 'Use this for the normal remove this from my dashboard flow.' It does not explicitly spell out when not to use it or name alternatives, but the resource scope ('a site') and the soft-delete lifecycle make the intended context clear enough for an agent.

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

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

Annotations already declare destructiveHint and idempotentHint, so the description's added value is explaining the exact blast radius: only the editable source tree is affected, and the served dist is unchanged. This goes beyond the structured annotations and helps an agent understand consequences.

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

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

The description is two sentences with no wasted words. The core action and the key scoping caveat are front-loaded, making it 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?

Annotations and the output schema cover safety and return-value concerns, and the description clarifies scope. However, the meaning of 'name' and 'siteId' remains unclear, and the description does not explain how deletion interacts with future deploys or other source-tree operations, leaving a notable gap.

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

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

Schema description coverage is only 33%, with only 'path' described. The description itself does not explain the optional 'name' and 'siteId' parameters or how they relate to the operation, so the agent is left without enough guidance on the full parameter set.

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 ('Remove') and names a precise resource ('one file from the site's editable source tree'). It also distinguishes this tool from deployment-affecting operations by explicitly stating that the served dist is unchanged, which separates it from sibling tools like delete_site or deploy-related actions.

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: this tool edits the source tree rather than the served output. However, it does not explicitly name alternatives or state when not to use this tool, 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?

Beyond the annotations, the description discloses server-side fetching, tarball parsing, 100 MB and 60s limits, the hostname allowlist, and the destructive 'replace wipes the live dist' behavior. This adds meaningful context beyond destructiveHint=true and 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?

The description is well organized and front-loaded with the main action, followed by use-case, equivalence, and pointer to the allowlist. There is slight redundancy between 'the server fetches and deploys it' and 'Server-side fetch ... then deploy its contents,' but it remains compact and purposeful.

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 deployment tool with full parameter documentation, an output schema, and annotations, the description covers purpose, when to use it, destructive behavior, limits, host restrictions, and how it relates to sibling upload/deploy tools. No essential information is missing for an agent to decide and call it correctly.

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

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

Schema description coverage is 100%, and the archiveUrl schema description already contains the allowlist, size/time limits, and use-case guidance. The free-text description mostly restates this information and points to the schema, so it adds only marginal value beyond the structured parameter documentation.

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

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

The description states a specific verb and resource: deploy a site from a public archive URL. It distinguishes itself from the upload workflow by explaining it is equivalent to begin_deploy → POST uploadUrl → commit_deploy in one call, and emphasizes 'no upload from your side.'

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

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

It explicitly tells when to use this tool: when the runtime sandbox can reach archive hosts such as github, gist, or S3 but cannot reach the upload endpoint. It also points to the archiveUrl description for the hostname allowlist and names the equivalent multi-step alternative.

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 mark this as destructive, and the description goes well beyond that by specifying exactly what destruction means: 'replaces every file on the named site with the supplied set' and 'Files not in this call are deleted.' It also discloses the confirm requirement, the rejection without confirmation, and dryRun behavior to preview changes before any write.

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

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

The description is well-structured and front-loads the critical destructive warning early. It loses a point because it repeats the platform subdomain information twice (once at the beginning and again later), and the phrase 'The fastest way to get a localhost project or an AI-generated site online' is marketing filler rather than essential operational guidance.

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 covers everything an agent needs: creation vs. full-replace behavior, destructive consequences, confirmation string, dryRun preview, large-file encoding strategy, and the sibling tool to use for non-destructive updates. Nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters well. The description still adds practical value beyond the schema with guidance on large files: 'A 100-250 KB HTML/CSS/JS file fits in THIS call when sent with encoding:'gzip+base64'' and explains how to prepare the encoding. This gives agents actionable usage nuance beyond the enum 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 opens with a clear verb and resource: 'Publish a website to a live URL' and 'Deploy a static site or single-page app.' It explicitly distinguishes this from update_site by describing deploy_site as a full-replace operation, so an agent can immediately tell it apart from sibling tools like update_site or begin_deploy.

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

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

The description explicitly says when to use this tool, when not to, and which alternative to choose: 'Use update_site (default mode:'patch') if you want to add or change individual files without removing the rest.' It also recommends dryRun before deploying to an existing site and points to add_custom_domain as the follow-up for custom domains.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses additional behavioral details: it returns the per-token MCP rate-limit ceiling and points to the X-RateLimit-Remaining response header for live remaining quota. This adds meaningful context.

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

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

Two sentences with no filler. The core purpose is front-loaded, followed by a specific usage directive and a useful note about rate limits. Every sentence earns its place.

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

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

For a simple, parameterless read-only tool with an output schema and safety annotations, the description is complete. It explains what is returned, when to use it, and even orients the agent to the rate-limit header.

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

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

The tool has zero parameters, so there is no parameter semantics to document. The description appropriately focuses on return value semantics instead, meeting the baseline for a parameterless tool.

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

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

The description states a clear verb and resource: it returns the team's plan, limits, and current usage, plus the rate-limit ceiling. This unambiguously distinguishes it from sibling tools like get_site or list_deploys.

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

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

The description explicitly says to call this BEFORE deploy_site or add_custom_domain to check plan limits and avoid PLAN_LIMIT_EXCEEDED. This gives the agent a concrete decision rule for when to invoke it.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description aligns with them. It adds meaningful context about what the config includes (resolved delivery mode, active From address, DNS records/verification status). The submission instructions relate to the returned endpoint rather than this tool's own behavior, but they are clearly labeled as 'Submissions'.

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

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

The purpose is front-loaded in the first sentence, but the second paragraph spends substantial space on submission limits, response shape, rate limits, and honeypot guidance that are only tangentially related to invoking this read tool. It is structured but not tight.

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

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

For a single-parameter read tool with an output schema and read-only annotations, the description provides enough invocation context. It could be complete without the submission-form details, but those details do not make the tool uncallable or underspecified.

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 the only parameter 100%, so the baseline applies. The description uses 'site' where the schema says 'siteName' but adds no new parameter semantics 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?

Starts with 'Read the form-to-email relay config of a site' – a specific verb, resource, and scope. It also names the returned config components (delivery mode, From address, DNS records, verification status), separating it from sibling tools like set_forms_config 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 read-only context is clear: use this to obtain a site's forms-relay configuration, not to modify it. It does not explicitly name alternatives such as set_forms_config or verify_forms_sender_domain, so it misses full when-not/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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the specific data returned, such as plan and deploy history, but no additional behavioral context like error handling, permissions, or rate limits. This meets the lower bar set by annotations but does not enrich behavior beyond return fields.

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

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

One sentence with no filler, front-loading the action and the primary returned fields. It is appropriately sized for a simple getter.

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 output schema and annotations cover return shape and safety, but the description leaves critical ambiguity: both input parameters are optional and there is no statement on how to select the site. It also fails to distinguish when this tool is appropriate compared to list_sites or get_site_analytics. For a tool with zero required parameters, this is a significant completeness gap.

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

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

Schema coverage is 0% and the description does not explain either 'name' or 'siteId', nor how they relate (e.g., either/or or both). The only mention of 'name' refers to an output field, which could confuse the input parameter. No compensation is made for the missing 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 states the verb 'Return' and enumerates the exact fields (name, url, plan, last deploy time, recent deploy history), making the resource clear. It does not explicitly contrast with siblings like get_site_analytics or list_sites, but the listed fields distinguish it sufficiently.

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

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

No guidance is given on when to call get_site versus list_sites or get_site_analytics. It does not state whether to pass name, siteId, or both, nor any context for retrieving deploy history. The description is purely declarative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond annotations: it promises privacy-safe output and explicitly states that raw IPs and user-agents are never exposed, which is useful for agents handling sensitive data.

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

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

The description is two efficient sentences with no filler. The core action is stated first, followed by the returned metrics and the privacy guarantee. 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?

For a read-only analytics tool with a full output schema and complete parameter descriptions, this description covers the essentials: what it returns, the optional period, and the privacy constraint. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (name, period, siteId). The description reinforces the period default and 'site' concept, but it does not clarify the precedence or mutability between name and siteId. Baseline 3 is appropriate because the schema carries the parameter detail.

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') with a clear resource ('privacy-safe traffic summary for a site') and enumerates the exact metrics included. It is easily distinguishable from sibling tools like get_site or list_sites, which focus on site metadata or enumeration 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 clearly signals when to use this tool: when you need traffic analytics for a site, optionally over a custom period. It does not explicitly name alternatives or exclusions, but the context is unambiguous enough that an agent would not confuse it with the site-management siblings.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, and the description is consistent with them. It adds value by stating that the response is a full list of all custom domains and that each entry exposes a recordId, which is directly useful for subsequent operations.

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 wasted words. The primary behavior is front-loaded, and the downstream usage detail is concise and directly relevant.

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

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

This is a simple read-only tool with one well-documented parameter, rich annotations, and an output schema. The description is complete for an agent to select and invoke the tool correctly, including the useful recordId linkage.

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 fully documents the single required parameter siteName with a clear description. The tool description does not add much beyond the schema, but with 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Return all custom domains attached to a site.' This clearly identifies the tool's purpose and differentiates it from related domain tools like add_custom_domain, 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?

The description explains a practical downstream use case: each returned entry has a recordId that can be passed to verify_custom_domain or remove_custom_domain. This gives clear context for when to use the tool, though it does not explicitly state exclusions or 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 mark this as read-only and idempotent; the description adds beyond that by declaring team-scoped results, default status filtering, and the 50-row limit. These are useful behavioral details not encoded in the annotations, though the description does not detail output ordering or pagination beyond the row cap.

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 short sentences, each carrying distinct information: scope, default filter, and result limit. It is front-loaded with the main purpose and contains no filler or restatement of the tool name.

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

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

For a read-only list operation with one optional parameter, rich annotations, and an output schema, the description covers scope, defaults, history behavior, and result limits. No critical missing context is needed for an agent to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents the single status parameter, its enum, and its default behavior. The description's mention of 'open + committing' and history inspection mostly restates that schema, adding no new parameter-level meaning beyond the overall 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 opens with a specific action and resource: 'Return staging sessions for the team this token belongs to.' This clearly distinguishes it from sibling list tools like list_sites and list_snapshots, and the default-behavior clause removes ambiguity about what a plain call returns.

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

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

The description explicitly says the default returns active sessions ('open + committing') and that 'Pass an explicit status to inspect history,' guiding the agent on when to supply the status parameter. It does not name alternative sibling tools or state when not to use this tool, so it falls just short of a 5.

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

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

Annotations already mark readOnly, idempotent, and non-destructive, and the description reinforces this by stating it does NOT create, change, or delete DNS records. It adds useful context about viewer permissions, ordering (oldest first), and the managed subset of records VibeDeploy tracks.

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

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

Three sentences with no filler: scope, return content/order, permissions, and read-only behavior are all covered. Every sentence contributes useful 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?

The tool has rich annotations, a complete input schema, and an output schema, so the description only needs to add behavioral context. It covers ordering, scope of records, permissions, and non-mutating behavior, which is sufficient for correct invocation.

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

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

Both parameters are fully described in the input schema (name and siteId), so schema coverage is 100%. The description adds no additional parameter-level meaning beyond the schema, earning the baseline score of 3.

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

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

The description uses a specific verb and resource ('Read the DNS records VibeDeploy tracks for a site') and clearly scopes to records created/managed on the user's behalf. It is clear but does not explicitly differentiate from sibling tools like list_custom_domains, so it stops short of a 5.

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

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

The description makes the read-only context clear and states that any team member, including viewers, can use it. However, it does not explicitly say when to prefer this over related domain/DNS tools, so there are no exclusions or alternatives named.

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

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint=false; the description adds meaningful scope behavior: it returns every currently served file, not a filtered or source-level list, and frames the result as a deploy-time diff baseline. 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?

Three sentences, with the core return value front-loaded in the first sentence and the redeploy workflow in the second. The SPA note earns its place by explaining why the tool produces dramatic savings in a common case.

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

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

Given the simple read-only operation, the annotations, and the presence of an output schema, the description supplies the necessary operational purpose and workflow. It is slightly incomplete only in not clarifying the site identifier semantics/defaults or when not to use it.

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

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

The description never mentions the site identifier parameters. The schema documents 'name' but leaves siteId with no description, and at 50% coverage the description should compensate; it doesn't. An agent must rely on schema or external context to know how the site is selected.

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

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

First sentence names a specific operation: return SHA-256 + size for every file currently served. This clearly separates it from sibling tools that manipulate source files or deploys. The description also gives a concrete use case (redeploy diffs), so an agent can recognize when this tool is intended.

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

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

Explicitly instructs to call this before re-deploying, and explains the diff-and-ship workflow, including how to use the result with update_site mode:'patch' or begin_deploy → add_files. It does not state when not to use it or compare it against sibling listing tools, so it stops short of a full routing rule.

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

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

Beyond the readOnly/idempotent annotations, the description discloses a 50-entry cap, newest-first ordering, the exact output fields, the optional nature of the label/snapshot, and access control ('Any team member can read history'). This adds substantial behavioral context.

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

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

Three sentences, front-loaded with the core action and limit, then the output fields, then access control. No filler or repetition of the schema.

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

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

The output schema and annotations cover much of the return and safety profile, but the missing parameter semantics and lack of explicit differentiation from list_deploys/list_snapshots leave an agent under-informed for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate, but it never explains 'name' vs 'siteId' or whether both/neither are required. 'for a site' gives only a general hint; 'name' remains ambiguous.

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

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

The description names a specific verb ('Return'), a clear resource ('deploy and snapshot history entries for a site'), and concrete scope ('most recent 50... newest first'). This distinguishes it from siblings like list_deploys and list_snapshots, which are narrower lists.

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 a combined-history use case by covering both deploy and snapshot entries, but it never explicitly says when to choose this over list_deploys or list_snapshots, nor does it mention exclusions. No alternative is named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds a small scoping detail about being tied to the connection's team, but does not disclose behavioral traits like default filtering of deleted sites or response characteristics; the includeDeleted behavior lives in the schema, not the description.

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

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

The description is a single, front-loaded sentence that directly states the action and scope with no filler. Every word earns its place, and it is appropriately concise for a simple list operation.

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

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

For a simple read-only list tool with one optional parameter, a rich output schema, and strong annotations, the description is sufficient. An agent knows what will be listed and under which team scope, and the schema covers parameter specifics.

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 fully documents the includeDeleted parameter, including its default and when to use true. The tool description itself adds no parameter-level meaning, which aligns with the baseline 3 for high schema coverage.

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

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

The description uses a specific verb ('List') and resource ('sites'), and adds a useful scoping detail ('for the team this connection belongs to'). It is clear and unambiguous, though it does not explicitly differentiate itself from sibling tools such as get_site or list_deploys.

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 no guidance on when to use this tool versus alternatives like get_site or other list_* tools. The only usage-related guidance appears inside the includeDeleted parameter description, not in the tool description itself, so the agent is left to infer selection 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 cover readOnly, idempotent, and destructive hints; the description adds valuable behavioral context beyond those: the NO_VOLUME error condition for never-deployed sites and the permission note that any team member can list. This is rich, non-obvious behavioral disclosure.

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 with the main action front-loaded. Every sentence adds useful content: scope, definition, permission, and an edge-case return value. No filler.

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

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

The description covers behavior and an important error case, and an output schema exists, so return values need no explanation. However, the two optional parameters remain underspecified, and the description does not resolve how an agent should select between name and siteId, leaving a meaningful gap for correct invocation.

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

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

Schema description coverage is 0%, and the description does not explain the meaning of 'name' versus 'siteId'. The phrase 'for a site' hints at scope but does not clarify which parameter identifies the site or whether they are alternatives, leaving real ambiguity.

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

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

The description states a specific verb and resource: 'List the Longhorn volume snapshots for a site.' It clearly distinguishes the tool from sibling create_snapshot and other list_* tools by naming the resource type and 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?

It provides clear context: snapshots are point-in-time backups, any team member can list them, and NO_VOLUME is returned for undeployed sites. It does not explicitly name alternatives or when-not-to-use scenarios, but the listing purpose is unambiguous.

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

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

This is an annotation contradiction. Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description states autoPromote/forcePromote can 'mirror the served dist into source' and 'copy dist → source,' which are mutating side effects. The description openly discloses mutating behavior while the annotations deny it, making the tool's safety profile unreliable.

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

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

Three sentences with no filler: the first defines the return value and object, the second gives the workflow, and the third explains the only surprising parameter behavior. Information is front-loaded and each 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 output schema covers return values and the schema covers forcePromote details, so the description doesn't need to repeat everything. However, the readOnlyHint contradiction is a serious completeness gap, and the description omits forcePromote's implications even though that parameter can overwrite source and change subsequent build behavior.

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%, and the description adds useful context for autoPromote but largely restates or pre-empts the schema text. name and siteId are left undocumented, and forcePromote is not mentioned in the description despite being a subtle, mutating parameter whose schema description carries important caveats.

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

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

The description states a specific verb and resource: it 'Return[s] SHA-256 + size for every file in the site's editable source tree' and immediately distinguishes that tree from 'the served dist'. This is clear enough for an agent to differentiate it from siblings like list_file_hashes or read_source_files.

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

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

The description gives explicit usage context: 'Use BEFORE editing so you know which paths exist and which haven't changed since the last build.' It also explains when autoPromote is relevant. It doesn't name alternatives or exclusions, but the primary workflow 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 read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond those annotations: the 5242880-byte per-call limit and the fact that larger files fail with FILE_TOO_LARGE rather than returning truncated bytes, which protects against corrupt downstream edits. 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?

Three sentences with no filler: the opening sentence states the core behavior, the second gives the workflow, and the third covers the size limit and path discovery. Every sentence earns its place.

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

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

For a single-file read tool, annotations cover the safety profile, the schema fully documents parameters, and the output schema covers return shape. The description adds the workflow, the size failure mode, and path discovery, so nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds little parameter-specific meaning beyond what the schema already documents. It does usefully point to get_site.filePaths for discovering valid paths, but that is more contextual guidance than semantic detail about the parameters themselves.

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 concrete operation: 'Return the bytes of one file currently served by the site.' The singular 'one file' and 'served by the site' clearly distinguish this from source-file readers and the plural read_files sibling, so an agent can tell what it does without ambiguity.

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

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

The description provides a clear workflow: 'call read_file → modify → update_site mode:"patch"' and directs agents to discover valid paths from get_site.filePaths. It does not explicitly name when-not-to-use alternatives like read_files or read_source_file, so it stops just short of full exclusion 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 and idempotentHint, so the tool is clearly safe. The description goes beyond annotations by disclosing the batch budget cap of 8388608 bytes and the exact failure mode BATCH_BUDGET_EXCEEDED, including how remaining paths behave. It doesn't explain response ordering in prose, but the schema note already covers that.

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

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

Three sentences with no redundancy: batch nature, per-file rules, and batch budget behavior are all covered compactly. The most decision-relevant fact (batched version of read_file) is front-loaded in the first sentence.

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

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

For a batch-read tool with readOnly/idempotent annotations and an output schema, the description covers the key operational constraints: size limit, per-file independence, and failure behavior. The only minor gap is not naming the required siteId parameter explicitly, but the title and read_file reference sufficiently anchor the context.

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

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

With 50% schema description coverage, the schema already documents paths and maxBytesPerFile, while name and siteId are only typed fields. The description adds that paths are fetched independently with the same per-file rules as read_file, which gives meaning beyond the raw schema. It doesn't explain name/siteId semantics, but those are inferable from the tool title and the same-rule pointer.

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 is the batched version of read_file, specifying the resource (multiple files from a deployed site) and the verb (read). The sibling list contains read_file, so naming it as the batched variant distinguishes it from the single-file tool and other read-related siblings like read_source_files.

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

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

The description explicitly says it is the batched version of read_file and that each file follows the same per-file rules as read_file, so an agent knows to use this when multiple paths need reading and read_file for a single path. It also gives an explicit error-based retry strategy for the batch budget, telling the agent to re-request remaining paths in another call.

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 readOnly, idempotent, non-destructive; the description adds context that this reads the editable source copy and is useful when original local files are unavailable. No hidden side effects are implied, and no contradictions with annotations exist.

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

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

Three purpose-driven sentences, with the core behavior front-loaded. The prerequisite and sibling routing are given in compact, unambiguous sentences with no filler.

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

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

For a read-only tool with strong annotations and an output schema, the description covers the essential call pattern and disambiguation. The only notable completeness gap is the unresolved semantics of name and siteId.

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

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

The schema documents path and maxBytes, but name and siteId have no schema descriptions and the tool description does not clarify them either. With only 50% schema coverage, the description needed to compensate for those opaque optional parameters and does not.

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

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

States a specific verb and resource: 'Return the bytes of one source file' from the platform's editable pre-build source tree. It also differentiates from read_file by explicitly targeting the editable copy, not 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?

Gives an explicit prerequisite ('Use list_source_files first to discover paths') and an explicit alternative ('For the served dist, use read_file instead'). An agent knows exactly when to choose this tool versus the sibling.

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

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

Annotations already mark the operation readOnly, idempotent, and non-destructive, so the bar is lower. The description adds valuable behavior: per-entry independence, non-aborting failures for missing/oversized files, a cumulative 8MB budget, and the exact BATCH_BUDGET_EXCEEDED error.

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 tight sentences with no filler. It front-loads the tool's purpose and batching scope, then packs constraints, failure behavior, and the error condition into the second sentence.

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

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

Batching mechanics and budgets are well covered, and the output schema fills in return-value details. However, with zero schema parameter coverage, the unexplained optional parameters create a meaningful gap, and there is no advice about choosing this over sibling read tools.

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%, so the description must compensate. It explains the paths array and the cumulative byte cap, but it leaves maxBytesPerFile, name, and siteId entirely unexplained. An agent cannot know the meaning or effect of those optional parameters from either the schema or the 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 clearly states a specific verb ('read'), a resource ('editable source tree'), and a batching scope ('up to 50 paths'). It distinguishes itself from single-file read tools like read_source_file through the word 'Batched', though it does not explicitly name any sibling tool.

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

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

The description implies batch usage but never says when to prefer this over read_file, read_files, or read_source_file. There is no explicit when-to-use or when-not-to-use guidance, and no 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 description discloses important behaviors beyond the annotations: auto-detection of URLs from HTML, SSRF-guarded downloads, size/count/time caps, atomic patch application, and skipping vibedeploy.be images. These details meaningfully inform the agent about side effects and safety constraints that annotations alone do not convey.

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

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

The description is dense but every sentence earns its place: the core operation comes first, followed by usage timing, safety limits, and implementation details. It is front-loaded and structured without 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?

For a tool with one parameter, an output schema, and rich annotations, the description covers all essential context: what it does, when to call it, what safety mechanisms apply, and what artifact is modified. There are no missing prerequisites or ambiguous aspects that would prevent an agent from invoking 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?

The schema already fully documents the single parameter with 100% coverage, establishing that 'name' is the site subdomain. The description reinforces the purpose ('whose external images should be downloaded and rehosted locally') but adds little beyond the schema. Baseline 3 is appropriate because the schema carries the semantic weight.

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 ('Download... store... rewrite'), names the exact resource (external images referenced by a site's HTML), and explains the outcome (removing the original dependency). It is clearly distinguishable from all sibling tools, none of which perform image rehosting.

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

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

It explicitly states when to call the tool: 'Call this once AFTER deploying a site rebuilt with the Website Converter.' This gives the agent a clear precondition and frequency, which is sufficient guidance for a tool with no ambiguous alternative among siblings.

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-read-only behavior. The description adds valuable scoping context beyond the annotations: the site is not destroyed, only the custom hostname is detached, and the default subdomain remains active. This meaningfully clarifies the blast radius of the operation.

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 short sentences with no filler. It front-loads the primary action, then clarifies scope, then notes the fallback service behavior. Every sentence contributes useful decision-relevant information.

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

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

For a destructive but narrowly scoped operation, the description is complete: it states what is removed, what remains unaffected, and which service continues to serve the site. The schema handles parameter specifics and the output schema covers return values, so nothing essential is missing.

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

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

The input schema documentation covers all three parameters with clear descriptions, including the domain-or-recordId choice. The description adds no parameter-specific details beyond the schema, so with 100% schema coverage the baseline of 3 is appropriate.

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

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

The description clearly states the action: removing a custom domain from a site, with the effect scoped to only the custom hostname. The title 'Detach a custom domain' reinforces the resource and operation, and the scope notes distinguish it from site deletion and from add/verify/list domain operations.

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 usage context by explaining that the site itself is unaffected and that the fallback subdomain keeps serving. This helps the agent use the tool for detaching a hostname rather than deleting the site, though it does not explicitly name alternative tools or exclusion conditions.

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 and idempotentHint, and the description adds useful behavioral context: literal vs basic regex search, the two target trees, and the prerequisite for searching source. It doesn't mention truncation or return shape, but the output schema covers budgetExceeded, so this is a reasonable burden split.

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 first states what the tool does, the second gives a concrete usage directive, and the third explains the key parameter option. The most important differentiation 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?

For a tool with 8 parameters, one required, an output schema, and safety annotations, the description covers the core decision points and workflow. It leaves name and siteId unexplained, but they are likely conventional context fields, and the schema covers pattern, regex, target, glob, maxMatches, and caseInsensitive.

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 75%, with name and siteId left undocumented in both schema and description. The description adds some value by explaining the target parameter's purpose and the source tree requirement, but it does not compensate for the two undocumented parameters.

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

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

The description names the exact verb and resource: 'Search for a literal string or basic regex across all files in either the served dist or the editable source tree.' It also distinguishes itself from batch-reading tools by framing it as the way to find candidates before reading, so an agent can tell this apart from read_files and 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?

The description is explicit about when to use it: 'Use this BEFORE batch-reading files to find candidates' and gives a concrete cost-saving rationale. It also gives a conditional guidance for choosing the editable tree with target: "source", including the Site.sourceStored=true prerequisite.

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 signal idempotent and destructive behavior, and the description adds substantial behavioral context beyond those flags: role requirements, null-to-disable semantics, the DNS verification workflow for custom senders, POST endpoint behavior, response shape, rate limits, and honeypot expectations. It clearly discloses that disabling the relay clears the config, matching destructiveHint. No contradiction with annotations exists.

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

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

The description is dense but every sentence carries operational value: configuration options, auth requirements, disable path, verification follow-up, submission format, limits, response shape, and honeypot guidance. It front-loads the core action and moves to progressively more specific behavioral details without repetition or filler.

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

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

For a complex configuration tool with nested settings, annotations, and an output schema, this description is exceptionally complete. It covers prerequisites, side effects, follow-up actions, runtime behavior, limits, and error response format. An agent has everything needed to decide whether to call the tool and to interpret the result.

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

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

The input schema already provides 100% coverage, so the baseline is 3. The description adds meaningful extra semantics such as the sender/smtpRelay verification dependency, the 'response returns DNS records' workflow, and runtime constraints like max field count and rate limits. These go beyond the schema's per-property descriptions, though some are runtime details rather than parameter-level clarifications, so a 4 is appropriate rather than 5.

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

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

The description opens with a specific verb and resource: 'Configure the built-in form-to-email relay', which clearly identifies the operation. It also differentiates from related siblings like get_forms_config and verify_forms_sender_domain by framing this as the configuration/write operation. The title 'Enable or update the forms relay for a site' is consistent and reinforces the scope.

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

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

The description gives clear context on when to use the tool: to configure, update, or disable the forms relay, including the explicit 'Pass config:null to switch the relay off' instruction. It names the follow-up verification tool verify_forms_sender_domain and states the required team role (owner/admin), but it does not explicitly say when to prefer a sibling such as get_forms_config for reading the current config. Overall it provides strong contextual guidance without a formal 'when not to use' boundary.

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

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

The description discloses crucial behavioral traits beyond the annotations: mismatched match counts abort the entire call with NO writes, edits are applied atomically, matching is literal rather than regex, and dist edits go live immediately while source edits require build_and_deploy. These details give the agent an accurate model of side effects and failure behavior. No contradiction with the destructiveHint=true 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?

The description is compact and well-structured: it opens with the precise purpose, then gives the targeted use case, then states the critical match-count behavior, then closes with the deployment consequence. Every sentence earns its place, and the most important operational warning is emphasized.

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 annotations, explicit schema, and output schema, the description is nearly complete for safe invocation: it covers what the tool does, when to use it, edit-count semantics, atomic failure, and required post-deploy steps. The main missing piece is explicit guidance on choosing this over the similarly named sibling apply_edits, which is more of a tool-selection gap than an invocation gap.

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

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

Schema description coverage is 100%, so the schema already fully documents every parameter. The top-level description mostly restates what the edits array and target field already say, such as count mismatch aborting with no writes and the dist/source deployment difference. It adds operational color but little genuinely new parameter-level 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 action: applying one or more literal find/replace edits to a single file in one call. It also gives concrete example use cases (nav-button reference, encoding fix, env var bump). However, it does not explicitly differentiate itself from the sibling tool 'apply_edits', so it stops just short of full sibling-level clarity.

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 strong usage context: use this for tiny edits where uploading the full file would be wasteful. It also explains the dist vs source follow-up requirement, naming build_and_deploy. It does not explicitly say when not to use this tool or mention the likely alternative apply_edits by name.

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

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

Annotations already flag destructiveHint=true, but the description delivers the missing context: exactly what gets destroyed in each mode (replace wipes the whole site; delete removes only listed paths), how to preview via dryRun, that it errors if the site doesn't exist, and the gzip+base64 server-side gunzip behavior. This is precisely the 'what gets destroyed' context the rubric rewards, with no contradiction against 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?

Roughly 140 words, front-loaded with purpose and the safe default (patch mode), with the replace warning placed immediately after and the LARGE FILES heuristic set off as a distinct callout. Every sentence carries non-obvious operational knowledge; no filler.

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

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

The description covers the full operational surface — modes, deletion semantics, dry-run preview, large-file encoding strategy, and the error condition — while the 100%-covered schema, annotations, and existing output schema carry parameter details and return shape. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% and the schema descriptions are already rich, so the baseline is 3. The description adds genuine beyond-schema heuristics: the 100–250 KB sizing guidance for choosing gzip+base64, the 'legacy behaviour, surfaced explicitly' framing for mode:'replace', and the routing preference away from the streaming alternative.

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

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

States a specific verb and resource ('Patch or replace files on an existing site') and immediately differentiates the two operational modes, patch vs replace. The 'existing site' scoping separates it from source-file siblings like write_source_files and update_file_content, and the mode contrast is the tool's core identity.

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 names the alternative pipeline ('prefer that over begin_deploy + add_file_chunk streaming') and the condition that selects this tool: 100–250 KB files with encoding:'gzip+base64'. It also gives when-not guidance — replace only when you genuinely want to wipe the rest, and dryRun before any destructive call.

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 explaining the actual side effect (attaching to ingress), the external dependency (DNS propagation delay), the recommended retry behavior, and the automatic HTTPS provisioning within ~30 seconds. This gives the agent a realistic model of how the tool behaves and what to expect. No contradiction with the annotations exists.

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

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

The description is three sentences with no filler. It front-loads the core action, then provides troubleshooting guidance, then states the outcome. Every sentence earns its place and the structure is easy to parse.

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

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

For a two-parameter tool with a rich description and an output schema present, all necessary context is covered: prerequisite step, failure mode, retry guidance, and post-success behavior. The annotations already cover idempotency and open-world behavior, so the description does not need to repeat them.

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

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

Schema description coverage is 100%, and both parameters are already documented in the schema. The description adds minimal extra meaning for parameters, though it does connect recordId to the step 1 flow. This meets the baseline for schema-covered parameters without adding significant new 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 states a specific action: checking the TXT record and attaching the domain to the site's ingress. It clearly identifies this as the second step in a two-step flow, distinguishing it from add_custom_domain and other domain-related siblings. The title reinforces the step-based 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 the correct workflow context by referencing 'the TXT record the user added at step 1', indicating this tool is used after add_custom_domain. It also tells the agent what to do on failure (wait and retry). It does not explicitly name alternatives or state when not to use the tool, but the step-based guidance is clear enough for correct selection.

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

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

Annotations provide openWorldHint and idempotentHint, but the description adds meaningful behavioral detail beyond them: the state change to 'verified,' the relay switching to the custom From with DKIM signing, fallback to the platform address until verified, and DNS propagation causing transient failures. This contextualizes side effects and retry behavior without contradicting the annotations.

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

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

The description is front-loaded with the core action, then efficiently explains the verification outcome, fallback behavior, retry guidance, and the smtpRelay exception. Every sentence carries useful information and none is filler or redundant with the schema.

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

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

For a single-parameter tool with an output schema and rich annotations, the description is complete: it covers the DNS records checked, the success/failure transition, retry rationale, and the case where this tool is unnecessary. An agent can correctly select and invoke the tool without missing key expectations.

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

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

The schema already documents the sole parameter siteName with 100% coverage, describing it as 'The site whose custom sender domain to (re)check.' The tool description reinforces the same concept but adds no new parameter-level detail, formats, constraints, or default behavior, so the baseline 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Check the DNS records for a site's custom sender domain (DKIM TXT + SPF include).' It also identifies the domain type (forms custom sender domain) and the verification workflow. It does not explicitly contrast with the sibling verify_custom_domain, so it stops short of full sibling differentiation.

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

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

The description gives clear when-to-use context: check DNS records, mark verified once DKIM is observed, and rerun if DNS propagation causes a first failure. It also provides a when-not-to-use condition: 'Not needed when the site uses a custom smtpRelay.' It does not explicitly name an alternative tool for that case, so it lacks a full alternatives statement.

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=false, destructiveHint=true, and idempotentHint=true. The description adds meaningful context beyond annotations: writes are staged, live dist is not affected until redeploy, and there is a specific failure mode for legacy sites. 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?

Every sentence earns its place: the first defines the operation, the second gives a prerequisite, and the third explains an important failure behavior. It is compact, front-loaded, and free of filler.

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

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

The description covers the staging workflow, redeploy requirement, and a failure mode, and an output schema exists so return values need not be explained. However, it leaves a significant gap around site identification (name vs siteId), which an agent needs to invoke 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 description coverage is only 33%, yet the description adds no parameter-specific meaning. The files array is well documented in the schema, but name and siteId have no explanation anywhere, and the description does not clarify how the site is selected or which identifier is preferred.

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 ('Stage edits') and resource ('a site's editable source tree') and immediately distinguishes it from the live dist. This clearly differentiates it from sibling write tools like add_files or update_file_content.

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 usage context: use list_source_files first, understand that the dist is unchanged until redeploy, and know that legacy sites may fail with SOURCE_STORAGE_NOT_ENABLED. It does not explicitly enumerate alternatives or contrast with add_files, but the guidance is strong enough for an agent to decide when 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.