Hostlo

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

Annotations provide readOnlyHint:false and destructiveHint:false, but the description adds crucial behavioral detail beyond those flags: it returns DNS records that the user must create externally, and the domain only goes live after those records are in place and a certificate is issued (usually within minutes). This non-immediate effect and external dependency are not inferable from the schema or annotations, and are valuable for the agent.

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, each earning its place: first states the action with constraints, second describes the return value, third explains the follow-up and timing. It is front-loaded with the core purpose and contains no filler, fluff, or redundant restating of the tool name.

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

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

With no output schema, the description correctly explains that the return value is the DNS records to create. It also covers the operational flow (records → certificate → domain serving) and suggests check_domain for monitoring. For a tool with two simple parameters and no nested structures, this is nearly complete; it lacks error-case handling or idempotency notes, but those are not essential given the simple inputs.

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

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

Schema coverage is 100% and both parameters (site, domain) have clear descriptions. The tool description does not add parameter-specific information beyond reinforcing that the domain must be already owned, which is more a usage precondition than a parameter semantic. Per the calibration rule, baseline 3 is appropriate when the schema carries the parameter documentation.

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

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

The description states a specific action ('Connect a domain the person already owns') and resource ('one of their sites'), with a clear qualifier (Pro plan). It is distinct from siblings like remove_domain, list_domains, and check_domain, which are separate operations. An agent can immediately tell this is the add/connect tool.

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

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

The description gives a clear use condition: the domain must already be owned and the site must be Pro plan. It also explicitly points to check_domain for following up, which guides the agent on the next step. It does not enumerate all alternatives, but the mention of check_domain and the implied contrast with remove_domain provide enough orientation.

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=false and openWorldHint=true; the description adds the asynchronous invitation flow, noting the invitee receives an email and becomes an editor only upon acceptance. It also clarifies that ownership is retained, which goes beyond the annotations.

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

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

Two sentences with no filler. The core action, permission scope, ownership retention, and invitation flow are all stated in the minimum words needed to convey the information.

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

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

For a two-parameter tool with no output schema and no nested objects, the description covers the action, prerequisites, permissions, and post-invite behavior. It is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It implies that 'site' is a site the caller owns and that 'email' belongs to the invitee, but it never explicitly maps the email parameter to the invitee's address or describes expected formats, 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 uses a specific verb ('Invite') with a clear resource ('a site you own') and defines the editor's permissions. It distinguishes this tool from siblings like remove_editor or transfer_site by spelling out what the invitee can do and what remains with the owner.

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

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

The description states a clear prerequisite ('a site you own') and explains the resulting access level, which tells an agent when this tool applies. It does not explicitly name or exclude sibling tools, but the context is strong enough to infer routing.

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 show readOnlyHint=false, openWorldHint=true, and destructiveHint=false, so the description appropriately adds side-effect context: nothing is charged until the user completes payment on Stripe. It also explains what the billing page contains and the refund policy, which goes beyond the boolean hints.

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

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

The purpose is front-loaded in the first sentence, and the rest covers pricing, features, and refund policy in a dense block. It is slightly longer than strictly necessary for tool invocation, but every sentence carries relevant business context and there is 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?

For a single-optional-parameter tool with no output schema, the description is complete: it identifies the output as a link, explains both billing states, covers pricing and payment timing, and notes the refund guarantee. Nothing essential for selecting or invoking the tool is missing.

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

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

The schema already provides 100% coverage for the only parameter, 'billed', including the monthly/yearly values and the fact that it is ignored for existing subscribers. The description repeats pricing details that are also in the schema, but it does not add meaningfully new parameter-level semantics beyond the schema.

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

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

The description opens with a specific action ('Get a link') and precisely defines the two outcomes: a subscription link for new buyers and a billing-management page for existing subscribers. It unambiguously distinguishes this tool from any billing-related sibling and leaves no doubt about what invoking it returns.

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

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

The description explicitly separates the two use cases: new subscribers get a Pro subscription link, while already-paying accounts get the billing page with card, invoices, and cancellation. It also tells the agent to hand the link to the person and notes that no charge occurs until the Stripe flow is finished.

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=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context by revealing that the tool queries the certificate provider externally and may transition the domain into a serving state. This goes beyond what the annotations express and does not contradict them.

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

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

The description is a single, well-structured sentence that front-loads the core action and then adds the conditional behavior. There is no filler or 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?

For a one-parameter, idempotent tool with safety annotations, the description covers the essential behavior and the condition under which a side effect occurs. It does not document output shape or error handling, but given the tool's simplicity and the absent output schema, this is only a minor gap.

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

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

The schema already provides a clear description for the only parameter, 'domain', including the important qualifier 'exactly as it was connected.' The description adds no additional parameter-level detail, but since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's specific action: querying a certificate provider about a pending custom domain and conditionally beginning to serve it. It is distinct from sibling tools like list_domains or add_domain, so an agent can correctly identify when to invoke it.

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

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

The description conveys a clear usage context: use it when a custom domain is pending and you need to know its status, with the added behavior of serving it if ready. It does not explicitly name alternative tools or exclusions, but the situation is unambiguous enough for an agent to select it appropriately.

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

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

Annotations already mark this as write-oriented and destructive, and the description adds meaningful behavior: private-repo support, automatic republishing on push, the two-step authorization flow, and the no-builds policy. This goes well beyond the structured data without contradicting it.

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 dense, front-loaded sentences with no filler. The main action leads, followed by important caveats: private repos, the authorization handshake, and no-build publishing. Every sentence earns its place.

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

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

For a tool with this complexity, the description covers the important caveats: private repos, auth, repeated invocations, and folder behavior. The main gap is that it does not describe what the second call returns, but the schema plus annotations make the invocation otherwise 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?

The input schema has 100% parameter coverage, so the baseline is 3. The description does add a little useful context around the folder parameter ('found automatically, or given') and the no-builds behavior, but it does not meaningfully clarify site, repo, or branch 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 names a specific action and resource: publish a site from a GitHub repository and republish on every push. This clearly distinguishes connect_repo from siblings like disconnect_repo or start_upload. The additional constraint 'No builds are run' further sharpens what this tool does.

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 flow: the first call returns an authorization link, and after the person authorizes, the tool must be called again. This tells the agent exactly when and how to use the tool. It does not explicitly name alternatives or exclusion conditions, but the guidance 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that a newly created site starts empty and remains so until files are published. This is useful runtime behavior context that is not present in the schema or annotations.

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

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

Two compact sentences with no filler. The core action is front-loaded, and the second sentence adds lifecycle context while referencing exact sibling tools.

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 creation tool with one optional parameter, the description is nearly complete: it states the action, the subdomain context, and the empty initial state. The main absence is any mention of what the successful response returns (e.g., site URL or id), though that is not required by the invocation itself.

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

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

Schema description coverage is 100%, and the description itself does not add parameter details beyond what the schema already states. The main text only reinforces that the site is created on a subdomain, which is already implied by the schema's 'Desired subdomain' field, so the baseline 3 applies.

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

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

The description uses a specific verb and resource, 'Create a new site,' and adds the key qualifier 'on a free subdomain.' It also distinguishes creation from content-publishing tools by noting that the site stays empty until files are published with write_files or start_upload.

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

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

It communicates the intended workflow by naming write_files and start_upload as the follow-up actions that populate the site. It does not explicitly state when not to use create_site or compare it to list_sites/delete_site, but the sequential 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 annotation already marks this destructive, and the description adds the distinct behavioral detail that the deletion is followed by publishing a result. It does not contradict the annotations, and it makes the side effect explicit beyond the schema.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes meaning.

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

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

For a destructive delete operation with two required string/array parameters and no nested objects, the description is concise but sufficient: it names what is deleted, where, and the result. The optional 'message' parameter is the only underspecified aspect.

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 0% schema description coverage, the description must carry parameter meaning. It clarifies that 'site' is the target site and 'paths' are the file paths to delete, but it says nothing about the optional 'message' parameter, leaving some semantics to inference.

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

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

The description names a specific verb ('Delete'), a precise resource ('files from a site'), and the follow-on effect ('publish the result'). This clearly distinguishes it from siblings like delete_site, patch_file, and write_files.

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

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

The description clearly implies the use case: deleting one or more files from a site and redeploying. It does not explicitly enumerate alternatives or exclusions, so it stops short of 5, but the context is not vague.

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 destructiveHint=true and readOnlyHint=false. The description adds the permanent nature, the removal of deploy history, and the side effect that the name becomes available, enriching behavioral context without contradicting annotations.

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

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

Two concise sentences front-load the core action and immediately follow with the key side effect. No wasted words; every clause carries meaning.

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

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

For a tool with two simple required parameters and no output schema, the description covers the operation's scope (site, files, deploy history) and a notable consequence (name release). No critical information is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters (site and confirm) are already well-documented. The description adds no further parameter-level meaning, so it meets the baseline for high schema coverage.

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

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

The description clearly states the action (permanently delete) and the resource (a site), explicitly mentioning its files and deploy history. This distinguishes it from siblings like delete_files, which operate on individual files, making the purpose unambiguous.

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

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

The description implies the tool is for whole-site deletion, which differentiates it from delete_files. However, it does not explicitly name alternatives or state when not to use it. The context is clear but not fully explicit.

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

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

While annotations already indicate destructiveness, the description adds valuable nuance by specifying that the site itself is not deleted—only the repository connection is removed. This prevents the agent from overestimating the impact and aligns with the destructiveHint 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?

Two sentences deliver the core action, the outcome, and the confirmation requirement with zero filler. The most important information is front-loaded.

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

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

For a simple two-parameter destructive action with no output schema, the description fully covers what the agent needs to know: the effect, the confirmation step, and the post-state of the site. Nothing essential is missing.

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

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

Schema coverage is 100%, so both parameters are already documented. The description only restates the confirm requirement, adding no new semantic depth beyond the schema. Baseline 3 is appropriate given the high coverage.

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

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

The description states a specific action ('Stop publishing a site from its GitHub repository') and clearly distinguishes it from siblings like delete_site or connect_repo. It also clarifies the non-destructive nature for the site itself, making the intent unmistakable.

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

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

It provides clear context about the effect ('site stays online with current files, can be edited here again'), which implies the appropriate scenario. However, it does not explicitly compare with alternatives or state when not to use it, leaving some inference to the agent.

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

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

readOnlyHint=true already establishes the safety profile, so the description's job is to add context beyond that — which it does by disclosing sort order (newest first) and that messages render with the form's own field labels. It omits pagination/auth details, but those are secondary here.

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

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

Two sentences, zero filler, and the core capability plus the usage trigger are front-loaded. Every clause earns its place.

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

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

With no output schema, the description carries the return-shape burden and does so adequately by specifying ordering and label rendering. It leaves the site parameter's identifier format and result volume/pagination unstated, which is a minor gap for a read tool.

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

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

Schema coverage is 67%: form and limit already carry descriptions (including default 20 / max 200 and omit-for-all semantics), while site is undocumented in both places. The description's 'all the site's forms' only echoes the schema's form parameter, adding no new syntax or format detail, so the baseline 3 holds.

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

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

States a specific verb (read) and resource (messages sent through a site's contact forms) plus ordering and presentation. The 'This is the inbox' framing cleanly separates it from siblings like list_forms (which enumerates forms, not submissions) and set_form.

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

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

Gives an explicit when-to-use trigger: 'use it when the person asks whether anyone has written in.' It implicitly contrasts with list_forms/set_form via the 'inbox' framing, but does not name an alternative tool or any when-not condition outright.

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

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

Annotations only say readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds material behavior: it copies assets, rewrites links, carries on in background for large sites (import_status reports), and cannot carry over forms/logins/search/checkouts. This is exactly the context an agent needs beyond the structured fields.

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

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

Four sentences, each earning its place: core action, legal constraint, async behavior, and limitation caveat. The purpose is front-loaded and there is no redundant prose.

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

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

For a complex tool with no output schema and sparse annotations, the description explains the asynchronous behavior, the limitation on dynamic features, and the need to report what couldn't carry over. It omits the file-replacement/rollback behavior (which the schema's site parameter covers), so the description is slightly incomplete but still sufficient for 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 covers all three parameters at 100%, so the baseline is 3. The description's reference to 'Wayback Machine's saved copy' restates from_archive without adding new semantics; it does not clarify parameter format or edge cases beyond what the schema already provides. No credit is given for schema-covered information.

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

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

The description opens with a specific verb ('Copy') and resource ('an existing website ... into a Hostlo site'), enumerates the imported assets (pages, styles, scripts, images, fonts) and notes link rewriting. It distinguishes this tool from siblings by naming the source types (WordPress, static, Wayback) and implying the contrast with import_status, which reports on background imports.

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

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

Gives clear when-to-use context: only import sites the person owns or has right to copy, and states the small-vs-large behavior that routes to import_status. It does not explicitly name alternatives like connect_repo vs import_site, but the guidance is sufficient for selecting this tool over reporting 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 provide readOnlyHint=true, indicating a safe read operation. The description adds context about what the tool returns (progress or full report) and the nature of the output (copied, left out, why). It does not contradict annotations and adds useful behavioral context.

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

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

The description is concise and front-loaded with the purpose. It is a single sentence that is informative without excessive wordiness.

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 (one parameter, no output schema), the description is quite complete. It explains what the tool reports on and its relationship to import_site. Missing explicit details about output format, but with readOnlyHint and simple schema, it's adequate.

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

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

Schema description coverage is 100%, so the schema already documents the 'site' parameter. The description implies the site is the one where the import was started, but doesn't add much beyond the schema. Baseline of 3 is adjusted to 4 because it clarifies context but not required.

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

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

The description clearly states that the tool reports on the status of an import started by import_site, including both progress and final report content (what was copied, left out, why). It distinguishes itself from import_site and other status tools like repo_status.

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 implies usage after an import started with import_site, but does not explicitly state when not to use it or mention alternatives. However, the context is clear enough for an agent to infer the right timing.

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 read-only safety profile is established. The description adds useful behavioral context beyond that: results are newest-first and the live deploy is marked. This helps an agent interpret output without contradicting the annotations.

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

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

The description is a single, front-loaded sentence with no filler, repetition, or unnecessary explanation. Every phrase earns its place by conveying ordering and live-marking behavior.

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

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

For a simple two-parameter, read-only listing tool, the description covers the core operation, ordering, and a distinguishing output trait; the limit default is covered in the schema. It lacks explicit usage exclusions and an output schema, but an agent has enough information to invoke the tool correctly.

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

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

The schema documents the limit parameter (default 20, max 100), but the required site parameter has no description. The description's phrase 'a site's recent deploys' gives minimal semantic context for site, but does not clarify the format or allowed values. It adds marginal value but does not fully compensate for the missing 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 states a specific action ('Show'), a resource ('a site's recent deploys'), and adds ordering ('newest first') and a distinctive output trait ('marking the live one'). This clearly distinguishes it from sibling list tools like list_sites, list_files, and list_domains, and from rollback, which mutates deploys.

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

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

The description makes the tool's purpose obvious, so when to use it is implied: whenever read-only deploy history for a site is needed. However, it does not explicitly state when not to use it or name alternatives such as rollback for changing the live deploy, so the guidance is not fully explicit.

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

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

Annotations already declare readOnlyHint=true, so the description only needs to add context beyond that. It adds that the output includes status and missing items, which is useful, but it does not disclose side effects, permissions, or rate limits. This is consistent with the annotation, so no 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, front-loaded sentence that efficiently communicates the action and scope. There is no unnecessary wording, making it highly concise and well-structured.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete: it states what is listed, the scope, and what detail is returned (status and missing). An agent has all the information needed to call it correctly, and the readOnly annotation covers the safety profile.

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 single parameter 'site' is fully described in the input schema (coverage 100%). The tool description does not add any parameter semantics beyond what the schema already provides. Baseline 3 is appropriate since the schema covers everything.

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

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

The description states a specific verb ('List'), resource ('custom domains'), scope ('on this account'), and adds detail ('their status and what is still missing'). It clearly distinguishes from sibling tools like add_domain, remove_domain, and check_domain, which operate on individual domains rather than listing all.

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 that you use this tool to see all custom domains, but it does not explicitly mention when to prefer it over alternatives like check_domain or list_sites. There is no guidance on when not to use it, but the purpose is clear enough that an agent can infer the 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 mark the tool as read-only (readOnlyHint=true), so the description's 'List' is consistent. The description adds the behavioral nuance that it targets the 'live deploy' specifically, which is useful context beyond the annotation. However, it does not disclose other behaviors such as pagination, recursive listing, or response format, which are not covered by 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, concise sentence with no filler. The key action and resource are front-loaded, making it efficient for an agent to parse quickly.

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

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

For a tool with only two parameters and no output schema, the description is adequate but sparse. It covers the core function but omits details like whether the list is recursive, includes directories, or has limits. Given the tool's simplicity, this is acceptable, but it could provide more context about the response structure.

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

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

Schema coverage is 50% (only 'prefix' has a description). The tool description indirectly clarifies the 'site' parameter by stating 'a site's live deploy', but it does not explain 'prefix' beyond what the schema already provides. This partial compensation is modest, so the description adds some meaning but not enough to fully bridge the gap.

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

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

The description clearly states the action (list), the resource (files of a site's live deploy), and adds the detail 'with their sizes'. This is specific and distinct from sibling tools like list_deploys or read_file. It is not a tautology and immediately conveys what the tool does.

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 inspecting a live deploy's files but does not explicitly mention when to use it versus alternatives like read_file or delete_files. There are no stated exclusions or comparisons to siblings, leaving the agent to infer the context from the purpose alone.

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 safety profile is covered. The description adds useful context about what each entry contains (fields, where submissions go, message counts), but says nothing about result volume, caching, or auth requirements for a tool that can span all sites.

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

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

One dense sentence, front-loaded with the verb and resource, with the scope qualifier and return-value preview packed in without filler.

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

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

For a no-required-param, read-only listing tool with no output schema, the description covers scope and the shape of returned data, and annotations cover safety. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100% and the single 'site' parameter is already fully documented, including the omit-for-all behavior. The description only restates that scoping, so baseline 3 applies.

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

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

States a specific verb+resource (list contact forms) with scope (a site or all sites) and previews the returned content (fields, submission destination, message counts). This implicitly separates it from form_messages, set_form, and remove_form, though no sibling is named explicitly.

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

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

The parenthetical '(or all your sites)' implies the omittable-site use case, and the schema confirms it ('Leave out for all of them'). But there is no explicit when-to-use vs alternatives guidance nor any exclusion pointing the agent to form_messages for actual submissions.

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 annotation readOnlyHint=true already signals a safe read operation, and the description adds value by disclosing exactly what data is returned: public URLs, file counts, and sizes. There is no contradiction, and the behavior is sufficiently transparent for such a simple read-only tool.

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

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

The description is a single sentence with no filler, and the core action ('List your sites') is front-loaded before the output details. Every word contributes meaningful 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 zero parameters, a read-only annotation, and no output schema, the description provides enough context by naming the returned attributes. Nothing critical is missing for an agent to select and invoke this 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?

There are no parameters, so the schema already fully covers this aspect. The baseline of 4 applies because no parameter documentation burden exists and the description does not need to compensate for missing schema coverage.

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

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

The description states a specific action ('List') and resource ('your sites'), and specifies the output dimensions: public URLs, file counts and sizes. This clearly differentiates it from sibling tools like list_domains, list_files, and list_deploys.

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

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

The wording implies this is the tool for listing sites, but it does not explicitly say when to prefer it over alternatives such as site_stats or list_domains, nor does it mention any exclusions or prerequisites. Usage context is implied rather than stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds the publish side effect and the uniqueness constraint on old_text. This goes beyond the annotations by revealing that the tool triggers deployment and requires exact matches. However, it does not detail failure behavior or consequences of partial edits, leaving some transparency gaps.

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 concise sentence (15 words) that front-loads the core action and constraint. Every word adds value, and there is no redundancy or filler.

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

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

The tool has 4 parameters and a nested edits array, but the description omits details on parameter semantics and the application order of edits. While the schema mentions 'Edits applied in order', this is not reinforced in the description. With no output schema and low schema coverage, the description should provide more context about expected inputs and side effects, but it only covers the uniqueness and publish aspects.

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

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

Schema coverage is only 25%, with most parameters (site, path, message) lacking descriptions. The tool description does not compensate by explaining these parameters or the edit structure beyond the uniqueness rule. It fails to clarify what 'site' and 'path' refer to or how 'message' is used, leaving significant semantic gaps.

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

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

The description clearly states the tool edits a text file via exact search and replace, then publishes. This specific verb-resource-method combination distinguishes it from sibling tools like write_files (full overwrite) and delete_files (removal). The publish step is also an explicit side effect that sets it apart.

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 targeted edits rather than full rewrites, but does not explicitly mention alternatives or exclusions. The constraint 'Each old_text must match exactly once' gives a condition, but no direct guidance on when to choose this over write_files or other siblings.

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

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

Annotations already cover readOnlyHint=false and idempotentHint=true, and the description adds meaningful context beyond that: it specifies exactly what the preference controls (Hostlo emails/pages) and explicitly excludes the assistant's reply language. This surfaces an important side-effect distinction that the annotations do not convey.

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

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

Three sentences with no filler: purpose/scoping first, then allowed values, then a key usage clarification. Each sentence earns its place and the structure front-loads what the tool does before diving into nuances.

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

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

For a simple one-param tool with no output schema, the description covers purpose, scoping, and a behavioral distinction that could affect the agent's response. It does not explicitly state what the tool returns (e.g., current preferences after read/change), but given the tool's simplicity and the schema's completeness, this is a minor gap rather than a critical omission.

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

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

Schema description coverage is 100%, so the schema already documents the 'language' parameter, allowed values (en/km), and the null/omit behavior. The description repeats those values and adds no new parameter-level syntax or edge cases; its extra language about replies is behavioral rather than parameter semantics. Baseline of 3 is appropriate.

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

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

The description states a specific verb-resource pair: 'Read or change the person's Hostlo preferences', then immediately narrows the current scope to language ('English (en) or Khmer (km)'). This fully distinguishes the tool from siblings, none of which manage preferences, and the annotation title reinforces the language focus.

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

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

The description gives an explicit trigger: 'Use it when they ask to read Hostlo in Khmer or English.' It also proactively clarifies a potential misapplication by noting 'Your own replies stay in whatever language you are speaking with them,' which prevents the agent from using this tool to change its own output language.

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 agent knows this is a safe read operation. The description adds the nuance 'live deploy,' indicating it reads from the deployed version, which is useful context but not extensive. 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 a single, front-loaded sentence with no fluff. Every word adds meaning, making it highly concise and easy to parse.

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

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

The tool is simple (2 params, read-only, no output schema). The description states the action and the resource, and the readOnlyHint covers safety. However, it does not explicitly mention what is returned (file content) or any error behavior, though this is largely implied. It is adequate but not fully detailed.

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

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

Schema coverage is only 50% (only 'path' has a description). The description does not elaborate on the 'site' parameter or clarify its format or purpose. It only implies 'site' via the phrase 'a site's live deploy,' which is not explicit parameter documentation. The description fails to compensate for the missing schema coverage.

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

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

The description clearly states a specific verb ('read') and resource ('a text file from a site's live deploy'). It distinguishes from siblings like list_files (which lists) and write_files/patch_file (which modify). No ambiguity about what the tool does.

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

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

No explicit guidance on when to use this tool vs alternatives. The description does not mention that this is for retrieving file contents as opposed to listing or modifying files, nor does it state any exclusions or prerequisites. The context is only implied by the verb.

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

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

Annotations already mark this as destructive (destructiveHint=true, readOnlyHint=false). The description adds meaningful behavior beyond that: the site stays online, and the user must pass the domain again in a confirm field. This discloses the confirmation mechanism and mitigates the destructive implication, which is genuinely useful for safe invocation.

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

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

Two short sentences deliver the core action, a key consequence, and the confirmation requirement with zero fluff. The action verb is front-loaded, and every clause earns its place. This is an appropriately sized definition for a simple 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?

For a two-parameter tool with annotations covering the safety profile and a fully described schema, the description is largely complete: it states the effect and the confirmation step. It does not describe return values or error conditions, but with no output schema and a straightforward operation, that is not a critical gap. Minor missing context like prerequisites (domain must be currently connected) prevents a 5.

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

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

Schema description coverage is 100%, so the schema already fully documents the 'domain' and 'confirm' parameters. The description's 'Pass the domain again in confirm' essentially restates the schema's 'Repeat the domain to confirm', adding no new semantic value. This matches the baseline of 3 for high schema coverage.

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

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

The description opens with a specific verb and resource, 'Disconnect a custom domain', and clarifies the scope by stating the site remains online at its Hostlo address. This clearly distinguishes it from siblings like delete_site, add_domain, or list_domains without needing to inspect schemas. The action and its boundary are unambiguous.

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

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

The description implies the use case: call this when you want to detach a custom domain from a site. It adds valuable context—the site is not taken offline—which helps an agent understand the practical effect. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false. The description adds useful behavioral nuance by clarifying the action can target invitations and handover offers rather than only active memberships, and that self-removal is allowed.

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 that front-loads the core action and then adds the two important edge cases. Every clause earns its place 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?

For a simple two-parameter destructive action with no output schema, the description fully covers what the tool does, when it applies, and the ownership/self-removal nuances. An agent has enough context to select and invoke it correctly.

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

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

There is 0% schema description coverage, so the description must compensate for the bare site and email parameters. It does explain that email is the editor/invitee/handover recipient address and that site must be owned, but it does not specify formats or further param meaning. This is helpful but not fully compensating.

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

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

The description states a specific action ('Remove an editor') and resource, and extends purpose to withdrawing invitations/handover offers and self-removal. It is clearly distinguishable from the obvious sibling add_editor and from site_members.

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

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

The description gives clear usage scenarios: removing an editor from a site you own, withdrawing an invitation/handover offer, and editors removing themselves. It does not explicitly name sibling alternatives or state when not to use the tool, so it stops short of a 5.

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

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

Annotations only declare destructiveHint=true; the description goes well beyond that by disclosing that stored messages are deleted along with the form, that the on-page HTML form stops working, and that the page markup must be cleaned up manually. That is exactly the additional behavioral context an agent needs before an irreversible call.

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

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

Three short declarative sentences, no filler, with the primary action front-loaded and the destructive side effects following immediately. Every sentence carries information.

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

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

For a two-parameter destructive tool with annotations covering the safety profile and no output schema required, the description supplies the critical missing context: message loss and the manual page-cleanup step. Nothing essential for calling it correctly is absent.

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

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

Schema description coverage is 50% – only 'name' is documented, while 'site' has no schema description. The description implicitly conveys both inputs (a form name acted on within a site) but adds no format, syntax, or lookup guidance, so it neither compensates for the gap nor falls below the baseline.

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

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

States a precise verb and resource ("Remove a contact form from a site") and the scope of what is affected. It is easily distinguished from set_form/list_forms/form_messages by resource and verb, but no sibling is named or explicitly contrasted, so it falls just short of the top band.

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

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

Usage is implied by the destructive framing (use it to delete a form and its messages), but there is no explicit when-to-use vs. when-not guidance and no mention of alternatives such as set_form or form_messages. The agent must infer the calling 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?

readOnlyHint=true already establishes this is a safe read, and the description adds the output surface: repository, branch, folder, live commit, and failure reason for the last push. For a simple status query this fully discloses the observable behavior beyond the annotation.

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

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

One compact sentence with the key output items listed after a colon; no filler, no repeated title, and the main purpose is front-loaded.

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

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

With no required parameters, a read-only annotation, and no output schema, the description still tells the agent exactly what information will be returned. Nothing an agent needs to decide whether to call this tool is missing.

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

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

Schema description coverage is 100% and the single optional parameter is already documented as 'Only this site. Leave out for all of them.' The description does not need to add further parameter detail, so it hits the baseline.

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

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

The description states a specific verb and resource ('Show which sites are published from GitHub repositories') and enumerates the exact status fields returned. This makes it clearly distinct from siblings like list_sites or list_deploys, which concern site metadata and deployment history rather than repo-publishing state.

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

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

It gives clear context: use this when you need the repo-to-site publishing state, optionally filtered to one site. It does not explicitly name when-not-to-use alternatives, so it stops short of a 5, but there is no misleading guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's job is lighter. The description adds valuable context: 'Nothing is deleted; you can roll forward the same way,' which clarifies that the operation is reversible and non-destructive in terms of data loss. This goes beyond the annotations and helps an agent understand the safety profile.

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 core action is front-loaded, and the reassurance about non-deletion is concise. Every sentence earns its place.

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

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

For a two-parameter tool with no output schema, the description is nearly complete. It explains the action, the reversibility, and the deploy_id source is in the schema. The only minor gap is that 'site' is not described, but the parameter name is self-explanatory in context. The destructiveHint annotation covers the risk profile.

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%: deploy_id has a description ('A deploy_id from list_deploys'), but site has none. The description does not add parameter-level meaning beyond the schema. Baseline 3 is appropriate because the schema covers half the parameters, and the description's mention of 'earlier deploy' implies deploy_id refers to a historical deploy, but it doesn't explicitly explain site.

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

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

The description states a specific verb and resource: 'Make an earlier deploy live again.' This clearly distinguishes it from sibling tools like list_deploys or delete_files. The title 'Roll back to a deploy' reinforces the purpose without being a tautology.

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: when you want to revert to an earlier deploy. It also notes that nothing is deleted and you can roll forward the same way, which gives context for safe usage. However, it does not explicitly name alternatives or state when not to use it, though the sibling list makes the alternative (list_deploys) obvious.

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

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

Goes well beyond annotations (which only cover readOnly/idempotent/destructive). It discloses where submissions go (email to owner, chat inbox via form_messages, Pro-plan webhook to Slack/Discord/Zapier/https), that the form posts to the site's own address with no third-party service, and that sensitive fields are rejected. This is unusually rich behavioral context.

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

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

Front-loaded with the core action, then delivery behavior, then the safety exclusion, then naming. Dense but every sentence carries information. Slightly long, but not padded.

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

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

With no output schema, the description compensates by explaining what is returned (an HTML form to drop in with write_files) and the full downstream lifecycle of submissions. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning: it explains the field concept ('describe the fields the visitor should fill'), the default form name, and the purpose of webhook_url (Pro-plan secondary delivery). The email_to 'usual choice' guidance is also clarified prose beyond the schema.

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

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

States a specific verb+resource: 'Add or update a contact form on a site.' An agent can immediately distinguish it from siblings like list_forms, remove_form, and form_messages, and the return artifact (an HTML form for write_files) is named.

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

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

Gives a concrete naming convention ('use the name contact unless the site needs more than one form') and an explicit exclusion (not for passwords or card numbers, which are refused). It implies but does not spell out when to prefer this over list_forms/remove_form, though those are self-evidently different operations.

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

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

Annotations already declare non-readOnly, idempotent, non-destructive, open-world. The description adds real behavioral context beyond that: other domains redirect visitors and search engines, only one copy is indexed, and the target domain must already be live. It doesn't describe reversibility or the response, keeping it from a 5.

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

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

Three tight sentences with no filler, and the core action is front-loaded ahead of the redirect consequence and the usage condition. Every sentence earns its place, though it is slightly longer than strictly necessary.

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 one-parameter mutation with no output schema, the description covers the effect, the redirect/indexing consequence, the liveness prerequisite, and the selection context. Only return/confirmation behavior is left unaddressed, which is minor here.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema ('exactly as it was connected'). The description adds the liveness prerequisite, which is meaningful, but otherwise the schema carries the semantics. Baseline 3 is appropriate.

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

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

States a specific verb and resource: making one connected domain a site's main address. It also distinguishes from siblings by referencing check_domain for the liveness prerequisite, so an agent can tell this apart from add_domain/list_domains without opening a schema.

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

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

Explicitly gives the when-to-use condition ('a site has more than one domain and the person says which should be the main one') and names the check_domain prerequisite. It lacks an explicit when-not-to-use, but the usage 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 readOnlyHint annotation already marks this as a safe read, and the description adds meaningful behavioral context by explicitly including pending invitations and handover offers, showing that in-flight requests are part of the response. 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 a single, tightly worded sentence with no filler. It front-loads the core purpose and covers all the key output categories without 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?

For a one-parameter read-only tool, the description provides sufficient context about what information will be returned. It does not describe the return structure or authentication requirements, but those are less critical given the simple input and readOnlyHint annotation.

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, site, has no schema description and the description only refers to 'a site' generically. This clarifies that the parameter identifies the queried site but does not specify the expected value format or identifier type. Partial compensation for the low schema coverage.

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

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

The description clearly states what the tool returns: the owner, editors, and pending invitations/handover offers for a site. It differentiates itself from sibling mutation tools like add_editor, remove_editor, and transfer_site by focusing on current membership state and pending requests.

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 the tool — when you need membership or pending-request information — but it never explicitly names alternatives or states when not to use it. The reader must infer the appropriate context from the described output.

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. The description adds valuable behavioral context beyond that: it explains that counting works without cookies or tracking scripts and that recent views may take about a minute to appear. This helps set expectations about privacy and data freshness.

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

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

Two tightly written sentences, each earning its place. The first states the core outputs, and the second adds important behavioral caveats. No filler or repetition.

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

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

Given the two parameters and no output schema, the description covers the main outputs, the time granularity, privacy behavior, and data freshness. It does not describe the exact response shape, but the listed metrics largely fill that gap for an agent deciding whether to call the tool.

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

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

The schema documents the 'days' parameter fully, and the description clarifies that the resource is a 'site', giving some meaning to the otherwise undocumented 'site' parameter. However, with only 50% schema coverage, the description could do more to explain acceptable site identifiers or how the two parameters interact.

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

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

The description clearly identifies the tool's purpose with a specific resource ('site') and a concrete set of outputs: page views, unique visitors, top pages, referring sites, and serving location. It distinguishes this tool from all listed siblings, none of which provide visitor 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 establishes clear usage context: use this when you need visitor statistics for a site. It does not explicitly name alternatives or exclusions, but no sibling tool overlaps with this functionality, so the alternative guidance is not strictly necessary.

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

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

Annotations already flag this as destructive and not read-only; the description adds meaningful behavior beyond that: the returned token is one-time, the shell command must be run, only changed files transfer, and the token expires after 60 minutes. No contradiction with the annotations.

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

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

Two sentences, with the main action and example front-loaded and the follow-up behaviors packed into the second sentence. Every sentence contributes information and there is no filler.

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

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

The core invocation flow is complete: this tool prepares an upload, returns a runnable shell command, and the token has a clear expiry. With no output schema, the return behavior is described directly; the main gap is the unexplained `site`/`message` parameters, though the destructive mode is already covered by annotations and schema enums.

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

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

Schema description coverage is only 33%, and the description does not compensate: it never explains the required `site` parameter or the optional `message` parameter. The 'local folder' phrasing relates to the workflow, not to any schema property, so the description adds almost no parameter-level meaning.

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

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

The description states a specific action ('Prepare an upload of a local folder') and names the concrete output (one-time token and shell command), so an agent can tell it is a staging step rather than a direct file write. It does not explicitly contrast itself with sibling tools such as write_files or delete_files, so it misses the top score.

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 build-output example ('dist/') and 'only changed files are transferred' imply a deployment use case, but no when-to-use or when-not-to-use guidance is given versus alternatives like write_files or delete_files. The usage context is implied rather than explicit.

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

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

The description discloses key behaviors beyond annotations: the email link, acceptance required, full asset transfer (pages, history, statistics, custom domains), plan impact, and that nothing changes until acceptance. It also clarifies the default of keep_me_as_editor (lose access). This richly augments the destructiveHint annotation 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 two sentences and front-loads the core purpose. It includes necessary behavioral details but is slightly verbose with the example clause. Still, each sentence earns its place, and the structure is clear.

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

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

For a destructive, async transfer tool, the description covers all essential aspects: trigger (email link), condition (acceptance), what transfers, plan implications, and default editor access. No output schema exists, so no return-value explanation needed. It is complete for an agent to call correctly.

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

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

Schema coverage is 67% (site is undocumented). The description doesn't elaborate on the 'site' parameter beyond its role in the transfer, but it does add context to keep_me_as_editor (agency scenario, default). While it doesn't fully compensate for the missing site description, it provides process-level semantics that partially inform usage. Baseline 3 is appropriate given moderate schema coverage and minimal direct parameter detail.

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

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

The description clearly states 'Hand a site over to someone else' with a specific resource (site) and purpose (client handover). It distinguishes from siblings like add_editor by focusing on ownership transfer, and the context of email acceptance makes it unambiguous.

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

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

The description provides clear usage context: when you want to give a site to a client, and it mentions asking about keep_me_as_editor as an agency practice. It doesn't explicitly name alternatives or say when not to use it, but the guidance is practical and sufficient for an agent to infer appropriate use.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds context about the content returned (plan limits, usage, edge locations) but does not disclose any additional behavioral traits such as authentication needs or rate limits.

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

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

A single, front-loaded sentence with zero filler. Every word earns its place, and the description is appropriately sized for the tool's simplicity.

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 no output schema and no parameters, the description carries the full burden of explaining what the tool returns. It lists the key categories (account, plan limits, usage, edge locations) and is complete for an agent to invoke and interpret the result.

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

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

The input schema is empty (0 parameters), so there is nothing to explain. Baseline for 0 params is 4, and the description correctly avoids inventing parameter semantics.

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

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

The description uses a specific verb ('Show') and names the exact resources: the signed-in account, plan limits, usage, and edge locations. This clearly distinguishes it from siblings like list_sites or site_stats, which focus on different data.

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

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

Usage is implied by the description: an agent would use this when needing identity or account-level limits/usage. However, it does not explicitly contrast with overlapping siblings like billing or site_stats, leaving some inference to the agent.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds key behavioral details: 'goes live immediately' and the constraint that 'binary files must really be what their extension says.' It also mentions encoding requirements (utf8 vs base64). These enrich the behavioral contract 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?

The description is two sentences long and front-loads the core action. The second sentence is dense but efficient, covering encoding, alternative tool, and allowed types without unnecessary fluff. It earns its length.

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 file-publishing tool with no output schema, the description is thorough: it covers creation, replacement, deletion, encoding, size guidance, allowed file types, and binary integrity. It gives an agent everything needed to invoke correctly and know what to expect. No critical 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?

The description directly explains the encoding parameter ('Use utf8 for text and base64 for small binary files') and adds a validation constraint on binary files. While the schema already covers most parameters with descriptions (75% coverage), the description provides meaningful additional guidance on encoding and file-type integrity.

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 and resource: 'Create, replace and delete files in one deploy that goes live immediately.' It distinguishes itself from siblings by mentioning the alternative start_upload for large files and specifying allowed file types. The purpose 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?

The description gives explicit guidance for when to use start_upload instead ('For large or many files use start_upload instead'), which helps the agent route correctly. It also implies this tool is for small to medium file sets. However, it doesn't clarify the distinction between this tool's delete capability and the sibling delete_files tool, leaving some ambiguity.

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