vibedeploy

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

Annotations provide readOnlyHint and destructiveHint, but the description adds critical behavior: immediate return, best-effort cleanup, and retry by sweeper. This goes beyond the annotations to inform the agent of asynchronous and non-blocking 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?

Two sentences with no wasted words. The first sentence defines the action and scope, the second adds important behavioral context. Each sentence earns its place.

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

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

For a simple tool with one parameter and an output schema (presumably standard), the description fully covers what the tool does, its side effects, and return behavior. No gaps remain.

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

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

Schema coverage is 100% with a single parameter deployId described as 'Session id to abort.' The description adds no further parameter-level details, but the schema itself is sufficient. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool discards a staging session and its scratch dir, with the specific verb 'discard' and resource scope. It distinguishes from siblings like commit_deploy by clarifying that it aborts rather than finalizes a deploy.

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

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

The description implies when to use this tool (to cancel a staging session) and that it does not affect the live site, providing clear context. It does not give explicit when-not or alternative tools, but the purpose is unambiguous given the name and sibling tools.

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

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

Beyond annotations (idempotentHint: true), the description explains how idempotency works in practice ('calling twice returns existing record'), mentions the TXT record return, DNS propagation timing, and the prerequisite about the site's subdomain. No contradictions with annotations.

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

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

The description is a single paragraph with front-loaded purpose, followed by idempotency behavior, next steps, and prerequisite. Every sentence adds value with no redundancy.

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

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

Given the existence of an output schema (not shown but indicated), the description covers purpose, behavior, prerequisites, and workflow integration (step 1 of 2). It is fully complete for a tool with 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?

Input schema has 100% coverage for 2 parameters, but the description adds context by explaining 'siteName' is the vibedeploy.be site name and 'domain' is the user-owned hostname, which enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Start attaching a user-owned domain to an existing site. Returns a TXT record.' It distinguishes from the sibling 'verify_custom_domain' by positioning itself as step 1 of 2, providing specificity and differentiation.

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

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

The description explicitly outlines when to use the tool (step 1 of domain attachment), prerequisites (site must exist on a vibedeploy.be subdomain, otherwise call deploy_site first), and next steps (call verify_custom_domain after TXT propagation). This gives clear guidance on usage and alternatives.

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

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

Annotations already indicate a write operation (readOnlyHint=false) but the description adds rich behavioral context: explains that the first chunk truncates and creates directories, the last triggers size stat, warns about corruption from concurrent chunks, and details practical chunk size limits. Adds significant value beyond annotations.

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

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

Description is fairly long but well-structured with clear focus. It front-loads the purpose and usage, then provides detailed parameter guidance. Every sentence adds value; no unnecessary repetition. Slightly verbose due to thoroughness but appropriate for the tool's complexity.

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

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

Given the tool's complexity (7 parameters, output schema exists), the description is remarkably complete. Covers chunking protocol, encoding options, alignment check, size limits, and even alternative methods for large uploads. No gaps identified.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond schema by providing practical chunk size guidance (~80KB base64) and mentioning alternative approaches (deploy_from_url, POST to upload URL). This extra context justifies a 4.

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

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

The description clearly states the tool's purpose: streaming a single file across multiple calls when content exceeds the per-MCP-call budget. It explicitly distinguishes from the sibling tool 'add_files' by specifying that add_files is for normal-sized files and add_file_chunk is for larger files.

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

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

Provides explicit when-to-use (file exceeds output budget) and when-not (use add_files for normal-sized files). Also gives critical guidance on sending chunks serially to avoid corruption, with a clear warning: 'Send chunks for the same path serially — concurrent chunks interleave and corrupt the file.'

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

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

Discloses beyond annotations: validation on every call ('bad file fails fast'), overwrite behavior ('Re-adding a path overwrites'), and cumulative 500 MB cap. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

Four sentences, each essential: purpose, usage pattern, validation behavior, capacity limit. No redundancy, front-loaded with 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?

Sufficiently complete for 2-param tool with output schema. Covers validation, overwrite, cumulative cap, and relation to commit_deploy. No gaps that would mislead an agent.

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

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

Schema coverage is 100%, but description adds significant context: encoding options (utf8, base64, gzip+base64), wire shape alternatives (map vs array), and overwrite behavior. Enhances understanding well beyond raw 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?

Description starts with 'Append files to an open staging session,' clearly stating the operation (append) and resource (files to staging session). It distinguishes from siblings like 'add_file_chunk' and 'commit_deploy' by emphasizing the incremental addition and batch commit pattern.

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 as many times as needed; commit_deploy applies them all at once,' providing clear usage context. Does not explicitly exclude alternatives like 'add_file_chunk' but the staging session context is well-defined.

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

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

The description adds critical behavioral details beyond annotations: atomicity across files, count semantics (default 1, -1 for all, positive for exact), and validation-before-write order. No contradiction with annotations (destructiveHint=true is consistent).

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 serving a distinct purpose: defining the tool, explaining per-file edit behavior, and describing atomicity. No redundant or extraneous text.

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

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

Given the tool's complexity (batch atomic edits with count checks), the description provides all necessary context for correct invocation. It covers batch limits, atomicity, and count semantics. Output schema exists but is not shown; the description does not need to explain return values.

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

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

Description clarifies count parameter semantics that go beyond the schema's min/max. Also, the schema's description for files mentions the 25-file/200-edit limit, but the description reinforces all-or-nothing behavior. Schema coverage is 67%, and the description compensates effectively.

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

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

Description clearly states it's a 'Multi-file find/replace in one tool call' and 'Batch sibling of update_file_content', specifying the verb (apply) and resource (edits across files). This distinguishes it from the single-file sibling.

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

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

The description labels it as a batch sibling of update_file_content, strongly implying single-file edits should use the sibling. However, it does not explicitly state when not to use or list alternatives, though the sibling tool is named.

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

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

Annotations already indicate non-read-only (readOnlyHint=false) and non-idempotent (idempotentHint=false). The description adds valuable behavioral details: session opening, active session limit, and default TTL. No contradictions with annotations.

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

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

Four sentences, each delivering essential information: core action, use case, workflow pairing, and constraints. Information is front-loaded and no extraneous content.

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

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

The description covers the tool's purpose, when to use it, the required workflow, and active session limits. Given that an output schema likely documents return values, it is nearly complete. Could mention error handling or session lifecycle, but it is already robust.

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 parameter descriptions in the schema are detailed. The description adds minimal extra meaning beyond the schema (e.g., clarifying 'replace' behavior). With high coverage, baseline is 3; the description does not significantly enhance parameter understanding.

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

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

The description clearly states the verb 'opens' and the resource 'staging session' for a multi-call deploy. It distinguishes from sibling tools like deploy_site and update_site by explicitly noting the tool is for sites too large for a single call.

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

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

The description gives explicit usage context ('when the site is too large to fit in a single deploy_site/update_site call') and outlines the required workflow (pair with add_files or tarball upload, then commit_deploy). It also notes constraints (5 active sessions, 1 hour TTL). It could mention abort_deploy as an alternative for cancellation, but the guidance is clear.

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

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

The description adds significant behavioral context beyond annotations: it details the isolated pod environment, atomic swap, and manifest mutation. It does not contradict the annotations, and provides a thorough account of what happens during execution.

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 appropriately sized, each sentence adds meaningful information, and it front-loads the core action. While slightly technical, it remains efficient without being overly verbose.

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

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

Given the tool's complexity (6 optional parameters, output schema present, many siblings), the description covers workflow, prerequisites, isolation, and manifest behavior. It does not explicitly address failure modes, but is otherwise thorough.

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

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

With 67% schema coverage, the description adds value by explaining the manifest persistence for buildCommand and outputDir, clarifying how these parameters behave across calls. However, it does not compensate for the undocumented 'name' and 'siteId' parameters.

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

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

The description clearly states the tool's function: building from an editable source tree and atomically deploying. It distinguishes from sibling tools by mentioning the hardened one-shot pod, editable source, and manifest persistence, making it specific and unique.

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 advises writing source first via write_source_files and explains the manifest behavior for first vs subsequent runs. However, it does not explicitly state when to use this tool versus other deploy tools like deploy_site or begin_deploy, nor does it provide exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. Description adds that the price is gross (21% VAT) and indicative, and that no changes are made. This provides useful context beyond annotations, though the core safety is already covered.

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

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

Description is concise with two sentences that are front-loaded. It uses a clear structure with an important note highlighted. No redundant information.

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

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

With annotations and an output schema present, the description provides sufficient context: read-only nature, price details, alternatives behavior, and requirements. The tool is well-explained for an AI agent.

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

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

Schema coverage is 100%, but description adds significant value by explaining the effect of the alternatives parameter and listing the TLDs checked. The domain parameter includes an example format. This enriches the schema definitions.

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

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

Clearly states the tool checks domain registration availability and returns an indicative price. The verb 'check' and resource 'domain availability' are specific, and the tool is distinct from siblings which deal with site management and deployment.

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

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

Description explicitly states the tool is a read-only lookup that does not buy or register domains. It also explains when to use the alternatives parameter. While it does not explicitly mention when not to use this tool versus others, the context makes it 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?

Adds significant context beyond annotations: atomic apply, preflight and malware scan, session persistence on failure, and the confirm gate. No contradiction with annotations.

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

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

Two sentences, clear and to the point. Slightly dense but not overly verbose. Could be broken into steps for readability.

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

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

Covers key aspects for a destructive tool: atomic commit, scans, failure handling, and replace-mode requirement. Output schema exists, so return value explanation not needed.

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

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

Schema coverage is 100%, so description minimal per-parameter detail. Description adds overall context but doesn't explain parameters beyond schema. Baseline 3.

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

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

Clearly states the tool atomically applies a staging session's files to the live site, distinguishing it from sibling tools like abort_deploy and begin_deploy.

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

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

Provides context on when to use (for committing staged files), mentions preflight and scan, failure behavior, and the special confirm requirement for replace-mode. Does not explicitly mention alternatives but is clear overall.

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

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

The description adds significant behavioral context beyond annotations: it clarifies the tool is additive, non-destructive, records a history entry, runs retention cleanup, and returns NO_VOLUME if the site has no volume. No contradiction with annotations.

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

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

The description is four sentences, tightly packed with essential information, no redundant phrases, and front-loaded with 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?

The description covers purpose, behavior, user restrictions, and an error case. Missing parameter details slightly reduces completeness, but the presence of an output schema partly compensates.

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

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

Schema description coverage is only 33% (one param has a description). The tool description does not explain any parameters or their roles, leaving the agent without guidance on how to use name, label, or siteId beyond the minimal schema info.

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

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

Description clearly states the tool takes a point-in-time Longhorn snapshot of a site's served files, explicitly distinguishing it from destructive operations by noting it's additive and does not change anything served. It differentiates from sibling tools like list_snapshots and delete_site.

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

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

The description provides context for when to use the tool (to create a manual backup) and adds a constraint (viewers cannot create snapshots). However, it does not explicitly compare with alternatives or give a when-not-to-use scenario.

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

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

Discloses that deletion is soft with a recovery window, that confirm=true is required, immediate effects (hostname freed, stops serving), and future purge. Also notes response includes 'accepted' and 'purgesAt' fields. This adds significant context beyond annotations.

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

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

Four sentences with no fluff. Key information is front-loaded: 'Soft-delete a site. confirm=true is required.' Efficient and scannable.

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

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

Covers behavior, response, and usage flow. Lacks mention of which identifier (name or siteId) is required or error handling, but output schema exists for details. Adequate for typical use.

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?

Reinforces that confirm must be exactly true, which adds meaning beyond schema's const constraint. Does not explain name or siteId, but they are typical identifiers; with low schema coverage (33%), the description compensates somewhat.

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

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

Clearly states 'soft-delete a site' and explains the effect (status deleted, hostname freed, stops serving). Distinguishes from sibling tools like delete_source_file or remove_custom_domain by focusing on site-level deletion.

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

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

Explicitly says 'Use this for the normal remove this from my dashboard flow', giving clear usage context. Does not mention when not to use or alternatives, but the description implies it's the standard deletion method.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds the key behavioral detail that only the source tree is affected, not the served dist. However, it omits error conditions or side effects for missing paths, making the transparency adequate but not thorough.

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 only two sentences, front-loaded with the core action. Every word serves a purpose, with no redundant information.

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

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

Despite having an output schema, the description lacks completeness for a destructive tool with many siblings. It does not explain required parameters, success/error outcomes, or how it interacts with other file operations, leaving significant gaps for an agent.

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

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

With only 33% schema description coverage, the description should compensate by explaining the parameters. It does not mention 'name', 'path', or 'siteId' beyond what the schema provides. The term 'one file' is too vague to clarify parameter usage.

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

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

The description clearly states the verb 'Remove' and the resource 'file from the site's editable source tree', distinguishing it from sibling tools like 'delete_site' or 'update_file_content'. It specifies the scope (source tree only) and notes that the served dist is unchanged.

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

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

The description provides minimal usage context, only implying that the tool is for source files. It does not explicitly state when to use it versus alternatives like 'delete_site' or 'read_source_file', nor does it offer exclusions or prerequisites.

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

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

Annotations indicate destructiveHint=true, and the description confirms destructive behavior. It adds extra behavioral details: server-side fetch, size/timeout limits, host allowlist, and equivalence to a multi-step process. No contradictions with annotations.

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

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

The description is concise (5 sentences) but packs essential information: purpose, mechanism, use case, constraints, and alternatives. Front-loaded with key verb and resource. No wasted words.

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

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

Given 3 required params, full schema coverage, output schema exists, and annotations present, the description is complete. It covers when to use, constraints, and the one-call nature, providing all necessary context for correct tool 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 has 100% coverage, but description adds significant value beyond schema: for archiveUrl it lists allowed hosts, max size, timeout; for mode it reinforces the 'replace' vs 'patch' semantics. The description also explains the one-call equivalence.

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

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

The title and description clearly state the tool's purpose: deploy a site from a public archive URL. It uses specific verbs and resources and distinguishes itself from siblings like begin_deploy, commit_deploy by explaining it's equivalent to the three-step process in one call.

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

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

The description explicitly tells when to use this tool: when the sandbox can reach archive hosts but not the upload endpoint. It names alternatives (begin_deploy → upload → commit) and mentions the hostname allowlist constraint.

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

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

The description warns that the tool is destructive on existing sites, replacing every file and deleting files not in the call. It aligns with the destructiveHint annotation and adds context about the confirm requirement and rejection without it. No contradiction with annotations.

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

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

The description is relatively long but front-loaded with the main purpose and structured with clear warnings and usage guidance. Every sentence adds value, though it could be slightly more concise without losing essential details.

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

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

Given the tool's complexity (4 parameters, destructive behavior, output schema), the description covers deployment to live URL, automatic SSL, custom domain mention, destructive nature, confirm, dryRun, and alternative tools. It lacks explicit output schema details but is adequate for effective use.

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?

All parameters have descriptions in the schema (100% coverage), but the description adds extra value: it explains when confirm is needed, what dryRun does, and the two file input formats (array for binary, map for UTF-8). It also clarifies encoding options, surpasssing baseline expectations.

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

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

The description clearly states the tool publishes a website to a live URL, specifying it deploys static sites or SPAs to a {name}.vibedeploy.be address with automatic SSL. It distinguishes between creating a new site and fully replacing an existing one, which differentiates it from sibling tools like update_site.

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

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

The description explicitly tells when to use this tool vs. alternatives: 'Use update_site (default mode:'patch') if you want to add or change individual files without removing the rest.' It also recommends using dryRun:true to preview changes and explains the required confirm flag for existing sites.

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

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

Annotations already declare readOnlyHint true, destructiveHint false, idempotentHint true. The description adds behavioral context about rate-limit ceiling and header, which goes beyond annotations.

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

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

Two sentences, front-loaded with purpose, then usage, then additional info. No wasted words.

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

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

Given output schema exists, the description does not need to explain return values. It covers purpose, usage, and extra rate-limit info, which is complete for this tool.

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

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

No parameters, so schema coverage is 100%. Baseline 4 applies. Description does not need to add param info.

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

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

The description clearly states the tool returns the team's plan, limits, and usage. It uses specific verb 'Return' and resource 'team's plan, limits, usage'. It distinguishes from siblings by mentioning usage for deploy_site and add_custom_domain.

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

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

Explicitly says when to use: 'Use this BEFORE deploy_site or add_custom_domain to know whether a deploy would trip a plan limit'. It also implies when not to use: 'instead of provoking PLAN_LIMIT_EXCEEDED'.

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, so the description adds context about what specific data is returned (endpoint, delivery mode, DNS records). The submission instructions are peripheral but do not contradict annotations.

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

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

The description is lengthy and includes extensive submission instructions (rate limits, honeypot, etc.) that are not directly about the tool itself. These details could be moved to an output schema or separate documentation, reducing front-loaded clarity.

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 simplicity (one required parameter, read-only), the description covers the purpose and key return values adequately. The output schema likely provides additional structure, so the description is complete enough despite containing extraneous submission details.

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

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

The only parameter, siteName, is described in the schema with identical wording ('The site whose forms-relay config to read'). Since schema coverage is 100%, the description adds no extra value beyond the schema's description.

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

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

The description explicitly states 'Read the form-to-email relay config of a site', providing a specific verb and resource. It distinguishes from siblings like 'set_forms_config' and 'verify_forms_sender_domain' by its read-only nature.

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 clearly indicates the tool is for reading config, but does not explicitly state when not to use it or provide alternative tools. However, the context of siblings implies when to use other tools. The inclusion of submission instructions could confuse the tool's intended usage.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by listing the returned fields (name, url, plan, etc.), providing clarity beyond the annotations. No contradictions.

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

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

The description is a single, efficient sentence with no unnecessary words. It conveys the essential information without redundancy.

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

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

While an output schema exists (reducing need to explain return values), the description fails to address how parameters are used—e.g., whether both are required, which takes priority, or behavior with missing parameters. This gap leaves the tool incomplete 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?

The input schema has 0% description coverage for parameters. The description does not explain the purpose or usage of 'name' and 'siteId', failing to add meaning beyond the schema. For a tool with undocumented parameters, the description should compensate but does not.

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

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

The description clearly states the verb 'Return' and specifies the resource as site details, listing specific fields. It distinguishes from sibling tools like 'list_sites' which returns all sites, and 'get_site_analytics' which is for analytics.

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

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

The description implies usage for retrieving details of a specific site, which is clear from context. However, it does not explicitly state when to use this tool versus alternatives, such as using 'list_sites' for multiple sites, nor does it provide exclusions.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds privacy safety details (no raw IPs or user-agents) and lists return components, providing valuable behavioral context beyond annotations.

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

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

The description is two concise sentences with no wasted words, front-loaded with the primary purpose.

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

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

Given the presence of an output schema (not shown), the description adequately covers all needed information: purpose, parameters, safety, and return summary. No gaps identified.

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

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

Schema coverage is 100%, so baseline is 3. The description adds the default value for 'period' and hints at mutual exclusivity of 'name' and 'siteId', providing added meaning beyond the schema.

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

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

The description clearly states the tool returns a privacy-safe traffic summary for a site over a specified period, specifying the verb 'Return' and the resource, and distinguishes from siblings as no other tool deals with analytics.

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

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

The description provides clear context on what the tool does and mentions default period, but does not explicitly state when to use it versus alternatives or when not to use it. However, since no sibling tool provides similar functionality, the implicit usage 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 readOnlyHint and idempotentHint; the description adds that the tool returns all custom domains with a recordId, which is consistent and provides extra context.

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

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

Two sentences, no redundancy, action front-loaded, every word adds value.

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

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

Given the simple tool, existing output schema, and annotations, the description fully covers necessary information for an agent to use the tool correctly.

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

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

With 100% schema description coverage for the only parameter (siteName), the description adds no additional parameter meaning beyond the schema, meriting the baseline score.

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 resource ('custom domains attached to a site'), and distinguishes from siblings by mentioning recordId usage in related tools.

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

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

The description provides context by noting that recordId can be used with verify_custom_domain or remove_custom_domain, but does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds value by noting the 50-row limit and default status filter, which are useful but not critical behavioral 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?

Two short, direct sentences with no unnecessary words. Information is efficiently presented.

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

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

Given the tool's simplicity (1 optional parameter, no required params, output schema present), the description fully covers purpose, default behavior, and usage. No gaps.

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

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

Schema coverage is 100% with a single parameter. The description enhances it by explaining why the default is 'open' and 'committing' (actionable ones) and suggesting the use of explicit status for history. This adds practical context beyond enum values.

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

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

Description clearly states the tool returns staging sessions for the team, with default filtering to active ones (open + committing) and a row limit of 50. This is specific and distinguishes from sibling tools like begin_deploy or commit_deploy.

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

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

The description explains default behavior and how to inspect history by passing an explicit status. It does not mention alternatives or when not to use, but the sibling context makes it clear this is the primary list tool for staging sessions.

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?

Description reinforces annotations by stating read-only and non-destructive, adding that records are managed on behalf of the user and ordering. Annotations already cover safety; description adds context about scope and permissions.

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

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

Three concise sentences, no fluff. Key action stated first, then details, then safety note. Optimal structure for agent consumption.

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 list tool with rich annotations and output schema, description covers ordering, permissions, and scope. No missing critical information.

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

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

Schema coverage is 100% with descriptions for both parameters. Description does not add new meaning beyond 'provide name or siteId'. Baseline score of 3 is appropriate as schema already documents parameters well.

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

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

Description clearly states it reads DNS records managed by VibeDeploy for a site, specifies ordering (oldest first) and returned fields (host, type, value). Distinguishes from sibling tools like list_custom_domains which deal with custom domains, not DNS 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?

States when to use: to read DNS records. Notes that any team member can use it. Lacks explicit when-not-to-use or alternatives, but context of siblings shows no other DNS reading tool, so guidance is adequate.

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. Description adds context about returning data for all files served but no further behavioral traits like rate limits or failure modes. Consistent with annotations.

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

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

Three sentences: first states purpose, second gives primary use case, third provides concrete example. Efficient and front-loaded, but the example could be merged with the use case.

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

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

Given two parameters, output schema present, and comprehensive annotations, the description is complete. It explains the tool's role in a deployment workflow and how to use it with sibling tools.

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

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

Schema coverage is 50%: name parameter has description referencing get_site lookup rules; siteId has no description. Description does not elaborate on siteId. Partially compensates for missing schema details but leaves a gap.

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

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

Description clearly states it returns SHA-256 and size for every file currently served, using specific verb+resource. It distinguishes from siblings like list_source_files by focusing on hashes.

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

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

Explicitly advises using before redeploying to skip unchanged files and references alternative deployment methods (update_site mode:'patch', begin_deploy → add_files). Provides clear when-to-use and how-to-use context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns most recent 50 entries, ordering, and included fields. It also adds access context ('Any team member'). No contradictions.

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

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

The description is two sentences long, with the first sentence stating the core purpose and output, and the second adding access context. It is front-loaded and contains no unnecessary words.

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

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

The description explains what is returned (most recent 50 entries, fields) and ordering, but does not mention pagination, how to get more than 50, or which parameter is required (likely siteId). The output schema exists but is not shown; description is adequate but has gaps.

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

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

Schema description coverage is 0%, meaning no descriptions for parameters 'name' and 'siteId'. The description does not explain what these parameters represent or when they are needed. It fails to compensate for the lack of schema documentation.

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

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

The description clearly states the verb 'return' and resource 'deploy and snapshot history entries' with specific scope ('most recent 50', 'newest first'). It distinguishes from sibling tools like list_deploys and list_snapshots by combining both types.

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 mentions 'Any team member can read history' which gives permission context but does not explicitly state when to use this tool versus alternatives like list_deploys or list_snapshots. No when-not or alternatives 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, destructiveHint. The description adds no additional behavioral traits beyond the purpose. No contradiction with annotations.

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

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

Extremely concise single-sentence description. Parameter guidance is detailed but lives in the schema. No wasted words.

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

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

With output schema present, return values need no explanation. Description covers core purpose. Could mention team scope or pagination, but simple list tool with one optional param seems adequately specified.

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

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

Schema description coverage is 100% for the single parameter 'includeDeleted', which already includes explanation. The tool description does not add meaning beyond the schema, so baseline 3.

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

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

Clear verb+resource (list sites). Scope 'for the team this connection belongs to' adds specificity. Does not explicitly differentiate from sibling tools like 'get_site' or 'list_deploys', but the name 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?

No explicit when-to-use or alternatives guidance for the tool overall. However, the 'includeDeleted' parameter description provides context on when to use it vs default, offering implicit usage 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 provide readOnlyHint=true and destructiveHint=false. The description adds useful context: permission info ('Any team member') and a specific error return (NO_VOLUME when no volume exists), which goes beyond annotations.

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

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

The description is three sentences with no wasted words. The main action is first, then context, then error condition. Perfectly front-loaded and concise.

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

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

Given an output schema exists (not shown), return value explanation is not needed. The description covers purpose, permissions, and a failure mode, but lacks parameter explanations. For a simple list tool, it is adequate but not fully 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 0%, so the description must compensate. It does not explain the parameters 'name' and 'siteId' at all—neither their purpose nor whether they are optional. The agent has to guess their 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?

The description clearly states the verb 'List' and the resource 'Longhorn volume snapshots for a site'. It explains what snapshots are (point-in-time backups) and distinguishes from siblings like 'create_snapshot' by focusing on listing.

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

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

The description mentions 'Any team member can list snapshots' indicating no special permissions, and describes a failure condition (NO_VOLUME). However, it does not provide explicit when-not-to-use guidance or comparisons to alternative tools.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context about the return values (hash and size) and the special behaviors of autoPromote and forcePromote beyond what annotations provide.

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

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

Three sentences efficiently convey purpose, usage, and special behavior without redundancy. The structure is front-loaded with core functionality.

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

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

Given the tool's complexity (4 parameters, output schema, annotations), the description fully explains behavior, return values, and edge cases (autoPromote/forcePromote), making it comprehensive for a listing tool.

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

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

Schema covers 50% of parameters with descriptions for autoPromote and forcePromote. The tool description expands on these behaviors but does not add meaning for name and siteId, which remain generic strings.

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

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

The description clearly states it returns SHA-256 and size for every file in the editable source tree, distinguishing it from sibling reading tools like 'read_source_file' by focusing on metadata instead of content.

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

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

Explicitly advises use before editing to know existing paths and detect changes, providing clear context. However, it does not explicitly mention alternatives like 'read_source_file' for reading content.

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. The description adds crucial details: size limit (5242880 bytes), failure mode (FILE_TOO_LARGE rather than truncation), and rationale for not splitting bytes. This goes well beyond annotations.

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

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

Three sentences, front-loaded with the core purpose. Every sentence adds distinct value: purpose, usage pattern, size constraint, and file discovery. No wasted words.

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

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

The description covers purpose, usage, size limits, error behavior, and path conventions. Output schema likely handles return value details. Only minor gap: no mention of encoding or base64 return, but output schema probably covers 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 baseline is 3. The description adds value by explaining the size limit behavior and path conventions (no leading slash, no '..'), which are not fully captured in the schema descriptions.

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

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

The description explicitly states it returns the bytes of one file and distinguishes from siblings like read_files (plural) and read_source_file. The use case for inspection and editing is clear.

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

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

The description provides a concrete usage pattern (read_file → modify → update_site) and mentions using get_site.filePaths for discovery. It doesn't explicitly state when to avoid using this tool, but the context is sufficient.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds important behavioral details: batch limit (50), total byte cap (8388608), per-file rules same as read_file, and explicit error handling (BATCH_BUDGET_EXCEEDED). No contradictions with annotations.

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

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

The description is three sentences, front-loaded with key information (batched version, limits, error). Every sentence adds value without redundancy or fluff.

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

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

Given the presence of annotations and an output schema, the description is largely complete. It covers limits, error handling, and references per-file rules from read_file. It does not repeat output schema details, which is appropriate.

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

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

Schema description coverage is 50% (paths and maxBytesPerFile have descriptions; name and siteId do not). The description adds context about the batch behavior and total byte cap but does not explain the name or siteId parameters. It partially compensates for the coverage gap.

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

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

The description clearly states it is a batched version of read_file, specifying the verb (read), resource (files from a deployed site), and scope (batch of up to 50 paths). It distinguishes itself from the sibling read_file by being a batch operation.

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

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

The description provides clear guidance on usage: pass up to 50 paths, each fetched independently with the same per-file rules as read_file, and a total byte cap. It implies when to use (batch reading) but does not explicitly state when not to use or compare to other siblings beyond read_file.

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

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

Annotations already declare readOnlyHint=true, so the tool is read-only. The description adds useful context: it returns bytes, targets the editable source tree, and mentions the maxBytes parameter for size caps.

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, each focused and purposeful. First sentence states the core action, second provides usage context. No wasted words.

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

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

The description covers the main purpose and usage, and an output schema exists to explain return values. However, it omits explanations for two parameters (name, siteId) and does not mention that the tool reads only a single file, which is clear from the schema.

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

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

Schema coverage is 50% (descriptions for path and maxBytes). The description reinforces path's meaning but does not clarify name or siteId parameters, which lack schema descriptions. This adds some value but does not fully compensate for missing parameter info.

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

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

The description specifies 'Return the bytes of one source file', clearly stating the verb and resource. It distinguishes from siblings by referencing list_source_files for discovery and read_file for the served dist.

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

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

Explicitly states when to use this tool versus alternatives: 'For the served dist, use read_file instead.' Also provides prerequisite: 'Use list_source_files first to discover 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?

The description adds significant behavioral details beyond annotations: per-entry independence, error handling, cumulative byte cap, and batch budget error, which are not covered by readOnlyHint or idempotentHint.

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

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

Two concise, front-loaded sentences with no wasted words.

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

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

Covers key behavioral aspects (batch independence, error mode, budget limit) and output schema exists, but could mention that result is per-path. Still sufficiently complete for a read tool with annotations.

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

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

Schema description coverage is 0%. Description explains 'paths' and cumulative cap but does not detail 'name', 'siteId', or 'maxBytesPerFile', partially compensating for missing schema descriptions.

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

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

The description clearly states 'batched read across the editable source tree' with a specific resource and limit of 50 paths, distinguishing it from siblings like single-file reads.

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

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

The description explains the batched read behavior and error isolation but does not explicitly say when to use this tool versus siblings like 'read_source_file' for single files.

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

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

Discloses SSRF-guarded downloads, size/count/time caps, atomic application, and skipping of images already hosted on vibedeploy.be. Annotations confirm idempotent (hint true) and non-destructive (false), with no contradictions.

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

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

Three sentences, each adding essential information. No fluff. Front-loaded with main action, then constraints and context. Highly efficient.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description covers all necessary behavioral and usage aspects. No gaps.

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

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

Only one parameter (name) with 100% schema coverage. Description adds context beyond schema by clarifying that it's the site whose external images should be processed, and that the site must already be deployed.

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

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

The description clearly specifies the action (download, store, rewrite HTML references), resource (site's external images), and scope (local rehosting). It distinguishes itself from sibling tools by stating it auto-detects images and is for use after deploying a site rebuilt with the Website Converter.

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 instruction to call once after deploying a site rebuilt with the Website Converter. No explicit when-not-to-use or alternatives, but the context makes it clear this is for external image rehosting, not for other tasks.

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

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

Description adds context beyond annotations: it clarifies that the site itself is unaffected despite destructiveHint=true, and that the vibedeploy.be subdomain continues serving. This addresses potential concerns about destructiveness.

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

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

Two concise sentences with no filler, front-loading the purpose and providing essential behavioral details.

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

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

Given the tool has 3 params (1 required), input schema with full coverage, and an output schema, the description adequately explains the core action, effects on the site, and idempotent nature implied by annotations.

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

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

Schema coverage is 100% with detailed descriptions for each parameter (e.g., explanation of mutual exclusivity of domain vs recordId). The description does not add significant extra 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?

Title 'Detach a custom domain' and description clearly state the action: remove a custom domain from a site. It specifies the scope (only the hostname is detached, site unaffected) and distinguishes from sibling tools like add_custom_domain.

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

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

The description makes clear when to use the tool (to detach a custom domain) and implies that the site remains served via the default subdomain. However, it does not explicitly list when not to use it or provide 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?

Disclosures: read-only behavior (matching annotations), literal vs regex mode with limitations (BusyBox grep BRE, no PCRE), glob pre-filtering via find, maxMatches truncation reported, target behavior. Adds value beyond annotations.

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

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

Two succinct sentences: first defines core function, second provides actionable guidance. No redundant or filler content.

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

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

Given 8 parameters (1 required), available output schema, and annotations, description covers essential behavior, usage advice, parameter caveats, and limitations. No significant gaps.

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

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

Schema coverage is 75%; description adds context for key parameters (target requires sourceStored, regex limitations, glob applied before grep, maxMatches cap). Does not describe every parameter but fills practical gaps.

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

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

Description specifies verb ('Search') and resource ('files across a site's files') with clear scope ('served dist or editable source tree'). Differentiates from sibling tools that read files rather than search content.

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

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

Explicitly recommends using before batch-reading files to save round trips, and explains when to use 'source' target (requires Site.sourceStored=true). No explicit alternatives named, but context is strong.

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

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

Annotations indicate idempotent, not destructive. Description adds critical behavior: effect of passing null, DNS record generation, verification requirement, submission details (endpoint, rate limit, honeypot, field constraints). No contradiction with annotations.

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

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

Every sentence serves a purpose. Well-organized: starts with purpose, then prerequisites, configuration details, submission behavior, response format. No fluff, yet comprehensive. Front-loads key information.

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

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

Given the tool's complexity (many config properties, submission rules, rate limits, verification flow), the description covers all essential aspects. Includes response format, rate limit, honeypot, and field constraints. No gaps identified.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaningful context beyond schema: explains that config:null disables, explains sender verification process, describes submission constraints (max fields, chars, rate limit, honeypot). Adds value without redundancy.

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

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

Description uses specific verb 'configure' and identifies the resource as 'built-in form-to-email relay'. It clearly distinguishes from sibling tools like get_forms_config (read) and verify_forms_sender_domain (verification step).

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

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

Explicitly mentions when to use (self-service configuration) and required role (owner/admin). Provides clear guidance on disabling (config:null) and next steps (call verify_forms_sender_domain after setting custom sender without SMTP relay). Lacks explicit 'when not to use' or alternative tools, but context is strong.

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

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

Annotations already indicate destructive, non-readOnly, non-idempotent; description adds atomicity details and deployment implications. No contradiction, and it enriches understanding of side effects.

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

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

Five concise sentences front-loaded with purpose, each adding unique value. No redundant or unclear phrasing.

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

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

Given complexity (find/replace, counts, targets), description covers key aspects: atomicity, mismatch behavior, deployment differences. Output schema exists, so return value details are not needed.

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

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

Schema covers 100% of parameters with descriptions. The description paraphrases some schema info but adds little new meaning beyond clarifying the count logic and atomicity. Baseline 3 applies.

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

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

The description clearly states the tool applies find/replace edits to a single file, specifying it's for 'tiny edits' and listing example use cases. It distinguishes from siblings like add_files or write_source_files by emphasizing surgical precision and atomicity.

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

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

The description explains when to use (tiny edits) and notes behavioral nuances (dist vs source, atomic abort on mismatch). It lacks explicit alternatives but implies larger edits warrant other tools.

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false. Description adds context: replace mode is destructive, dryRun previews diff, delete only in patch mode, errors if site does not exist, 500 MB limit. Adds value beyond annotations.

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

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

Four sentences, each adding a distinct behavioral point. Front-loaded with purpose and mode defaults. No wasted words. Ideal length for a moderately complex tool.

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 all essential behaviors: modes, delete, dryRun, error condition. Output schema exists so return values not needed. Could mention idempotency (annotation indicates idempotentHint=true), but not critical. Adequately complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds guidance beyond schema: 'Pass mode:"replace" to wipe-and-replace', 'Use delete: [paths] in patch mode', 'Use dryRun: true to preview diff'. These add practical usage context.

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

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

Clearly states 'Patch or replace files on an existing site', distinguishing between patch and replace modes. Explicitly mentions delete and dryRun capabilities. Distinct from sibling tools like add_files (creating?) and 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?

Specifies default mode (patch), warns against accidental replace with 'surfaced explicitly so it can't happen by accident'. Recommends dryRun before destructive calls. Could be more explicit about when not to use (e.g., creating new site), but context from sibling tools implies this is for existing sites only.

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

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

The description discloses external DNS checking, attachment mutation, propagation delay, and HTTPS timing. Annotations already indicate non-readonly and idempotency; the description adds valuable behavioral context without contradiction.

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

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

Three sentences, front-loaded with the core action, no fluff. Each sentence serves a purpose: action, failure handling, and outcome.

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

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

The description covers the action, common failure, and result. It assumes knowledge of step 1, but the title and sibling tools provide that context. The existence of an output schema compensates for missing return value details.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds only the context that recordId comes from add_custom_domain, but that is already implied by the schema and title.

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

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

The description clearly states the tool checks a TXT record and attaches the domain to the site's ingress. The title explicitly marks it as step 2 of 2, distinguishing it from sibling tools like add_custom_domain and remove_custom_domain.

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

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

The description explains it is the follow-up to step 1 (add_custom_domain) and gives guidance on handling DNS propagation delays. It does not explicitly list when not to use it, but the context is clear.

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

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

The description explains the full verification flow: DNS check, marking verified, changing relay behavior from custom DKIM-signed From to platform fallback. It also mentions propagation delay and idempotency. Annotations (idempotentHint, readOnlyHint false) are consistent and supplemented.

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

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

The description is four sentences, each serving a purpose: action, consequence, fallback, and usage notes. It is front-loaded with the core action and contains no fluff.

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

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

Given the simple schema (one param) and presence of an output schema, the description covers behavior, fallback, propagation, and exclusion. It could mention prerequisites like domain setup, but overall it is complete for a well-documented tool.

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

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

Schema description coverage is 100% for the single parameter siteName, so the baseline is 3. The description does not add additional parameter details, but the purpose is clear from context. No extra value beyond schema.

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

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

The description clearly states it checks DNS records (DKIM TXT + SPF include) for a site's custom sender domain used in forms. It explains the effect of marking verified and the fallback behavior. This distinguishes it from similar sibling tools like verify_custom_domain (general domain verification) and set_forms_config.

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

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

The description explicitly says it is not needed when the site uses a custom smtpRelay, giving a clear condition to bypass. It also advises re-running if DNS propagation fails. While alternatives are not named, the context is clear.

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

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

The description adds value beyond annotations by explaining the staging behavior (not live), overwrite semantics, per-file and per-call limits, and the specific error condition 'SOURCE_STORAGE_NOT_ENABLED'. Annotations already indicate idempotency and non-destructiveness, and the description complements this with concrete details without contradiction.

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

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

The description is a single paragraph of three sentences, front-loaded with the main purpose. Every sentence is necessary: primary action, recommended precursor, and failure scenario. No wasted words.

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

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

Given the existence of an output schema, the description adequately covers behavioral context, preconditions, and failure modes. However, it does not explain the 'name' and 'siteId' parameters, which might be inferred from the tool name but are not explicitly described. For a tool with moderate complexity, it is minimally sufficient.

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

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

Schema coverage is low (33%), but the description compensates by explaining the 'files' parameter structure, including the encoding options and their use cases (utf8, base64, gzip+base64). It also adds constraints (per-file cap 5 MB, per-call cap 50 MB, max 200 files) that are not in the schema. However, 'name' and 'siteId' are not addressed, leaving some ambiguity.

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

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

The description clearly states the tool stages edits to the site's editable source tree, not the live dist. It uses the specific verb 'Stage' and identifies the resource. It also distinguishes itself from siblings like 'add_files' by noting the same wire shape but different context (staging vs. adding), and mentions using 'list_source_files' first, showing awareness of the workflow.

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

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

The description provides clear guidance: use 'list_source_files' first to discover the source tree, explains that the dist remains unchanged until redeployment, and mentions the failure case when source storage is not enabled, including a resolution. It does not explicitly list exclusions but gives enough context for an agent to decide when to use this tool.

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