Your AI builds real hosted websites: describe it, get a live site with SSL, forms, analytics. Free.
Scored across 13 tools
Each tool targets a fairly distinct operation: lifecycle (create/get/list/build_status), editing (edit_site vs write_site_files vs add_component), files (read/list), publishing, analytics, domains, and account. The main overlap risk is the three different editing paths (edit_site AI edits, write_site_files hand-coding, add_component library insertion), but the descriptions clearly delineate when to use each. An agent could still momentarily hesitate between edit_site and write_site_files, hence not a 5.
Nearly all names follow a clean verb_noun snake_case pattern (create_site, edit_site, get_site, list_sites, publish_site, read_site_file, write_site_files, search_domains, get_analytics, get_build_status). The lone outlier is whoami, which breaks the verb_noun convention but is still readily understood. Minor inconsistency only.
13 tools is well within the ideal 3-15 range and each tool maps to a distinct capability in the site-building lifecycle. Nothing feels padded or redundant; the set is tightly scoped to the domain.
The surface covers creation, AI/manual editing, file read/write/list, publishing, analytics, domain search, and account introspection — strong lifecycle coverage. However, there is no delete/remove operation for sites or files, and no explicit rollback/restore tool despite publish taking snapshots, leaving a couple of minor dead ends. Agents can mostly work around these gaps.
Insert a component from the site's shared library into one or more existing pages, INSTEAD of hand-writing the markup yourself — the classes are already styled and themed to this site's colours. Choices: sc-page-title (the page's one ), sc-gallery (cross-fading photo reel — needs 'images'), sc-info-tiles (title + picture + text sections — needs 'tiles'), sc-instructions (numbered/titled steps, optionally with a button each — needs 'tiles'), sc-event (one dated thing: a class, a session, an opening — needs 'title'), sc-btn (a link styled as a button — needs 'label'). NOT offered: sc-header/sc-footer (the site's own shell already emits those) or sc-hero (placed once, on the home page, by the site's own build). 'anchor' says where it goes: {"type": "heading", "value": "", "position": "after"} (default), {"type": "id", "value": "", "position": "after"}, {"type": "main_end"} (append at the end of the page), or {"type": "replace", "value": "<class of an existing sc-* block>"}. 'pages' is "all" or a list of paths from list_site_files. A page whose anchor doesn't match comes back in 'findings' with what's wrong and the fix — other pages in the same call still get the component. Follow with publish_site.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| slug | Yes | ||
| pages | No | "all", or an array of page paths, e.g. ["index.html", "about.html"] | |
| anchor | Yes | ||
| fields | Yes | Component-specific content. sc-page-title: {text, eyebrow?}. sc-gallery: {images: [{src, alt}]}. sc-info-tiles: {tiles: [{title, img?, alt?, text}]}. sc-instructions: {title?, intro?, tiles: [{title?, body, img?, alt?, button?: [label, href]}]}. sc-event: {title, img?, meta?: [{label, value}], desc?, rsvp_href?, rsvp_label?}. sc-btn: {label, href}. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description does add real behavioral context beyond that: the replace anchor overwrites an existing sc-* block, per-page anchor mismatches are reported in 'findings', and other pages in the same call still receive the component. It never explicitly warns that insertion mutates/destroys existing page content, so it only partly reinforces the destructive hint.
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?
Effectively one long paragraph but front-loaded with the core purpose before enumerating components and anchors, and every clause carries operational detail. Slight redundancy with the schema's own 'fields' description, which repeats the per-component content shape.
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 still covers the return-relevant behavior ('findings' with what is wrong and the fix), the mutation semantics, the anchor grammar, and the publish follow-up. For a nested-object, partially documented 5-param mutation tool, an agent has what it needs to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, and the description compensates substantially: it spells out all four anchor shapes with example objects, defines 'pages' as "all" or paths from list_site_files, and maps each component name to its required fields. Only 'slug' is left unexplained, which keeps it short of a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (insert) and resource (library component into existing pages) and immediately scopes it against the sibling write_site_files by saying it is used 'INSTEAD of hand-writing the markup yourself'. The enumerated component list makes the tool's surface 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?
Gives explicit when-to-use (use a pre-styled library block rather than raw markup), explicit when-NOT (NOT offered: sc-header/sc-footer/sc-hero and why), and a routing instruction to follow with publish_site. It also documents the 'findings' partial-failure path, which tells the agent what a non-fatal miss looks like.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build a brand-new hosted website from a plain-language description. RETURNS IMMEDIATELY with status 'building' — the site takes about 2-3 minutes and is NOT ready when this returns. Tell the user where it will be (expected_url) and poll get_build_status with the returned claim_token. NEVER call create_site a second time for the same site: each call builds another one. Works WITHOUT signing in: an unauthenticated call builds a guest site and returns a claim_url — the user signs up free (no card) at that link to keep it; unclaimed guest sites are deleted after 72 hours. Signed in, the site lands directly on the connected account (free tier: one site, no card).
| Name | Required | Description | Default |
|---|---|---|---|
| template | No | Starting template (guest builds; default local-services). | |
| site_name | Yes | Short human name for the site, e.g. 'Whitney Apparel'. | |
| description | Yes | What the site is for. MINIMUM 12 CHARACTERS — a bare 'bike shop' is rejected. Say what the business is, where it is, and what the site should include; the AI builds directly from this, so more detail means a better first result. Good: 'Oak Barrel Coffee, a small-batch roaster in Turlock CA — our story, three coffees with tasting notes and prices, and a contact form.' If the user was vague, ask them one question before calling this rather than sending two words. | |
| contact_email | No | Optional, guest builds only: the user's email — we send the site link and a reminder before the unclaimed site expires. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description reveals crucial asynchronous behavior: it returns immediately with status 'building' and is not ready. It discloses the 2-3 minute build time, the expiration of guest sites after 72 hours, and the need for claim_url for unauthenticated users. This far exceeds what annotations convey and gives the agent an accurate model of side effects and timing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured. It front-loads the most critical behavior (returns immediately, not ready) and then covers polling, idempotency, guest vs signed-in, and expiration. While it is relatively long, every sentence contributes necessary information; there is no fluff. It earns a 4 rather than 5 because it could be slightly tightened without losing content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity—async build, token-based polling, guest accounts, expiration, and multiple parameters—the description covers all operational essentials. It specifies expected_url and claim_token, describes the guest claim flow, and explains the free-tier constraint. An agent can confidently call this tool and handle the response correctly without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds significant value beyond the schema. For the 'description' parameter, it explains the minimum length requirement, provides a concrete example, and advises on the level of detail needed. For 'contact_email', it explains the guest-only purpose and the reminder behavior. This enriches the schema and helps the agent craft effective calls.
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-oriented purpose: 'Build a brand-new hosted website from a plain-language description.' It clearly identifies the resource (a hosted website) and the action (build), and distinguishes it from siblings like edit_site, get_site, and publish_site. The mention of returning immediately with status 'building' and requiring polling further clarifies what this tool uniquely 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 explicit usage guidance: it instructs the agent to poll get_build_status with the returned claim_token, warns never to call create_site twice for the same site, and explains the guest vs signed-in flow. It also advises asking the user one clarifying question if the description is vague, which is a clear directive on when to call and how to prepare input.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask sitectrl's AI editor to change an existing site ('add a contact page', 'make the hero darker'). Edits land in the site's draft; the first build of a brand-new site goes straight live. Returns what changed plus the draft URL.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| instruction | Yes | The change to make, in plain language. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare not read-only and not destructive, but the description adds meaningful context: edits go to draft, first build of a new site goes live, and it returns what changed plus the draft URL. This is beyond annotation value and sets correct expectations 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 well-structured sentences, front-loaded with purpose and examples. It includes the draft/live nuance and return info without any wasted words, making it efficient and readable.
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?
It explains the draft/live behavior and the return value, which compensates for the lack of an output schema. The only minor gap is the implicit definition of 'slug', but overall an agent has enough to call 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 only documents 'instruction' (50% coverage); description provides examples for instruction but does not explicitly explain 'slug' or its format. The description implies slug identifies the site, but it's not stated. The examples add some value, but the slug semantics remain under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('change an existing site') with concrete examples, and the resource (site) is unambiguous. It implicitly differentiates from create_site and publish_site by focusing on existing sites and the draft/live distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'change an existing site', signaling when to use this tool over creating a new site. It does not name sibling tools directly, but the draft/live behavior provides contextual clarity. Slightly lacking explicit 'when not to use' exclusions, but the target use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The site's private first-party traffic: pageviews/visitors/sessions/clicks totals, top pages, referrers, devices. Windows: 24h, 7d, 30d.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| window | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes that the tool is read-only, and the description adds that the data is 'private first-party traffic', which is useful context. However, it does not disclose return format, pagination, or any rate-limiting beyond what is implied by 'windows'. With the annotation covering safety, the description adds moderate behavioral value.
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 that front-loads the core purpose ('The site's private first-party traffic') followed by the metrics and windows. Every word adds value, with no redundancy. It is efficiently structured for quick agent parsing.
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 parameter set (two parameters, one required) and the readOnly annotation, the description provides a clear scope of what data is returned (metrics and windows). Since there is no output schema, it goes partway by enumerating the returned metrics, though it does not explicitly describe the response format (e.g., whether it is a flat object or nested). For a read-only analytics tool, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It explains the 'window' parameter by listing the allowed values (24h, 7d, 30d), which aligns with the enum. The 'slug' parameter is only implied as the site identifier ('The site's...'), with no explicit definition. This partial compensation is adequate but not thorough.
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 ('get') and resource ('site analytics'), and enumerates the exact metrics returned (pageviews, visitors, sessions, clicks, top pages, referrers, devices) and available windows (24h, 7d, 30d). This clearly distinguishes it from sibling tools like get_site or get_build_status, which serve different purposes.
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 when site traffic analytics are needed, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusion conditions or prerequisites. For instance, there is no guidance about needing a site slug from a prior call or whether this works for unbuilt sites. Usage is inferred from context but not made explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether a site started by create_site has finished. Pass the claim_token create_site returned. Works WITHOUT signing in. Poll this every 30-60 seconds rather than calling create_site again — a second create_site call builds a SECOND site.
| Name | Required | Description | Default |
|---|---|---|---|
| claim_token | Yes | The claim_token from create_site. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds value beyond that by noting it works without signing in and recommending a polling cadence. The duplicate-site warning also helps prevent misuse, though return statuses are not described.
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 purpose and immediately follow with the token requirement and polling guidance. No filler or redundant explanation.
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 status-check tool, the description covers purpose, token source, auth requirements, and polling behavior. Nothing essential 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% and already specifies claim_token comes from create_site. The description repeats that provenance without adding new format or semantic details, so it stays at the baseline for fully documented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Check whether') and resource ('a site started by create_site'), and clarifies the tool is about build completion. It is immediately distinguishable from siblings like create_site and get_site.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: poll every 30-60 seconds instead of calling create_site again, and warns that a second create_site call creates a second site. This clearly tells the agent when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Details for one site: live URL, draft URL, status.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The site's slug from list_sites. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers the read-only nature, and the description does not contradict it. However, the description adds little beyond that: it does not mention error behavior for unknown slugs, data freshness, or whether the response includes nullable fields. This is acceptable for a simple read-only tool but provides no extra 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 a single sentence that immediately conveys the resource scope and the expected payload fields. There is no redundant wording, repetition of the tool name, or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only lookup tool, the description is sufficient for an agent to invoke it correctly: it states the scope, the input source in the schema, and the fields the agent should expect in the response. No output schema exists, so explicitly naming live URL, draft URL, and status fills that gap well.
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 sole parameter completely, including its provenance from list_sites, so the description does not need to add parameter semantics. At 100% schema description coverage, the baseline of 3 is appropriate; the description adds no additional parameter 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 clearly states that the tool returns details for exactly one site, specifying the resource and the fields returned (live URL, draft URL, status). This distinguishes it from sibling tools like list_sites, which handle multiple sites, and from get_build_status and get_analytics, which focus on different concerns.
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 implicit usage context: it is for fetching one site's details after obtaining a slug via list_sites, as reinforced by the schema's parameter description. However, it does not explicitly state when not to use it or compare it with alternatives such as get_build_status or list_sites, leaving some selection burden on the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the files in a site's draft tree (paths + sizes).
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already marks this as safe, and the description adds useful behavioral context: it operates on the draft tree and returns file paths and sizes rather than file contents. This clarifies the scope beyond what the annotation alone conveys.
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 phrase earns its place: the operation, the target scope, and the returned data.
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 listing tool, the description is nearly complete. It states the input (site slug), the scope (draft tree), and the return content (paths + sizes). A note on ordering or pagination would improve it, but nothing essential is missing for a correct call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only 'slug: string' with no description, and the description implies slug identifies the site whose files should be listed. However, it does not explain the slug format, how to obtain it, or how it relates to get_site or list_sites, leaving part of the parameter 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 states a specific verb and resource: 'List the files in a site's draft tree' and adds the result shape ('paths + sizes'). This clearly distinguishes it from siblings like list_sites (which lists sites) and read_site_file/write_site_files (which handle file contents).
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 intended use is implied by the verb and resource, but the description does not explicitly state when to prefer this tool over alternatives or when not to use it. No alternatives or exclusions are mentioned, so the agent must infer the usage context from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the user's sitectrl sites with their live URLs and hosting platform.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals that this is a safe read operation, so the description does not need to restate that. It adds useful context about the response contents (live URLs, hosting platform), but it does not disclose pagination, ordering, or authorization behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler. It front-loads the action and resource, then adds the key output details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter list operation, the description is nearly complete: it states what is listed and what is included in the results. Since there is no output schema, explicitly noting the response shape or empty-state behavior would make it 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?
The tool has zero parameters, so the description does not need to explain parameter meaning. The phrase 'user's sites' clarifies scope conceptually, which is sufficient for a no-parameter call.
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 ('List') and a clear resource ('the user's sitectrl sites'), and it adds what is returned ('live URLs and hosting platform'). This makes it easy to distinguish from sibling tools like get_site and list_site_files, even without explicitly naming them.
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: to list all of the user's sites rather than a specific site or its files. However, it does not explicitly state when not to use it or name alternatives like get_site, so the guidance is mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish the site's draft to the LIVE site (hosted sites). A snapshot of the previous live version is taken first, so it's undoable.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description's job is to add context beyond that. It does: 'A snapshot of the previous live version is taken first, so it's undoable' explains the mitigating safety mechanism behind the destructive operation. This is genuinely valuable behavioral disclosure, though it doesn't address permissions or post-publish side effects like rebuilds.
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 zero filler. The primary action is front-loaded in the first sentence, and the second sentence earns its place by adding the snapshot/undo safety detail. Nothing extraneous.
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 low-complexity, single-parameter tool with annotations already covering the destructive profile, the description covers the essentials: the action, the hosted-site scope, and the undo safety net. The main gap is unaddressed slug semantics and the absent return-value note, but given no output schema and a single obvious parameter, an agent can reasonably proceed.
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% — the schema offers only 'slug: string' with no description — so the description must compensate. It does not: 'slug' is never explained or even mentioned. The agent must infer that slug identifies the site from the tool name alone. With low coverage and no compensation, this is a clear 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 states a specific verb ('Publish'), a precise source resource ('the site's draft') and a target ('the LIVE site'), which clearly differentiates it from sibling tools like create_site, edit_site, and write_site_files. The 'hosted sites' qualifier adds useful scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it — to move a draft into production — and the parenthetical '(hosted sites)' hints at a scope restriction. However, it never explicitly names alternatives, states when NOT to use it, or clarifies prerequisites (e.g., a draft must exist). Usage context is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one file from a site's draft tree (text, or base64 for binary; 512 KB cap).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, and the description adds meaningful behavior: text vs base64 for binary and a 512 KB cap. It does not cover missing-file behavior, but the safety profile is already 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?
A single front-loaded sentence with no filler. Every clause adds necessary information: what is read, where from, encoding behavior, and the size cap.
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 tool with a readOnly annotation, the description covers the key operational details: target tree, encoding, and size limit. Missing path-format specifics are a minor gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not define 'slug' or 'path' beyond property names. It leaves the path format and exact meaning of slug to inference, so it fails to compensate 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?
States a specific verb and resource: 'Read one file from a site's draft tree.' It clearly distinguishes itself from siblings like list_site_files and write_site_files by specifying a single-file 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?
The description implies when to use the tool (reading one file) but does not explicitly name alternatives or exclusions, such as using list_site_files to discover paths or write_site_files to modify files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search real domain availability + prices (com/net/org/co/io/site and more). Available results include a purchase_url — hand it to the USER to complete checkout; the connector never spends money. Purchased domains connect to their sites in one click.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Domain or name to check, e.g. 'sierratrailcoffee.com'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already marks it as read-only, and the description adds valuable behavioral context beyond that: available results include a purchase_url, but the connector never spends money and the user must finish the purchase. This prevents the agent from misinterpreting the result as something to act on financially.
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 in the first sentence. The final sentence about purchased domains connecting to sites is contextually useful but somewhat incidental to invoking this tool, so it falls just short of a perfect score.
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, high-schema-coverage tool, the description is complete. It tells the agent what the tool checks (availability and prices), what the returned result contains when available (purchase_url), and what to do with that result (give it to the user).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single query parameter completely with an example, so the description does not need to restate it. The description adds a little extra meaning by listing supported TLDs, but the schema carries most of the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource pair: 'Search real domain availability + prices', which clearly states the operation and distinguishes it from the site-management siblings such as create_site, edit_site, and publish_site. It also names covered TLDs, so the tool's scope is immediately apparent.
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 frames the tool as search-only and tells the agent not to complete checkout itself: 'hand it to the USER to complete checkout; the connector never spends money.' This is a clear when-to-use and when-not-to-use directive, especially useful in the presence of create/publish siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The connected sitectrl account: email, plan status, free-site slot, and credit balance.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already declaring the safety profile, the description adds useful behavioral context by specifying the exact account attributes (email, plan status, free-site slot, credit balance) that will be reported. It introduces no hidden side effects or contradictions with 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 front-loads the subject and lists the relevant output fields without repetition, filler, or restating the title. Every word 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 zero-parameter, read-only identity tool with no output schema, this description is sufficient: it names the scope ('connected account') and the returned fields. Nothing an agent needs to select or successfully 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?
The tool has no parameters and no schema descriptions, so the parameter burden is zero; the no-parameter baseline of 4 applies. The description contributes nothing about parameters because there is nothing to contribute.
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 identifies the resource ('the connected sitectrl account') and enumerates the returned data fields, clearly distinguishing it from the sibling site-management tools. It lacks an explicit verb like 'retrieves' or 'returns,' but the intent is unambiguous from the noun phrase and tool title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear this is the tool for inspecting the currently connected account's identity and quota details—context that lets an agent select it for account-status questions. It does not name alternatives, but no sibling covers account identity, and zero parameters makes invocation trivial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Push files (HTML/CSS/JS/images) into a site's DRAFT — use this when YOU are writing the code yourself instead of asking sitectrl's AI. Text files go in 'content'; binary files (images/fonts) in 'content_base64'. Max 40 files/call, 2 MB/file. Keep the include on every HTML page (the site's built-in private analytics — publish re-adds it if missing). Use clearly-marked placeholder contact info unless the user provided real details. For working forms, POST to /_sc/form/submit with a hidden _form name field — submissions reach the owner's dashboard + email (never use mailto:). Every HTML file is checked before it's written (DOCTYPE, charset, and any invariant this site has declared) — a file that fails is refused and comes back in 'refused' with what's wrong and the exact fix; other files in the same call still write. Follow with publish_site to go live.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | ||
| files | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare non-readOnly and destructive. The description adds substantial operational context: 40 files/call and 2 MB/file limits, draft-vs-published semantics, the pre-write validation check with partial-failure behavior ('other files still write'), the 'refused' response field, and the sc-track.js re-add invariant on publish. This is rich disclosure well 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?
Dense but every sentence earns its place: limits, routing to alternative, file-split semantics, invariants, forms guidance, validation behavior, next step. Front-loads the core action. Slightly long but justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates by explaining the 'refused' field and partial-write behavior. Covers limits, format rules, validation invariants, and the follow-up publish step. An agent has everything needed 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 0%, so the description must compensate. It explains that text content goes in 'content' and binary in 'content_base64', which is the key discriminator between the two file-array fields. It doesn't explain 'slug' or 'path' semantics, so not a full 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (push files) and resource (into a site's DRAFT) and enumerates the file types (HTML/CSS/JS/images). Clearly distinguished from sibling edit_site and publish_site by scoping to the draft and pointing at publish_site for going live.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it: 'when YOU are writing the code yourself instead of asking sitectrl's AI.' Also routes to publish_site for going live. No explicit when-not, but the AI-vs-self distinction is strong context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add_componentcreate_site1 field changedInput schema / properties / template / enumPrevious value: -[
- "local-services",
- "blank",
- "restaurant",
- "brewery",
- "shop",
- "portfolio"
-]New value: +[
+ "local-services",
+ "restaurant",
+ "shop",
+ "portfolio",
+ "classes",
+ "community"
+]get_build_statuscreate_site2 fields changedInput schema / properties / description / descriptionPrevious value: -"What the site is for — business, tone, sections wanted. The AI builds directly from this."New value: +"What the site is for. MINIMUM 12 CHARACTERS — a bare 'bike shop' is rejected. Say what the business is, where it is, and what the site should include; the AI builds directly from this, so more detail means a better first result. Good: 'Oak Barrel Coffee, a small-batch roaster in Turlock CA — our story, three coffees with tasting notes and prices, and a contact form.' If the user was vague, ask them one question before calling this rather than sending two words."Input schema / properties / description / minLengthAdded value: +12create_siteedit_siteget_analyticsget_sitelist_site_fileslist_sitespublish_siteread_site_filesearch_domainswhoamiwrite_site_filesBuild & edit your own website by talking to your LLM: pages, forms, SEO, analytics. Free to start.
Build, edit and run real hosted websites from your AI - content, SEO, menus, store, rollback.
Build, edit, and publish real websites and online stores by chatting with your AI assistant.
Build a hosted website by chatting. Snapshots, forms, analytics. Hand off the dashboard. Walk away.
Add one secure layer between your agents and this server.
