RunLite

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

The description adds real value beyond the annotations: it discloses that the call mutates state ('advances it as far as it currently can') and describes the three possible outcomes (still validating, certificate issued, active). But 'safe to call repeatedly' largely restates idempotentHint=true, so the behavioral content is partially duplicative; it also omits auth/prerequisite requirements for the site.

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

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

Two sentences, front-loaded with the action, followed by the enumerated return states. Every clause carries information and nothing is padded.

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

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

For a one-param, no-output-schema tool whose annotations already cover safety and idempotency, the description is nearly sufficient: it explains the lifecycle states an agent will see. The remaining gap is the unexplained siteId and the relationship to set_custom_domain.

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% for the single required siteId parameter, and the description never mentions what siteId refers to or where it comes from. With the schema providing no documentation, the description was the only place to compensate, and it doesn't.

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 (re-checks and advances) and resource (a pending custom domain request), and explicitly frames it as re-checking a pending request, which separates it from the setup/removal siblings in spirit. However, it never names set_custom_domain or remove_custom_domain as the alternatives, so the differentiation is implicit rather than explicit.

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?

'Re-checks a pending custom domain request' and 'Safe to call repeatedly' give a clear condition for use (a request that is already pending) plus polling guidance. It stops short of explicitly saying to use set_custom_domain to create the request first or remove_custom_domain to tear it down, so it lacks named alternatives.

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

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

Goes well beyond the annotations: explains that a replacement occurs per channel (consistent with idempotentHint), that the previous destination is overwritten (consistent with destructiveHint), and that new destinations are inert until confirmed via a link or START message. The pendingConfirmation and optInLink return behavior is exactly the kind of context annotations cannot convey.

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

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

Four tight sentences, front-loaded with the core purpose, then replacement semantics, then the two confirmation flows. Dense and mostly free of waste, though the confirmation detail is packed into a single run-on paragraph.

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?

No output schema exists, yet the description discloses the key returned fields (optInLink, pendingConfirmation) and the gating condition for activation. It is nearly complete for a mutation tool; the only omission is any statement about formId or what happens on invalid/paid-plan-restricted requests.

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%; the description reinforces the 'to' and 'channel' semantics (email vs. Indian mobile, paid plan) but adds little beyond what the schema descriptions already state. formId receives no explanation in either place, which is the one real 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?

Names a specific verb and resource — where a form's submissions are delivered — and enumerates the two channels (email, WhatsApp). No sibling tool touches notification routing, so the agent can distinguish it from update_form or get_form 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?

Sets clear operating context: one destination per channel, repeat calls replace the existing one, and WhatsApp is limited to Indian (+91) numbers on paid plans. It doesn't name alternatives or explicitly say when not to use it, but for a tool with no true siblings the context is sufficient.

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

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

Annotations already declare that this is a non-read-only, non-idempotent, non-destructive operation in a closed world. The description adds useful behavioral context beyond that: it returns ready-to-use HTML with the action URL, honeypot field, and hidden spam-check inputs, and submissions begin only once that HTML is live.

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 are front-loaded with the creation action and then the returned HTML, with no wasted wording. The activation condition is included compactly in the second sentence.

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

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

For a creation tool with annotations covering safety, this is mostly complete: it explains the key return behavior even though no output schema exists. It does not cover permissions, validation behavior, or how the tool relates to update_form, but those are secondary given the schema and annotations.

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

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

Schema description coverage is 50%, and the description explicitly references only siteId as the existing site. The schema covers name, fields, nested field properties, and successMessage, but the description adds little parameter-level meaning for those inputs.

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

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

The description states a specific verb and resource: it creates a form endpoint for an existing site identified by siteId. It also clarifies the notable output, ready-to-use HTML, but it does not explicitly distinguish this from the sibling update_form tool.

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

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

The description implies when to use it: for an existing site, when you need form HTML with spam protection that can be embedded to start receiving submissions. It does not explicitly say when to use update_form or get_form instead, so the usage guidance is contextual 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?

Annotations only declare destructive/non-idempotent; the description adds far more: atomicity ('every file goes live or none does'), whole-site replacement semantics (unsent live files are removed), hard limits of 200 files and 4 MB, a required root index.html, quota_exceeded on site-limit overflow, content-type refusals for sensitive fields without a paid custom domain, and the draft fallback with published=false. All of this is consistent with destructiveHint=true and gives the agent the failure surface it needs.

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

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

Front-loads the core action and the create/update fork in the first two sentences, then layers constraints. It is dense and long, but nearly every clause carries a real operational constraint; a slightly tighter grouping of the quota/policy rules would improve scanability.

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, non-idempotent mutation with no output schema, the description covers limits, failure modes, and policy refusals, plus hints at the response shape (published=false, quota_exceeded). It does not describe the overall return structure or what an update does to a site's deployment history beyond the message field, leaving 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?

With 80% schema coverage the baseline is 3, and the description earns above that by tying semantics together: name is required only when creating, subdomain is derived from name unless given, and siteId omission flips the mode. It adds little on files, message, or encoding, which the schema already covers.

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 ('Uploads files and makes them live') with concrete scope ('{subdomain}.runlitehost.com address'), and immediately splits the create-vs-update behavior on siteId. An agent can distinguish this from siblings like upload_files, start_upload, or update_site without opening any schema.

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

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

Explicitly says 'Without a siteId it creates a new site ... with one it updates that site', giving clear when-to-use branching. It does not name sibling alternatives (e.g. upload_files or publish_upload) or say when not to use full deploy versus a partial update, so it stops short of the top band.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true and openWorldHint=false, so safety is covered; the closing 'Changes nothing.' restates that. The description earns credit beyond the annotations by disclosing the response surface (plan, siteIds, limits, per-site deploy/submission/domain/bandwidth usage, upgrade path) and by implying an authenticated-connection requirement, which matters because there is no output 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?

One long but front-loaded sentence: identity and scope come first, the contents in a parenthetical list, the safety note last. Every clause carries information, though the dense list could be broken for faster scanning and 'Changes nothing.' duplicates the annotations.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly, covering plan tier, site inventory, limits, and usage metrics. The only real gap is edge behavior (what is returned if the connection is unauthenticated or the account has no sites), which is minor for a zero-argument read.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly presents this as a no-argument call scoped implicitly to the signed-in connection.

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 (shows) and resource (the RunLite account for this connection) and then enumerates the exact contents: plan, sites with siteIds, plan limits, usage counters, and the next plan up. That is clearly distinct from sibling readers such as get_site, get_form, or get_submissions, which each target one object.

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 rather than stated: an agent can infer this is the account-level overview to call before working with sites, and 'this month's usage against the plan' hints at capacity checks. However, there is no explicit when-to-use, no when-not-to-use, and no named alternative (e.g. get_site for one site's detail).

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Changes nothing' mostly restates them. The one piece of added value is that the HTML is 'the same markup returned when the form was created', which tells the agent the markup is stable/reusable rather than freshly generated. It says nothing about what happens with an unknown formId or how large the returned HTML is.

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

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

A single front-loaded sentence that opens with the action and resource, then enumerates the payload. It is dense but each clause corresponds to a distinct returned item, so nothing feels wasted; slightly list-heavy 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 and no annotation gaps, the description usefully enumerates the returned contents and states the operation is non-mutating. The remaining gap is the formId contract (format, source) for a tool whose only input is that opaque identifier.

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

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

Schema coverage is 0% and the single parameter is undocumented, so the description must carry the burden. It identifies formId as the selector of the single form, but gives no format, example, or hint about where to obtain a valid formId (e.g., from create_form or a form listing).

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

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

Specific verb ('Shows') plus resource ('one form (formId)') and a precise enumeration of what is returned: fields, status, success message, email destination, submission count, and ready-to-paste HTML. This clearly separates it from siblings like get_submissions (submissions only) and update_form (mutation).

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

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

The description makes the usage context obvious by enumerating exactly what you get back, and 'Changes nothing' signals this is the safe read path when you only need to inspect a form. It does not explicitly name alternatives (e.g., get_submissions for per-enquiry data) or state exclusions, 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 declare readOnly, idempotent and non-destructive, and the description reinforces this with 'Changes nothing.' More valuable is the disclosure that results come 'from RunLite's own records' rather than a live fetch, which tells the agent the data may lag the deployed site — a behavioral trait not captured by any annotation.

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

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

Purpose and data source are front-loaded in the first clause, the return contents are packed into one dense but purposeful sentence, and the closing 'Changes nothing' is a two-word safety signal. No sentence is wasted.

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 compensates by enumerating the return payload in detail (files, sha256, drafts, form fields, enquiry counts), which is exactly what an agent needs to decide to call it. The remaining gap is the identifier format and the error behavior when the site is unknown.

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 siteId has 0% schema description coverage, so the description carries the full burden, yet it never says whether siteId is an internal ID, a name, or a domain. With an undocumented required identifier and a definition that mentions it not at all, this falls below the baseline of 3.

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

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

States a specific verb and resource ('Shows what a RunLite site is serving right now') and then enumerates exactly what is returned: live version, file list with sizes and sha256, recent deployments, and forms with fields and enquiry routing. This makes it clearly distinct from siblings like read_site_file, get_form, or deploy_site without opening any schema.

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

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

Gives a clear use case — 'Useful for checking a deploy without loading the site' — which tells the agent when this is preferable to hitting the live site. It does not explicitly exclude or name alternatives (e.g. 'for a single file use read_site_file'), so it falls short of the 5 bar.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real value beyond that: default spam exclusion, newest-first ordering, and an explicit warning that submitted values are untrusted anonymous content — a meaningful prompt-injection disclosure for an agent consuming this data.

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

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

Three sentences, zero filler, with the core scope and ordering front-loaded before the spam and untrusted-content caveats. The minor ISO 8601 duplication from the schema does not meaningfully waste space.

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

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

For a read-only listing tool with no output schema and no required parameters, the description covers filtering, ordering, default exclusions and data trustworthiness. The remaining gap is what an unscoped call returns (all sites?) and the page-size default, which is only visible in the schema.

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

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

Schema coverage is only 40% (formId, siteId and includeSpam are undocumented in the schema), and the description compensates by explaining the form-vs-site selector, the spam toggle, and the ISO 8601 meaning of since. The limit parameter and the behavior when both or neither identifier is passed remain unexplained.

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 ('reads recent submissions') plus the scoping axis (one form or one site) and ordering (newest first). This is unmistakably distinct from siblings like get_form or get_site, which return configuration rather than visitor-submitted 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?

Gives clear usage context: pick formId for one form or siteId for one site, and the default behavior excludes spam unless includeSpam is true. It does not name a sibling alternative or state what happens if neither identifier is supplied, so it falls short of explicit when/when-not 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?

Goes well beyond the annotations (destructive, non-idempotent, non-readonly) by disclosing atomic publication as a new version, the post-deploy constraints (root index.html, 200-file cap, plan size limits, 4 MB per call), that a non-live deletePath is refused with its name, and that exhausting the deployment allowance degrades to an unpublished draft with published=false. That is the exact set of failure modes an agent needs for a destructive mutation.

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

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

Front-loads the operation in the first clause, then spends the paragraph on quantitative constraints and edge-case behavior. Every sentence carries a distinct, actionable fact (atomic publish, draft fallback, refusal rule) with no filler.

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

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

For a destructive mutation tool with no output schema, it supplies the safety-relevant behavior and failure modes. It does not describe the overall response shape (beyond the published flag) or any authorization prerequisites, which keeps it just short of fully complete.

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

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

Schema coverage is 75%, so the schema already documents path format, encoding, and message. The description adds real semantics the schema lacks: files replace the live file at the same path, deletePaths must correspond to live files or the call is refused, and the total payload is capped at 4 MB per call. siteId and message semantics are left to the schema.

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

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

States a specific verb and resource ('changes some files of a live site') and immediately delimits scope: files added or replaced, deletePaths removed, everything else untouched. This clearly separates it from full-deploy siblings like deploy_site and from update_site without requiring the schema to be opened.

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

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

Makes the operative condition clear: the patch starts from the live version, never an unpublished draft, so it is the partial-update path rather than a full deploy. It does not explicitly name deploy_site or update_site as alternatives or state when a full deploy is preferred, so the alternative routing 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?

With destructiveHint already set, the description still adds substantial context: atomic replacement of the site's files, retryability because the upload stays open on failure, and the draft fallback plus published=false when the monthly allowance is exhausted. This is exactly the kind of consequence and edge-case disclosure annotations cannot carry.

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

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

Three sentences, front-loaded with the core action and its destructive effect, then failure semantics, then the quota edge case. The rule enumeration ('root index.html, website files only, plan limits, content checks') is dense but earns its place as precondition guidance.

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

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

For a destructive, non-idempotent publish with no output schema, the description covers what gets replaced, what happens on failure, and how the caller learns the outcome (published=false). Only the provenance of uploadId is left out, a minor gap against the rest.

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

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

The single uploadId parameter has 0% schema description coverage, so the description must compensate. It implies uploadId identifies an upload holding files, but never says where that id comes from (start_upload) or that the upload must still be open – so the one ambiguous parameter stays partially ambiguous.

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

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

States a specific verb and resource with scope: 'publishes every file an upload holds as one atomic deploy,' including that it replaces the site's files or creates the site. It's clearly distinguishable from start_upload/upload_files, but never names deploy_site to route the agent between the two publishing paths.

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 only implied by 'every file an upload holds' – an agent can infer it comes after start_upload/upload_files – but there is no explicit when-to-use or when-not versus deploy_site. The failure and rate-limit behaviors are covered, which is more about outcome than selection.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds real behavior: a 30,000-character cap per call, part-wise reads via the returned nextOffset, and that binaries yield only size and sha256. It stops short of stating error behavior when the sha256 does not match, which is the one unexplained branch.

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

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

Three dense sentences, front-loaded with the action and return contract; the text-versus-binary split and the pagination rule each earn their line. No filler and no restatement of the title.

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

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

There is no output schema, and the description compensates fully by describing what comes back for text files, the nextOffset continuation token for long files, and the size/sha256-only shape for binaries. An agent has enough to call this and interpret the response without guessing.

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

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

Schema coverage is 67% and siteId is undocumented, but the description explains the offset/pagination relationship (feed the returned nextOffset back as offset) and the 30k cap that triggers it, which goes beyond the schema's bare "Character to start from". path and siteId get no added meaning beyond the schema.

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

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

States a specific verb and resource ("Returns the current content of one file on a RunLite site's live version") with scope qualifiers that separate it from get_site, upload_files and deploy_site. The sha256-verification detail further pins down exactly what is being read.

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 "live version" scoping and the closing "Changes nothing", but no sibling is named and there is no explicit when-to-use/when-not guidance. An agent can infer this is the read path versus upload/deploy tools, but must do the routing itself.

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, it explains the immediate effect, the delayed certificate/distribution cleanup, the transient removed:false return value, and repeat-call safety. This is exactly the kind of mutation behavior an agent needs before invoking a destructive 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 three tightly written sentences, front-loaded with the main effect and followed by the timing and idempotency details. Every sentence adds useful information without 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?

For a one-parameter destructive operation with no output schema, the description covers the immediate effect, asynchronous cleanup, return behavior, and repeatability. An agent has enough context to invoke it correctly despite the simple schema.

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

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

There is only one required parameter, siteId, but schema description coverage is 0%. The description implies the parameter identifies the site but does not add format or lookup details, so it only partially compensates 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 uses a specific verb and resource: it detaches a custom domain from a site and explains the immediate fallback to a runlitehost.com subdomain. This clearly distinguishes it from sibling tools like set_custom_domain and check_custom_domain_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?

The description gives clear operational context: the domain reverts immediately, cleanup finishes later, and the call is safe to repeat. It does not explicitly compare against alternatives such as set_custom_domain, but the removal scenario is unambiguous.

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

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

Beyond the annotations, the description explains that this is an asynchronous setup process that requests a certificate and returns a CNAME record for the customer to add. It also clarifies that live traffic does not change until setup is complete, and it discloses the paid-plan prerequisite and root-domain DNS limitations.

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 and is front-loaded with the core action and return behavior. Each sentence earns its place by adding setup, DNS, or domain-form nuance without 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?

For a non-destructive but asynchronous external-DNS mutation with no output schema, the description covers the important operational details: paid plan, certificate request, returned CNAME, delayed traffic cutover, and root-domain caveats. An agent has enough information to call it correctly and explain 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 schema covers the domain parameter well, and the description adds useful meaning: the value is usually the www form, must not be a runlite address, and root domains have special DNS-provider constraints. It does not add explanation for siteId, leaving that to the schema, but siteId is self-explanatory in context.

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

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

The description states a specific verb and resource: it starts attaching a customer-owned domain to a site in place of the runlitehost.com address. It clearly distinguishes the tool from siblings like remove_custom_domain and check_custom_domain_status by focusing on initiating the attachment and returning the required CNAME record.

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 establishes clear context: the customer needs a paid plan, and root domains only work where the DNS provider supports CNAME-style root records, otherwise the www form should be used. It does not explicitly name check_custom_domain_status or remove_custom_domain as follow-up or alternative tools, which keeps it just short of a 5.

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

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

Goes well beyond the annotations: the uploadId expires after 2 hours, the 200-file and plan-dependent size limits, and the important nuance that starting is non-destructive while publishing replaces the site's files — consistent with destructiveHint=false but explaining why. That resolves the one place an agent could misjudge risk from the annotations alone.

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

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

Purpose and the uploadId return are front-loaded, and every sentence carries information. The limits sentence is dense, packing file count, two plan tiers and a pointer to the result's limits into one clause, which costs a little readability.

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

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

No output schema exists, and the description covers the return value (uploadId), its lifetime, the size constraints an agent must respect before uploading, and the create-vs-replace semantics. That is everything needed to call it correctly and plan the follow-up steps.

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 the consequence of each branch — siteId means publishing overwrites that site, its absence means name/subdomain define a new site — which is more than the terse schema text. The message parameter's role in deployment history is left entirely to the schema.

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

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

States a specific verb and resource ('Starts a deploy whose files are sent in several parts') and scopes it to sites too large for a single call. It also rules out a misreading with 'is not a deploy' and 'changes nothing live', which separates it conceptually from deploy_site. It stops short of naming the sibling tools it hands off to, so sibling differentiation is implied rather than explicit.

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 clear selection condition ('a site too large to send in one call') and a full branch on siteId: replace an existing site vs. create a new one with name/subdomain. What is missing is an explicit negative case and hand-off naming — nothing says to use deploy_site for small sites or that upload_files/publish_upload complete the flow.

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 idempotentHint=true, but the description goes well beyond them: it warns that fields replaces the entire list, reassures that submit URL, stored enquiries, and email routing survive a rename, and discloses that the return value includes regenerated HTML that changes with the fields. That is exactly the kind of consequence detail an agent needs before a destructive mutation with no output 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?

Front-loaded with the verb and resource, and every clause carries information — the replacement semantics, the preserved data, and the HTML return. It is a single dense sentence-cluster with nested parentheses, so it reads as slightly packed rather than crisply segmented, but nothing is wasted.

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 5-parameter destructive mutation with no output schema, the description covers partial-update semantics, data preservation, status toggling, and the return shape. It leaves out permission requirements and what happens on invalid field definitions (e.g., a select without options), which is the remaining gap.

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

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

Schema coverage is 80%, so the schema already documents status, successMessage (including the empty-string default behavior), and the fields list. The description adds genuine semantics on top: the wholesale replacement of fields and the fact that omitted parameters are left untouched, which is the key contract for an optional-parameter update tool.

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

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

States a specific verb and resource ("Changes an existing form in place") and enumerates the four mutable surfaces: name, fields, success message, and submission status. This makes it trivially distinguishable from create_form, get_form, and update_site without opening any schema.

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

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

The phrase "existing form" and the in-place partial-update rule ("Anything not sent stays as it is") tell the agent this is the modification path rather than creation, and the parenthetical on "paused"/"active" gives actionable context. It stops short of naming sibling alternatives or stating prerequisites, so it is clear-context rather than explicit when/when-not guidance.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description explains exactly why: 'replacing all of its files: a live file not sent is removed' and 'atomically'. It adds preconditions the annotations don't carry (root index.html required, website files only, plan limits), so the agent knows what gets destroyed and what will be rejected.

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

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

Three tight sentences, front-loaded with the operation and its destructive scope, then the siteId constraint, then inherited rules. No repetition of the title or filler.

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

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

For a destructive 3-parameter mutation with no output schema, the description covers replacement semantics, atomicity, and deploy constraints — enough to call it safely. It does not say what the caller receives back on success/failure, which is the main remaining gap.

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

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

Schema coverage is only 33% (siteId and files have no top-level descriptions), and the description compensates by explaining that siteId is required and that files is a full replacement set rather than a delta. The message parameter is left to the schema, which already documents it ('Shown in deployment history').

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 ('Re-deploys an existing site atomically, replacing all of its files') and explicitly distinguishes itself from create-type siblings with 'siteId is required, so it never creates a new site'. An agent can route between update_site and deploy_site without opening either schema.

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

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

Implies the create path belongs to deploy_site and frames this as the existing-site path, plus 'the same rules apply as for any deploy' gives context for what it inherits. It does not name deploy_site or patch_site directly as alternatives or state when not to use this tool, so the guidance 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?

Goes well beyond the annotations: it discloses a 50-file cap, the replace-on-duplicate-path semantics that give meaning to idempotentHint, per-file validation on arrival, the staged/publish-gated behaviour, and the return payload (count plus total size). That is exactly the extra context annotations cannot carry.

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

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

Five short sentences, each carrying a distinct fact (limit, overwrite rule, validation, return shape, publish gating), with the core action stated first. No filler or restatement of the title.

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

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

For a two-parameter tool with no output schema, the description covers return values, limits, validation, idempotency and the publish lifecycle. The only real gap is the origin/semantics of uploadId, which an agent must infer from start_upload.

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

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

Schema coverage is 0%, so the description must compensate and it only partly does: it explains the 'files' array limit and the replace-by-path rule, but says nothing about where uploadId comes from or what it identifies. Nested path/encoding semantics are covered by the schema, not the description.

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

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

States a specific verb (adds) and resource (files) plus the container (an open upload) and a hard limit (50 per call), which cleanly separates it from start_upload and publish_upload without naming them. It stops short of explicitly contrasting with the sibling tools, so it lands at 4 rather than 5.

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

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

'Adds files to an open upload' establishes the prerequisite that an upload already exists, and 'Nothing goes live until the upload is published' steers the agent toward publish_upload as the follow-up step. There is no explicit when-not guidance or named alternative, but the workflow context is clear.

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