VibeDeploy

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds genuine context beyond that: it scopes the destruction to staged files only ('live site is untouched') and discloses failure handling ('cleanup is best effort and retried later'), which directly explains why destructiveHint is false. It omits auth/permission requirements.

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, front-loaded with the core action, followed by the two facts that matter (live site untouched, cleanup retry). No filler, 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?

For a simple one-parameter tool with annotations and an output schema, the description covers the essential behavioral facts. It could go further by naming the commit_deploy alternative, but nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter (deployId) is fully documented as the id returned by begin_deploy. The description references the begin_deploy session but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Discard a begin_deploy session and its staged files') and names the originating sibling, begin_deploy, making it distinguishable from commit_deploy and begin_deploy without opening a schema.

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

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

The purpose implies when to abort (abandon a staged session), and the 'live site is untouched' clause helps an agent decide, but there is no explicit statement of when to use this versus commit_deploy or what happens to the session afterward. Usage is implied rather than spelled out.

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

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

Annotations already flag idempotentHint=true and destructiveHint=false, but the description adds real substance: the idempotency key (same siteName + domain returns the existing record), DNS propagation timing (minutes up to 24h), automatic re-checking for a few days, and an email notification on success. That is exactly the operational context an agent cannot get from the annotation block.

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 action and return payload, then behavior, then sequencing/prerequisite. No sentence is filler; timing and idempotency details are compactly packed.

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, non-destructive mutation with an output schema, the description covers the remaining burden: what is produced, how long it takes, what the caller does next, and what must exist beforehand. Return-value shape is delegated correctly to the output schema.

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

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

Schema description coverage is 100%, so both parameters are already documented as domain FQDN and site name. The description reinforces that the domain is user-owned and must be pointed at their DNS provider, but adds no format, validation, or edge-case detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Start attaching a user-owned domain to an existing site') and immediately says what the call returns: the DNS routing record plus ownership TXT record. The title's 'step 1 of 2' framing plus the named follow-up make it unmistakable versus verify_custom_domain or check_domain_availability.

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

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

Gives explicit when-to-use and sequencing: publish the records, then call verify_custom_domain with the returned recordId. It also names the prerequisite ('The site must already exist; call deploy_site first if it does not') and the alternative path when the site is missing.

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

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

Annotations only give the generic safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds operationally critical behavior the annotations cannot convey: chunks of one file must be sent serially because 'parallel chunks corrupt it', isFirst truncates an existing staged file, and after a transport error the file must be restarted from its first chunk rather than blindly resent.

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 opening sentence front-loads the use case and the alternatives follow in priority order, so nothing is buried. It is a single dense paragraph with several clause-chained rules, which is efficient but slightly harder to scan than a structured list would be.

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

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

This is a complex stateful chunked-upload protocol with 7 parameters, and the description covers the sequencing rule, the encoding requirement, the boundary flags, and the failure-recovery procedure. An output schema exists, so return values need not be restated, and nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter including isFirst, isLast, encoding and expectedByteOffset is already fully documented in the schema; the baseline of 3 applies. The description reinforces the ordering semantics of isFirst/isLast in a workflow context, but adds little parameter detail the schema does not already carry.

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 with its scope: 'Send one file in several calls when it is too big for a single tool call.' It goes further and names the sibling tools it exists to avoid (add_files, begin_deploy's uploadUrl, deploy_from_url), so an agent can distinguish it from them without opening any schema.

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

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

Explicitly frames itself as a last resort and gives the ordered alternatives with their capacity limits ('add_files with encoding:gzip+base64 (about 250 KB)', 'uploadUrl (one 100 MB tar POST)', 'deploy_from_url'). The when-to-use and when-not-to-use conditions are both present and unambiguous.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, so the safety profile is covered. The description adds real behavioral context: paths/extensions/encodings are validated on every call, and it gives sizing guidance (100-250 KB fits one call). It stops short of describing failure modes or error behavior, so not a full 5.

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, all front-loaded: purpose and workflow first, validation second, encoding/sizing tip and faster alternative last. No filler and every sentence carries actionable 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?

With an output schema present, return values need no explanation, and annotations carry the safety profile. The description covers the session lifecycle, repeated-call semantics, validation behavior, and encoding/size guidance, leaving nothing an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents path/content/encoding. The description still adds practical meaning by recommending encoding:'gzip+base64' with the local gzip-then-base64 recipe and a size range where it applies, which guides parameter choice beyond the raw enum.

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 (add files to a staging session) and names the lifecycle siblings begin_deploy and commit_deploy, so an agent immediately understands this is the staging step between them. It also distinguishes itself from add_file_chunk by contrast.

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

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

Explicit when-to-use: call repeatedly against an open begin_deploy session, then commit_deploy publishes. Names an alternative (prefer gzip+base64 over add_file_chunk) and even an out-of-band faster path (tar POST to uploadUrl), giving the agent concrete routing guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior: atomic all-or-nothing writes keyed to expected match counts, and the fact that dist edits go live immediately while source edits only ship via build_and_deploy.

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, front-loaded with the core action and then the two targets and the atomicity guarantee. Every clause carries distinct, decision-relevant information with no padding.

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

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

With an output schema present and rich annotations, the description need only cover behavior and routing. It covers targets, edit semantics, and the atomic failure mode, so nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining what each target tree implies operationally (live-at-once vs build-and-deploy) and by tying the count parameter to the all-or-nothing failure rule.

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 (apply literal find/replace edits), a specific resource (several files in one call), and scope (dist vs source trees). It is clearly distinguishable from the single-file sibling update_file_content, which it references.

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?

Explains the two target modes and their consequences (dist live at once, source shipped by build_and_deploy) and points to update_file_content for the edit rules. It gives clear context but never explicitly states when to prefer this over the single-file tool.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, and the description adds genuinely non-obvious operational constraints the annotations do not carry: a 5-open-session quota per token and a 1-hour expiry. It stops short of stating auth requirements or what happens to an expired/aborted session's staged files, so 4 rather than 5.

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

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

Three dense sentences, front-loaded with purpose then the routing rule then the limits. No filler; every clause carries an actionable fact.

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

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

An output schema exists, so return values need no explanation, yet the description still signals the key returned artifact (uploadUrl). With annotations, a complete workflow chain, quota and expiry all present, an agent has everything needed to invoke correctly.

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

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

Schema coverage is 100% and the schema itself fully documents both `mode` (replace vs patch semantics) and `name` (existing site, see list_sites). The description adds no parameter-level detail beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb and resource ('open a staging session for a deploy') and immediately scopes it against the common case, naming the sibling flow to use instead. An agent can distinguish this from deploy_site/update_site without opening either schema.

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

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

Explicit when-to-use rule ('only when the files do not fit in one deploy_site or update_site call'), plus the full follow-on workflow (add_files/add_file_chunk/tar POST, then commit_deploy). Alternatives and the selecting condition are both 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?

Beyond the destructive and non-idempotent annotations, the description discloses that the build runs in an isolated one-shot pod, that publishing is atomic and replaces served files, that a restore point is normally taken first, and that failed builds return their log in error details.

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 written sentences, front-loaded with the core action and followed by usage routing and persistence behavior. There is no redundant restatement 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?

For a destructive, open-world deployment tool with annotations and an output schema, the description covers the important behavioral context: what is replaced, the restore-point safeguard, the build environment, alternatives, persistence of settings, and failure logging.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds cross-call meaning: the first build saves buildCommand, outputDir, and rootPath on the site so later calls can omit them. It does not add much about name/siteId or saveManifest beyond what the schema already says.

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: build the stored editable source in an isolated pod and publish the output as the live site. It clearly distinguishes this from update_site, which is for already-built files, and names the source-editing siblings that precede it.

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

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

It explicitly says to use this after changing stored source via write_source_files or apply_edits with target 'source', and explicitly routes already-built uploads to update_site. The first-build manifest saving behavior is also called out so repeated calls are understood.

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

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds non-redundant behavior: it never buys, registers or reserves; prices include VAT where applicable; alternatives expands to a fixed TLD list; and the response reveals whether the user's plan permits domain purchase (purchase.dashboardUrl). This is more than the annotations cover.

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

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

Front-loads the purpose, then disambiguates with the read-only note and the alternatives scope. Slightly dense with four clauses, but every sentence carries information (safety, scope, cross-selling to add_custom_domain) rather than restating the title.

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 read-only lookup with a full output schema and rich annotations, nothing an agent needs is missing: cost basis (VAT), scope (single vs canonical TLD set), safety profile, and the follow-up path for already-owned domains are all stated.

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

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

Schema coverage is 100% and both parameters are fully documented in the schema, so the description's parallel explanation of 'alternatives:true' and the domain string adds no new syntax or format detail. Baseline 3 is appropriate since the schema carries the parameter burden.

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

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

States a specific verb and resource ('check whether a domain can be registered') plus the secondary output ('indicative price'), which uniquely distinguishes it from siblings like add_custom_domain or list_custom_domains. An agent can identify this as the only pre-purchase lookup tool without opening the schema.

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

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

Gives explicit when-to-use context ('Not tied to a site'), explicitly rules out the mutation path ('Read-only: it never buys, registers or reserves'), and routes the owned-domain case to the sibling add_custom_domain. It also explains when to set alternatives:true, which is the only real decision point in the 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?

Goes well beyond the annotations by disclosing the secret/malware scan gate, that a failed scan leaves the session open to retry or abort, and the exact confirm token for replace mode. The note that re-calling with the same deployId returns the running/finished commit rather than starting a second one is genuinely useful nuance. It is not fully contradictory to idempotentHint=false (a re-call does return a changed state), but the tension is worth noting; what's missing is any statement about authorization/permission requirements for a destructive live-site 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?

Front-loaded with the core action, then failure semantics, then the sibling routing rule at the end. The sentences are dense and nearly all earn their place; the confirm-token restatement slightly duplicates the schema at some cost to brevity.

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, open-world publish operation it covers atomicity, scan gating, failure/retry behavior, the replace-mode confirmation requirement, and the correct sibling choice. Since an output schema exists, no return-value explanation is required, and nothing an agent needs before invoking 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 deployId, delete, dryRun and confirm are already fully documented in the structured field descriptions. The description restates the confirm requirement and adds the deployId-reuse semantics, but adds no new syntax or format detail. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Publish a begin_deploy session's staged files to the live site') and pins down the atomicity and scan semantics. It also explicitly names the siblings that do the same job differently (deploy_site, update_site), so an agent can pick it out without reading schemas.

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

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

Gives an explicit when-to-use rule ('Use commit_deploy only to finish a begin_deploy session') plus the alternatives ('deploy_site and update_site publish in one call'). It also covers the retry path (call again with the same deployId) and the abort/retry option on scan failure, leaving little 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 readOnly=false, destructive=true, idempotent=false, openWorld=true, and the description adds substantial context beyond them: served content is unchanged, retention cleanup may prune older snapshots, container data is excluded, an owner/admin role is required, and the NO_VOLUME failure code is explained. This is rich, non-redundant behavioral detail.

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

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

Purpose and the restore-point framing are front-loaded, and each following sentence carries distinct information (side effects, exclusions, permissions, error code) with little waste. The first sentence is dense but does not bury the core action.

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

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

An output schema exists, so return values need not be described. For a mutating tool the description covers side effects, retention behavior, scope exclusions, permission requirements, and a documented error state, leaving nothing an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so name, label, and siteId are already documented in the schema. The description adds no syntax, format, or mutual-exclusion detail beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Take a point-in-time snapshot of a site's served files') plus the resulting artifact ('a restore point'). An agent can immediately distinguish this create operation from the sibling read tool list_snapshots without opening any schema.

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

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

The description frames the value context ('a restore point the user can restore ... within the plan's restore window') and lists a prerequisite role, so usage is implied. However it never states when to create a snapshot versus alternatives (e.g. deploys, automatic snapshots) or any when-not condition, leaving the agent to infer the trigger.

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

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

Goes well beyond the annotations: it discloses that deletion is soft/reversible, that serving stops immediately, that purging happens after the plan's restore window, that purgesAt appears in the result, and where restoration happens (dashboard). The destructiveHint and idempotentHint annotations only signal the safety profile; the description supplies the actual lifecycle semantics.

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 load-bearing: constraint first, then lifecycle/restore behavior, then sibling routing. No filler, and the most decision-relevant facts are 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 destructive 3-param tool with an output schema present, the description covers the safety profile, reversibility, timing, and sibling selection; return values need not be explained since purgesAt is referenced contextually and the output schema carries the rest.

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 name, siteId and confirm are already fully documented in the schema, and the description's 'confirm:true required' merely restates it. No additional syntax, format or interaction detail about the identity parameters is added, so baseline 3 applies.

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

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

Opens with a specific verb+resource+key constraint ('Soft-delete a site (confirm:true required)') and explicitly contrasts with the sibling remove_app, so an agent can distinguish it without opening either schema. The scope of destruction (whole site vs. container services) is unambiguous.

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

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

States the required precondition (confirm:true) and names the alternative tool with the condition that selects it: 'Use delete_site to remove the whole site; use remove_app instead to stop only its container services.' Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds real context beyond that: the deletion targets the editable source tree and does not affect served output until build_and_deploy runs, which is the non-obvious consequence an agent needs. It stops short of mentioning auth or irreversibility/confirm-step requirements.

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 tight sentences with no filler. The core action is front-loaded and the deferred-deploy caveat follows immediately, so nothing is buried.

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 and annotations covering the safe/destructive profile, the description only needs to supply the behavioral nuance, which it does via the build_and_deploy caveat. It could go slightly further on irreversibility of the source-tree deletion, but for this complexity level it is essentially complete.

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

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

Schema description coverage is 100%, so name, path, and siteId are fully documented in the schema itself. The description adds no parameter-level detail (no path format, no confirmation of the name/siteId alternative), so the baseline 3 applies.

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

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

States a specific verb ('Remove') and resource ('one file from the site's editable source tree'), and the source-tree qualifier cleanly separates it from served/deployed content and from delete_site. It does not explicitly name a sibling tool, so an agent still has to infer the boundary against write_source_files/apply_edits, keeping this just 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 implies the workflow ('served files do not change until build_and_deploy runs'), which hints at when deletion matters, but it never states when to use this instead of apply_edits, update_file_content, or write_source_files, nor any prerequisite. Usage is implied rather than stated.

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

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

Rich disclosure well beyond the annotations: services missing from the config are stopped (volumes kept), the others restart and pick up new source files, the call blocks until every service is ready and returns per-service status, and it enumerates hard limits (6 services, 2048Mi/2000m, 4 volumes, 3Gi). It also discloses the secrets model (dashboard-added secrets become env vars, secrets must never go in config/source/chat) and the snapshot caveat, none of which the annotations 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?

It is long but front-loaded — purpose and config-application behavior lead, operational details (public port, secrets, limits, snapshots) follow in order of relevance. Most sentences carry unique information; a few (e.g. the snapshot caveat) sit far from the main action but still earn their 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 nested-object, high-consequence mutation with no output schema, the description supplies the return value (per-service status), failure routing, resource limits, and the secrets/volume-retention semantics. An agent has everything needed to invoke it correctly and 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the "${generated:NAME}" placeholder for DB passwords, the rule that API keys/secrets must come from the dashboard rather than config, and the overall config-application semantics. These are operational facts the schema's shape description does not establish.

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 — run container services (server, database, workers) next to a site — and immediately constrains the scope to gVisor-sandboxed containers from any public image. This clearly separates it from the many sibling deploy tools (deploy_site, build_and_deploy, begin_deploy), which an agent can distinguish without opening a schema.

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

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

It gives a clear trigger (applying a whole services config next to a site) and routes the agent to an alternative on failure: 'if one is not ready, call get_app_status with logs.' However, it never explicitly contrasts this tool with other deploy siblings such as deploy_site or build_and_deploy, so the when-not-to-use boundary is left to inference.

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

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

Beyond annotations (which already flag destructiveHint/openWorldHint), the description discloses what replace mode destroys (other/live files are deleted), that exactly one wrapping top-level folder is stripped, that a confirm string is required on an already-populated site, and that a failed call never leaves a staging session open. This is meaningful behavioral context the annotations do not carry.

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

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

The description is front-loaded with purpose, then usage routing, then destructive-mode caveats, and every paragraph maps to an agent decision. It is dense and slightly long, with the dotfile/allowlist sentence partly restating the schema, so it is efficient but not maximally tight.

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

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

For a destructive, open-world composite tool, the description covers preconditions (existing site, public URL, allowed hosts, size/time limits), irreversible effects, the confirm safeguard, and failure atomicity; an output schema exists, so return-value detail is correctly omitted.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it explains the replace-vs-patch semantic at call level, the confirm token's live intent, and the file/type rules that cause an archive to be rejected with INVALID_FILE_TYPE. It largely defers host/limit details to the archiveUrl schema, which is appropriate.

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

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

The description states a specific verb chain on a concrete resource: fetch a public tar(.gz) over HTTPS and deploy its files to an existing site, explicitly framing it as begin_deploy + upload + commit_deploy combined. It names the target scope ('existing site', 'does not create sites') and contrasts itself with deploy_site and update_site, so an agent can distinguish it from the ~40 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?

It gives an explicit when-to-use (files already published at a public URL, e.g. a repo archive, or when the sandbox can reach allowed hosts but not mcp.vibedeploy.be) and a when-not with named alternatives (deploy_site or update_site). The preconditions for replace mode, including the confirm token, are stated up front.

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?

Although annotations already mark the tool as destructive and open-world, the description adds critical behavior: existing names delete every file not in the call, require the exact confirm token, and should be previewed with dryRun:true. It also explains payload handling via gzip+base64 and mentions the 404.html fallback behavior.

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

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

The description is dense but front-loads the core action and destructive behavior. It contains many operational details, all relevant, though the single-paragraph style makes it slightly less scannable than it could be.

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

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

For a destructive deployment tool with annotations and an output schema, the description covers the key risks, alternatives, confirm requirement, preview path, file-size workaround, and post-deploy domain step. 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 coverage is 100%, so the schema already documents parameter constraints. The description still adds useful semantics around name-based create-vs-replace behavior, the confirm token, dryRun preview effects, and encoding choices for larger text files.

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: publish a static site or SPA to a live HTTPS URL, with create-vs-full-replace semantics. It explicitly distinguishes this from update_site, which is used to change only some 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?

It gives clear routing rules: use this tool for new sites or full replacements, use update_site for partial changes, use begin_deploy only when files do not fit in one call, and preview with dryRun:true before replacing. The confirm token requirement is also stated explicitly.

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 clear. The description adds useful behavioral context: what account information is returned and why an agent should check it before plan-limited operations. It stops short of richer details like auth requirements, but the output schema and annotations cover most of the remaining burden.

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

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

Two tightly constructed sentences. The return contents are front-loaded, followed by a concrete pre-call recommendation. No filler and every clause carries 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 zero-parameter, read-only account-info tool with annotations and an output schema, the description is complete. It states what is returned, when to call it, and the operational reason, leaving nothing essential for the agent to infer.

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?

This tool has zero parameters, so there is no parameter semantics to explain. The baseline for a parameterless tool is 4, and the description correctly does not waste space on nonexistent inputs.

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

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

The description uses a specific verb (Return) and names the exact resource and fields: team plan, limits, current usage, trial end date, and per-token MCP rate limit. This clearly distinguishes it from all sibling tools, which are deployment, domain, file, and site 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?

It explicitly instructs the agent to call this before deploy_site or add_custom_domain to check a plan limit, and gives the concrete failure mode to avoid (PLAN_LIMIT_EXCEEDED). That is a direct when-to-use rule with named 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 cover the safety profile (readOnly, idempotent, non-destructive). The description adds meaningful behavior beyond that: it discloses that secrets are shown by name only and never by value, and that logs are optional and scoped to one service. It stops short of describing pagination or truncation behavior, so it is not a 5.

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

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

Front-loaded with the core purpose, then enumerates return contents, and ends with the sibling routing sentence. It is a dense single paragraph; a slight restructure could improve scannability, but there is minimal waste.

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 no output schema but with annotations carrying the safety profile, the description is nearly complete: it covers what is returned, the secret-name-only constraint, and the logs option. It could mention name/siteId selection but the schema already handles that.

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

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

Schema coverage is 100%, so all four parameters (logs, name, siteId, tail) are already documented in the input schema. The description only alludes to the optional logs behavior without adding format or default details beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Show the site's container services') and enumerates exactly what is returned (per-service status, config, secret names, optional logs). It also explicitly distinguishes itself from the sibling get_site: 'Use get_app_status instead of get_site for anything about containers.'

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 (get_site) and the condition that selects this tool ('anything about containers'). This is a textbook when-to-use vs alternative 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: what is actually returned (resolved delivery mode, active From address) and the conditional branch where custom sender domains yield DNS records plus verification status. It doesn't mention auth or permission requirements, which keeps it from a 5.

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

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

Two sentences, front-loaded with the primary read action and the returned payload, followed by a single routing pointer to the sibling tool. Every clause carries information; nothing is padded.

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

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

An output schema exists so return values need not be spelled out, yet the description summarizes them compactly and flags the conditional DNS/verification case. Combined with annotations covering the safety profile and a fully documented single parameter, 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?

There is a single parameter and schema description coverage is 100%, so the schema already defines siteName. The description confirms the scope ('of a site') but adds no format or resolution detail beyond the schema, making the baseline 3 correct.

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

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

The description states a specific verb ('Read') and resource ('the form-to-email relay config of a site'), then enumerates the concrete payload (delivery mode, active From address, DNS records with verification status). It also names the sibling that owns the related concern (set_forms_config), so an agent can place it precisely among the forms 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?

Usage context is clear: this is the read side of the forms-relay configuration for a given site, and the description routes the agent to set_forms_config for the submission format. It stops short of explicit when-not-to-use or prerequisite conditions, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds the scope of the read (e.g. last 10 deploys rather than all deploys, whether editable source is stored), which is modest value beyond what annotations plus the output schema 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?

Two sentences, front-loaded with purpose, then routing guidance. The enumeration of return fields is somewhat redundant given an output schema exists, which is the only real excess.

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 lookup with full schema coverage, no required params, and an output schema, the description covers purpose, alternatives, and content scope. It need not explain return values, and indeed the light redundancy there is the only 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% and both parameters (name, siteId) are documented with sourcing hints and an either/or note. The description adds nothing about parameter syntax or precedence, so the baseline 3 applies – the schema does all the work here.

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 one site's details") and enumerates the payload (live URL, status, plan, source/build settings, domains, bandwidth, last 10 deploys). It also explicitly separates itself from list_sites and get_app_status, so the agent can distinguish it from siblings without reading schemas.

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

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

Gives a concrete usage rule ("inspect a site before editing it") plus two named alternatives with the conditions that select them: list_sites for finding names, get_app_status for container services. Nothing about when to reach for this tool versus another is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds genuinely new behavior: a privacy guarantee ('Never exposes raw visitor IPs or user-agents') and the default aggregation window, which the agent could not infer from the structured fields.

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

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

A single front-loaded sentence that leads with the action and scope, then lists outputs, then the privacy caveat. No filler or repetition.

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

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

An output schema exists, so return values need not be explained, yet the description usefully summarizes them. Safety and privacy are covered; only the site-identifier selection guidance lives elsewhere, leaving a minor gap for a tool with three parameters.

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 all three parameters are already documented. The description only echoes the `period` default of 7, adding no syntax, constraint, or interaction detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Return a privacy-safe traffic summary for a site') and enumerates the exact contents (page views, visitors, top pages, daily counts, device/browser, Web Vitals). This clearly distinguishes it from the config-oriented get_site and the deploy/file 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?

Usage is implied by the name and the analytics content, but the description never states when to reach for this versus get_site or list_sites, nor any prerequisites such as needing a siteId from list_sites (that routing only appears in the schema). No explicit when-to-use 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 readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds substantive context the annotations cannot: returned entries carry a source discriminator and a recordId handle usable by verify_custom_domain/remove_custom_domain, and dashboard entries are out of reach of those tools. It does not mention pagination, ordering, or behavior when the site has no domains.

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

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

The core action is front-loaded in the first clause, and every subsequent clause (source split, recordId handle, dashboard limitation, dedupe precondition) carries information. It is delivered as one very long sentence, which makes it denser than ideal to parse, but there is 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?

Given one required parameter, full schema coverage, an output schema, and rich annotations, the description supplies exactly the missing piece: what the two groups of returned domains mean and what the agent can or cannot do with each. Nothing needed to select or invoke the tool correctly is absent.

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 single parameter siteName is already documented as 'The site whose custom domains to list.' The description adds no syntax, format, or edge-case guidance for siteName, so the schema does all the work and the baseline 3 applies.

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

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

States a specific verb and resource ('Return all custom domains attached to a site') and immediately scopes it: both MCP-added and dashboard-linked domains. The mention of the two sources distinguishes it cleanly from add_custom_domain, verify_custom_domain, and remove_custom_domain without needing the schema.

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

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

Explicitly says 'Call it before add_custom_domain to avoid adding a domain twice,' giving a concrete precondition and naming the alternative. It also signals the expected follow-on path: dashboard-sourced domains must be verified or removed on the dashboard, while 'mcp' entries carry a recordId for the MCP verify/remove tools.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so safety is covered. The description adds non-obvious behavior the annotations cannot convey: the default status filter and the 50-result cap, both of which affect the result set. It does not discuss pagination beyond the cap, but with an output schema present that is a minor gap.

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

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

Two sentences, front-loaded with the resource and scope, and the actionable workflow note comes second where it belongs. No filler; the only mild redundancy is the restatement of the default statuses already in 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 optional-parameter list tool with full annotations and an output schema, the definition covers scope, default behavior, result cap and intended use case. Return-value details are correctly left to the output schema, leaving little an agent would still need.

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 single enum parameter is fully documented there, including the default and the 'inspect history' rationale. The description restates the same default (open and committing) without adding format or edge-case detail, so baseline 3 is appropriate.

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

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

States a specific verb+resource (list the team's begin_deploy staging sessions) and immediately qualifies scope: default to active statuses and a 50-item cap. The reference to begin_deploy, commit and abort ties it directly to the sibling tools it complements, so an agent can distinguish it from list_history or list_snapshots without opening the schema.

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

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

Gives a concrete triggering scenario — 'useful after a crash or restart to commit or abort leftovers' — which tells the agent when this tool is the right entry point. It stops short of naming an explicit alternative or a when-not condition, so it is clear context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the closing sentence "Read-only: it never creates, changes or deletes a DNS record" largely restates structured data. It does add one genuine behavioral detail not in the annotations, the result ordering ("oldest first"), which is worth partial credit.

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 tight sentences with the substantive scope statement front-loaded and no filler. The second sentence is somewhat redundant against the annotations, which costs a little, but nothing is wasted or buried.

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

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

An output schema exists, so return values need not be described, and the annotations carry the safety profile. An agent can call this correctly from the description plus structured fields; only minor list-behavior details (pagination or result caps) are unaddressed.

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

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

Schema description coverage is 100% and the schema itself already explains the name/siteId choice ("Provide name or siteId"). The description adds no syntax, format, or precedence guidance beyond that, so the baseline 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?

Specific verb+resource ("Read the DNS records VibeDeploy tracks for a site") with the returned fields enumerated (host, type, value) and the scope clarified as "including custom-domain verification records." This distinguishes it from near-siblings like list_custom_domains and get_site without the agent needing to open a schema.

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

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

The description establishes clear context: use it to read the DNS records VibeDeploy tracks for a given site, and it implicitly rules out managing domains by scoping itself to records. It never explicitly names an alternative tool or states a when-not-to-use condition, 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?

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds the scope ('every served file') but says nothing about auth requirements, cost/latency on large sites, or result size limits — modest value beyond the annotations.

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

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

Two sentences, no filler: the first states what is returned, the second states the motivating workflow and the exact follow-up calls. Front-loaded and every clause earns its place.

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

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

An output schema exists, so return values need no explanation; the description covers purpose and the comparison workflow. It could have noted that the listing is unpaginated or expensive for large sites, but nothing essential for a correct call 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% and both params (name/siteId) are fully documented there, including the 'provide name or siteId' selection rule. The description adds no parameter semantics of its own, so the baseline 3 applies.

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

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

States a specific verb+resource ('Return SHA-256 and size of every served file') and scopes it to deployed/served files, which distinguishes it from siblings like list_source_files, read_files and search_files. An agent can identify the tool without opening any schema.

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

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

Gives an explicit workflow and named alternatives: hash local files, compare, then upload only changed ones via update_site mode:'patch' or begin_deploy + add_files. This is a real when-to-use directive referencing sibling tools, not vague context.

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

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

Annotations already cover the read-only and idempotent nature, but the description adds substantial behavioral context: a 50-entry limit, newest-first ordering, the fact that each snapshot holds content from before its entry, and that restoration happens outside the tool within the plan's restore window.

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 and return scope, then adds two compact sentences that clarify snapshot semantics and the absence of a restore tool. Every sentence carries relevant information without waste.

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

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

Given the output schema and annotations, the description is complete enough to call the tool correctly: it states the return limit, ordering, entry fields, snapshot timing, and the restore limitation. 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 description coverage is 100%, so both name and siteId are fully documented in the input schema. The description adds no additional parameter meaning, making a baseline 3 appropriate.

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

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

The description states a specific verb and resource: returns the site's last 50 deploy and snapshot entries, newest first. It distinguishes itself by combining deploy and snapshot history, but does not explicitly name or differentiate itself from sibling tools like list_deploys or list_snapshots.

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

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

Usage is implied by the purpose, and the description usefully states that restoring is done in the dashboard with no restore tool available. However, it gives no explicit guidance on when to choose list_history instead of sibling listing tools such as list_deploys or list_snapshots.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description adds non-obvious behavior in the ordering ('most recently updated first') and the hard 100-result cap. It doesn't say what happens past 100 (truncation vs. paging) and defers the soft-delete/restore-window semantics to the schema, so it's strong but not exhaustive.

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

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

Two sentences, zero filler, with the payload/ordering/cap front-loaded before the sibling routing. Every clause carries information an agent needs.

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

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

An output schema exists, so return values need no prose explanation, though the description redundantly lists the key fields. The only real gap is behavior at/after the 100-item limit; otherwise the definition covers everything required 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?

There is a single parameter with 100% schema description coverage, including default and restore-window semantics for includeDeleted. The description adds nothing about it and none is needed; baseline 3 applies where the schema does all the work.

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

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

States a precise verb+resource ('List the team's sites') plus the returned fields, ordering, and result cap, so the agent knows exactly what comes back. It also contrasts itself with get_site, making it distinguishable from the many siblings without opening a schema.

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

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

Explicitly routes the agent: 'Use list_sites to find a site name; use get_site for one site's files, source status and history.' The selection condition between the two list/detail siblings is stated, not implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real context beyond them: that restoration cannot be performed through the API at all, and that a snapshot is only restorable within the plan's restore window. It does not describe ordering or volume handling, which keeps it short of a 5.

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

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

Three short sentences, front-loaded with the core action and resource, with each remaining sentence carrying distinct information (the NO_VOLUME sentinel and the out-of-band restore constraint). 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description still fills the gaps that matter: the NO_VOLUME meaning and the fact that restore is not an API capability. Only the absence of any when-to-use routing keeps it from 5.

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 already document their source (list_sites/get_site) and the name-vs-siteId tradeoff. The description adds no parameter-level detail, so the baseline 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?

States a specific verb and resource ('List the snapshots of a site's served files') and immediately defines the domain term as point-in-time restore points. It also implicitly separates this from write/restore siblings by noting that restoring is a dashboard action, not an API call, so an agent can place it among create_snapshot and the deploy 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?

Usage is implied (inspect available restore points for a site) but never stated as when-to-use or when-not. There is no guidance on choosing this over list_deploys or list_history, which are the nearest informational 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 declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that: the exact returned fields (path/SHA-256/size) and the specific error code plus recovery path when no source tree 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?

Three short sentences: purpose and scope first, the read-only note, then the error/recovery path. Every sentence earns its place and nothing is buried.

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, return values need no further explanation, and the description still covers scope, safety, and the failure mode with recovery alternatives. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so name, siteId, and the deprecated autoPromote/forcePromote flags are fully documented in the schema. The description adds no parameter-level meaning beyond that, making the high-coverage baseline of 3 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 gives a specific verb (List) plus the exact returned fields (path, SHA-256, size) and scopes the resource to the 'editable source tree', explicitly distinguishing it from served files. It does not, however, differentiate itself from the sibling list_file_hashes, leaving a small ambiguity an agent must resolve.

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 names the failure condition (SOURCE_NOT_STORED) and routes the agent to alternatives (write_source_files, promote_dist_to_source), which is genuine when-to/alternative guidance. It stops short of an explicit 'use this rather than list_file_hashes/read_source_files' 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?

Annotations declare non-read-only, idempotent, non-destructive, but the description adds traits they cannot express: the served files are not modified, an already-sourced site is untouched, and force mode copies minified build output that is not original source. That last point surfaces a real consequence and a consent requirement beyond the structured 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?

Three sentences, front-loaded with the outcome and precondition, then consequences, then the caveat. No filler and nothing repeated from the name 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?

An output schema exists, so return values need not be described, and all three parameters are documented in the schema. The behavioral and usage context needed to invoke this safely (precondition, no-op case, force-mode risk) is fully covered.

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

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

Schema coverage is 100%, so the baseline is 3, and the description does add value by tying the mode parameter to a behavioral rule ('force only after telling the user that build output is not original source'). It does not further clarify name vs siteId, which the schema already handles.

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 (create/copy) and resource (the editable source tree) with an explicit precondition: a site that has none. It also names the downstream tools (write_source_files, apply_edits, build_and_deploy) that exist only after this runs, which cleanly separates it from siblings like list_source_files or write_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?

It gives the exact condition for use ('a site that has none'), the no-op case ('a site that already has source is left as is'), and a conditional rule for the risky path ('use mode force only after telling the user...'). That is when-to-use, when-not-to-use, and a gating instruction in one place.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description still adds real behavior beyond that: dual text/base64 encoding, a hard 5242880-byte ceiling, and the fact that oversized files fail with FILE_TOO_LARGE rather than returning truncated bytes. Auth requirements and pagination are unstated, keeping it short of a 5.

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: purpose first, routing second, limits and path discovery third. No filler and no repetition of structured fields; every clause carries a distinct constraint.

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, return-format detail is unnecessary, and annotations carry the safety semantics. Combined with the size cap, error behavior, sibling routing, and path source, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema already documents name/siteId/path/maxBytes well. The description adds value the schema does not: that maxBytes is an error threshold rather than a truncation control, and that valid paths come from get_site.filePaths.

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 one file the site serves now') plus the encoding contract (utf8 text or base64 for binary). It explicitly distinguishes itself from read_source_file, so an agent can separate the two without opening either schema.

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

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

Gives an explicit routing rule: 'Use read_file for the served files; use read_source_file instead for the editable source tree (get_site.sourceStored).' It also names the downstream follow-up (update_site mode:'patch') and the discovery path (get_site.filePaths), so both when-to-use and alternatives are covered.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds context they cannot express: the 8 MiB aggregate batch budget, the 50-file ceiling, and the concrete BATCH_BUDGET_EXCEEDED error plus remediation. It stops short of mentioning permissions/auth requirements, so it is not exhaustive.

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

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

Two sentences, no filler, and the most important constraint (batch size and total budget) is front-loaded before the routing pointer. The raw byte count is precise rather than padded.

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

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

An output schema exists, so return format need not be explained. Between the batching limits, the error contract, and the sibling routing, an agent has everything required to call this correctly on the first attempt.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds the aggregate byte budget that governs how the four parameters interact (per-file caps plus a total cap that the schema does not show). It also ties behavior back to read_file's per-file rules, which is meaning beyond the schema.

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

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

States a specific verb and resource with explicit scope: 'Read up to 50 served files in one call.' The word 'served' plus the pointer to read_source_files cleanly separates it from the source-tree readers and from single-file read_file, so an agent can pick it without opening a schema.

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

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

Gives an explicit alternative and the condition that selects it ('Use read_source_files instead for the editable source tree'), and adds a failure-recovery rule: paths past the budget fail with BATCH_BUDGET_EXCEEDED and should be re-requested in a separate call. Both when-to-use and what-to-do-on-failure are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety and idempotence profile is fully covered by structured data. The description adds genuinely useful context about what the source tree is (pre-build code that lets a chat edit the site without local files), but says nothing about truncation behaviour for large files, the effect of the maxBytes cap, or error behaviour on a missing path.

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, zero waste, front-loaded with what is returned before the routing guidance. Each sentence earns its place: identity, path discovery, and alternative selection.

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

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

An output schema exists, so return shape needn't be restated, and the annotations carry the safety profile. Combined with the explicit sibling routing and the path-source pointer, nothing an agent needs in order to call 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 description coverage is 100% and all four parameters (name, path, siteId, maxBytes) carry their own descriptions including defaults and caps, so the schema does the heavy lifting. The description adds nothing parameter-specific beyond that, which is acceptable when coverage is this high, though a note that path must be a source-tree path from list_source_files would have been a small bonus.

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 one file from the site's editable source tree'), and immediately clarifies what the source tree is ('the stored pre-build code'). It distinguishes itself from read_file explicitly and names list_source_files as the path source, so an agent can place it against the read_file/read_source_files/list_source_files cluster without opening any schema.

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

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

Gives an explicit selection rule: 'Use read_source_file for source; use read_file instead for the files the site serves.' That is when-to-use, when-not-to-use and the named alternative in one sentence, plus a pointer to list_source_files for discovering valid paths.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, yet the description still adds meaningful behavior: per-path independent success/failure, the BATCH_BUDGET_EXCEEDED failure mode, and the 8388608-byte total budget. This is exactly the kind of partial-failure semantics an agent needs before batching.

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 batch scope and sizing, then behavioral failure semantics, then the sibling routing. No filler and every sentence carries distinct 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?

An output schema exists, so return-value explanation is unnecessary; the description covers scope, budget limits, failure behavior, and alternative selection. Nothing needed to invoke this 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 coverage is 100%, so the baseline is 3; the description earns above that by disclosing the total batch byte budget (8388608) that is not present in the schema and by framing paths as order-preserving with independent outcomes. Per-file cap and path count are already in the schema, so no additional credit there.

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 (Read), resource (source tree files), and batch scope (up to 50 files in one call). It is clearly distinguishable from the singular sibling read_source_file and from read_files, which the description names explicitly.

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

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

Explicitly routes the agent: 'Use read_source_files for source; use read_files instead for the files the site serves.' The when-to-use-this vs. when-to-use-alternative decision is fully stated with no inference required.

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

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

Annotations declare the safety profile (destructive, idempotent, open world), and the description adds genuinely new operational detail: SSRF guarding, size/count/time caps, atomic patch-mode application, and that platform-domain images are skipped. This is substantially more than the annotations provide.

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

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

Dense but front-loaded: the core action comes first, then usage timing, then behavioral caveats. Every clause carries information, though the second and third sentences are long and could be tightened.

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

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

An output schema exists, so return values need no explanation, and the description covers the prerequisites, side effects, and safety limits an agent needs before invoking a destructive-but-idempotent mutation.

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

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

Only one parameter and schema description coverage is 100%, so the schema already defines 'name' fully. The description reinforces that images are auto-detected from the site's own HTML (i.e. no URL list is passed), which is mildly useful, but adds no syntax or format information.

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

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

States a specific verb chain (download, store, rewrite) with a concrete resource and destination path (assets/img/), and distinguishes itself from deployment siblings like deploy_site by describing a post-deploy normalization step. An agent can identify exactly what this does without opening the schema.

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

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

Gives explicit timing and precondition: 'Call this once AFTER deploying a site rebuilt with the Website Converter.' That is clear when-to-use guidance, though it names no alternative tool or when-not-to-call condition (e.g. a site with no external images).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the specifics an agent needs: what happens to the site (falls back to static files), what survives by default (volumes/database data), and that deleteData is a permanent, irreversible deletion. This is exactly the "what gets destroyed" context that annotations alone cannot convey.

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

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

Three short sentences, all front-loaded: scope and effect first, data-retention caveat second, sibling routing third. No filler, and the highest-stakes information (irreversibility) is not buried.

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

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

For a zero-required-param mutation tool with no output schema, the description covers everything an agent needs: the operation, the default-safe behavior, the irreversible flag, and the alternative sibling. No return-value explanation is needed since no output schema exists and the description states the end state instead.

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 name, siteId and deleteData are already documented with their formats and defaults; baseline 3 applies. The description's note that volumes hold database data and are deleted "for good" largely restates the schema's "Also delete every volume (database files)... Irreversible," adding only marginal meaning over structured data.

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?

"Stop every container service of the site" names a specific verb (stop) and resource (container services), and immediately states the observable outcome ("the site serves its static files again"). It also explicitly distinguishes itself from the sibling delete_site, so an agent can route without opening either schema.

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

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

Explicit when-to-use routing: "use remove_app to stop only the containers; use delete_site to remove the whole site." It also gives the condition that changes the risk profile (deleteData true vs false), leaving nothing 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds genuinely useful scope detail: the site itself is unaffected and keeps serving on its platform subdomain, clarifying exactly what does and does not get destroyed.

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 short sentences, front-loaded with the core action and immediately followed by the most important consequence. No padding or redundancy.

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

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

With an output schema present and annotations covering the safety profile, the description need not explain returns. Parameters are fully covered by the schema. Only the absence of when-to-use/alternative guidance keeps it from a perfect score.

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

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

Schema description coverage is 100%, so all three parameters (domain, recordId, siteName) are already documented in the schema, including the 'provide this or that' pairing and the domain example. The description adds no parameter-level detail, so the baseline 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 gives a specific verb ('Detach') and resource ('custom domain') paired with the site, which is clear and unambiguous. It doesn't explicitly distinguish itself from siblings like add_custom_domain or verify_custom_domain, but the verb choice makes the operation obvious.

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

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

There is no explicit when-to-use guidance or mention of alternatives such as add_custom_domain or list_custom_domains. The only contextual hint is that the site continues on its subdomain, which is behavioral rather than routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's scope statements ('served files by default', 'editable source tree with target source') largely restate the target parameter description, and it adds no details on result truncation, match limits, or site-selection requirements.

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 compact sentences; the core capability is front-loaded and the workflow hint follows. No filler, no repetition of schema detail.

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

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

With an output schema present, the description need not explain return values, and it covers scope, modes and workflow placement. Given eight parameters, it could note the result cap/truncation behavior and site scoping more explicitly, but 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%, including the glob filter, regex flag, target enum, maxMatches cap and siteId/name choice, so the schema carries parameter meaning. The description only echoes the regex and target distinctions, adding no syntax or format guidance beyond it — the baseline 3 applies.

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

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

States a specific verb and resource ('Search every file of a site') plus the two match modes (literal string or regular expression) and the two search scopes (served files vs. editable source tree). An agent can distinguish it from read_files/read_source_files without opening any schema.

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

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

Gives clear conditional guidance — 'Use it before reading files in bulk, to find the ones that matter' — which establishes the intended workflow position relative to the read_* siblings. It stops short of explicitly naming read_files/read_source_files or stating when not to use it, so it isn't a full 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 declare destructiveHint=true and idempotentHint=true. The description adds value beyond them by disclosing the auth requirement (owner/admin), replacement semantics ('Full config... replaces existing'), and the disable/clear behavior of null.

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

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

Front-loaded with purpose and next-step before details. It is on the long side because it carries submission mechanics (POST JSON, field/char limits, honeypot, rate limit) that are tangential to invoking the config tool, but the structure is logical.

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

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

With annotations covering the safety profile and an output schema present, the description need not restate returns. It covers auth, replacement behavior, and the verification workflow, leaving little an agent needs 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 already 100%, so the baseline is 3. The description still adds meaning: it groups the config surface (custom From via verified domain or SMTP relay, Reply-To, branding) and explains the sender-without-smtpRelay DNS-record flow.

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

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

States a specific verb+resource: 'Configure the built-in form-to-email relay.' It is easily distinguished from siblings get_forms_config (read) and verify_forms_sender_domain (verification), and even states the disable case ('config:null to switch the relay off').

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

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

Clear context and prerequisites ('Requires team role owner or admin') and an explicit next-step route ('then call verify_forms_sender_domain'). It does not explicitly name get_forms_config as the read alternative, so it stops short of 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 destructive/non-idempotent/openWorld, but the description adds the crucial atomicity contract ('any mismatch aborts the call with no writes') and the differing deploy semantics of dist vs source. These are high-value behavioral traits beyond what the structured fields 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?

Four tight sentences, front-loaded with the core action, then atomicity, then deploy timing, then the sibling pointer. Every sentence carries distinct information with no padding.

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

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

With a 100%-covered schema and an output schema handling return values, the description supplies exactly the missing pieces: atomicity guarantee, dist/source behavior, and sibling routing. Complete for a mutation tool of this 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 name/path/edits/target and the nested count semantics are already fully documented. The description reinforces 'literal' and the expected-match-count idea but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Apply literal find/replace edits to one file') with the scope qualifier 'in one call' and explicitly routes multi-file work to apply_edits. An agent can distinguish it from siblings like apply_edits, write_source_files, and read_file without opening a schema.

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

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

Gives an explicit when-to-use rationale ('for small changes where uploading the whole file is wasteful'), names the alternative for the multi-file case ('Use apply_edits for several files'), and clarifies the dist-vs-source timing consequence with build_and_deploy. Nothing about tool selection is left to inference.

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

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

Annotations already declare destructiveHint/idempotentHint, but the description goes further: it explains exactly what gets destroyed in each mode (replace deletes every unlisted file), how delete interacts with patch, and the SITE_NOT_FOUND failure mode. This is real behavioral context 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?

Front-loaded with the core action, then mode semantics, then preview and sibling routing, then the size/encoding tip and failure mode. Every sentence carries information; nothing is padding.

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

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

With a rich schema, full annotations, and an output schema, the remaining burden is usage routing, destruction semantics, failure modes, and payload sizing — all present. Nothing an agent needs to invoke this safely and correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by tying parameters to concrete guidance not in the schema — the 100-250 KB single-call threshold for encoding:'gzip+base64', the preview discipline for dryRun, and the delete+files rename combination — rather than merely restating field meanings.

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

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

States a specific verb and resource ('Change files on an existing site') and immediately names the sibling it is not ('Use deploy_site instead to create a new site'). An agent can distinguish this from deploy_site, add_files, and update_file_content without opening a schema.

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

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

Gives explicit when-to-use routes: deploy_site for creating sites, dryRun:true before replace mode or deletes, and gzip+base64 preferred over begin_deploy plus add_file_chunk for 100-250 KB payloads. Alternatives and the conditions selecting them are spelled out.

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

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

Adds real context beyond the annotations: it has a serving side effect (site starts serving), issues certificates asynchronously within a minute or two, and returns a per-record remediation list on failure. The re-check note reinforces idempotentHint with practical meaning. It does not spell out whether the domain must be the only one affected or what happens to existing traffic during propagation, so not quite a 5.

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

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

Front-loads the verification-and-serve behavior, then failure semantics, then timing/retry notes — each clause carries information. It is a dense run-on sentence where a small amount of structure would improve scannability, which keeps it below a 5.

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

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

Covers prerequisite, side effects, failure output shape, propagation latency and retry safety, which is enough for an agent to call it correctly; return values need not be explained because an output schema exists. Only the comparison against DNS-inspection alternatives is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented, including that recordId comes from add_custom_domain. The description repeats the add_custom_domain linkage but contributes nothing new about the parameter values or formats; baseline 3 applies.

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

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

States a specific verb and resource ('check the records ... and, when both are right, start serving the site on that domain') and anchors itself as the step after add_custom_domain. The agent can distinguish it from siblings like check_domain_availability, list_dns_records, add_custom_domain and verify_forms_sender_domain without reading the schema.

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

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

Makes the prerequisite explicit ('the records from add_custom_domain', title says step 2 of 2) and gives retry guidance ('calling it again on a verified domain is a harmless re-check'). It doesn't address alternative situations, e.g. when to inspect DNS with list_dns_records instead, or when it's premature to call this.

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

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

Goes well beyond the annotations by disclosing the resulting state change: once DKIM is observed the domain is marked verified and mail relays from the DKIM-signed custom From, otherwise it falls back to the platform address. The annotations mark this non-read-only and idempotent, and the description explains exactly what mutates and confirms safe re-running.

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

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

Four tight sentences, front-loaded with the verification action, then the outcome, then operational timing advice, ending with the exclusion. No filler and every sentence contributes actionable 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?

An output schema exists, so return values need not be described. For a state-mutating verification tool the description covers the trigger, the consequence, fallback behavior, retry guidance, and the case where it isn't needed at all.

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

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

Only one parameter with 100% schema description coverage, so the schema already carries the semantics; the description merely implies that the site's sender domain is the target and that the check is repeatable. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a precise verb and resource: checking DNS records (DKIM TXT + SPF include) for a site's custom sender domain. This is clearly distinguished from the sibling verify_custom_domain, which concerns hostname DNS rather than sender-domain DKIM/SPF records.

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 exclusion ('Not needed when the site uses a custom smtpRelay') and practical timing guidance ('DNS can take a few minutes to propagate; re-run if it fails'). It does not name a sibling tool to use instead for other verification needs, but the when/when-not framing 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 destructive/idempotent/open-world, and the description layers on genuinely new behavior: writes are staging-only until build_and_deploy, the tree is lazily created, and legacy sites fail with SOURCE_STORAGE_NOT_ENABLED along with the user-facing remedy. That is exactly the error-mode and side-effect context annotations cannot convey.

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

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

Four sentences, each load-bearing: action, deploy semantics, prerequisite, failure mode. The core operation is front-loaded and nothing is padding.

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

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

An output schema exists, so return values need no explanation, and the description covers side effects, prerequisites, and the error path. The remaining gap is routing among the several other file-mutation siblings, which the description never addresses.

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%, including path/encoding semantics, size caps, and the 'same wire shape as add_files' note, so the schema carries parameter meaning on its own. The description adds no format, encoding, or limit detail beyond it, which makes 3 the correct baseline.

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

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

States a specific verb pair (write/overwrite) and a precise resource ('the site's editable source tree'), plus the non-obvious detail that the first write creates the tree. It does not distinguish itself from near-neighbours like add_files, update_file_content, or apply_edits, which is the only thing keeping it from 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?

Gives clear context: check with list_source_files first, and edits stay invisible to visitors until build_and_deploy runs. It stops short of naming the alternative write tools (add_files, apply_edits, update_file_content) or stating when to prefer one over the other, so no explicit exclusions.

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