sitectrl

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.

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

Annotations only say it is not read-only and not destructive; the description adds the critical async behavior (returns immediately with status 'building', ~2-3 minutes), the duplicate-build side effect, the 72-hour deletion window for unclaimed guest sites, and the free-tier one-site limit. These are exactly the traits an agent cannot infer from the structured fields.

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

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

Front-loaded with the action and the 'RETURNS IMMEDIATELY' warning before any auth detail, and nearly every sentence carries operational consequence. It is dense, packing auth modes, polling instructions, and claim mechanics into long parenthetical sentences, which slightly hurts scanability but not substance.

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 by naming the fields returned (status, slug, claim_token, claim_url, expected_url / live_url) and what to do with each. Combined with the guest-claim and free-tier rules, an agent has everything needed to call this and handle the response correctly.

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

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

Schema description coverage is 100%, so site_name, description, template, and contact_email are already fully documented with examples and constraints in the schema itself. The description reinforces intent ('plain-language description', guest-only claim flow) but adds no parameter-level syntax or format detail beyond what the schema states, which is the correct baseline.

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

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

States a specific verb and resource ('Build a brand-new hosted website from a plain-language description') and implicitly separates itself from edit_site and get_build_status by making clear this creates a new artifact each time. An agent can pick this over the siblings 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 covers when to call (new site from a description), when NOT to call again ('NEVER call create_site a second time for the same site: each call builds another one'), and which sibling to use next (get_build_status, with slug vs claim_token depending on auth state). It also states the guest and signed-in paths so the agent knows the call is valid without authentication.

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 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.

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.

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

Annotations already declare readOnlyHint=true and the description is consistent with that. Beyond annotations it adds the returned status values (building/built/failed), the no-auth guest mode, the polling interval, and the consequence of a duplicate create_site call — rich behavioral context an agent could not infer otherwise.

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 purpose, then the two auth paths, then the polling anti-pattern. No filler; each clause carries actionable information.

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

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

No output schema exists, but the description enumerates the status return values, covers both auth modes, and gives polling guidance — so an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so both parameters are already documented, but the description adds the crucial semantic that slug applies to signed-in flows and claim_token to guest flows and requires no auth. This mode-selection meaning goes beyond the field descriptions, though the required/optional dynamic (both optional) is only implicit.

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 (check) and resource (site build status), and ties it to create_site so it is unmistakably the follow-up tool. An agent can distinguish it from siblings like get_site or create_site from the description alone.

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 spells out both invocation paths: signed-in callers pass the slug from create_site, guest builds pass claim_token and work without signing in. It also states the polling cadence (every 30-60 seconds) and warns against re-calling create_site, which would build a second site.

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

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

The readOnlyHint annotation already 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.

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

readOnlyHint=true already covers the safety profile, and the description goes well beyond it by disclosing the payload's role: invariants that must be honored, platform-owned parts with snippet and rationale, and per-file base_hash needed for patching. It also surfaces the draft-vs-live state model and the no-whole-file-regeneration rule, none of which is derivable from annotations or schema.

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

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

The single most important constraint — call before any write — is placed first, and the long enumeration that follows is a dense but purposeful payload manifest. Every listed item corresponds to something a writing agent must honor, so nothing reads as 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?

There is no output schema, so the description must carry the return-value burden, and it does so item by item. Combined with the edit rules and the draft/publish lifecycle, an agent has enough to call this correctly and act on the result without further discovery.

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

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

The only parameter, slug, has 0% schema description coverage and the description never explains it. An agent must infer whether slug identifies a site, a page, or a draft context, and where to obtain a valid one (presumably list_sites). With the schema carrying no semantic load, the description should have compensated and does not.

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

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

States a specific verb and resource, then enumerates exactly what comes back: notes, brand tokens, page inventory, invariants, platform-owned snippets, per-file base_hash, and edit rules. That enumeration is what separates it from get_site, list_site_files, and read_site_file, which an agent can infer without opening their schemas.

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

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

Opens with an imperative 'CALL THIS BEFORE ANY WRITE', which is an explicit when-to-call trigger. It also names the downstream alternatives and their constraints ('patch, never regenerate a whole file', 'writes land in the draft; publish_site goes live'), so the agent knows not just when to call this but which sibling to use next.

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

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

The readOnlyHint annotation already marks this as 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.

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.

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

Annotations only say non-readonly and non-destructive; the description adds substantial context beyond them: edits apply in order, a non-unique anchor causes nothing to be written and an explanatory failure, base_hash provides optimistic concurrency from read_site_file, and validation rules (keep sc-track.js, data-sc-carry tags, sc-badge block; no noindex / 'Disallow: /' on a custom-domain site). No contradiction with destructiveHint=false, since only targeted substrings are swapped.

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 prerequisite, then purpose, then edit shapes, then the alternative, then constraints — good ordering with no filler. The trailing parenthetical constraint list is dense and slightly harder to scan, but each item is actionable.

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 mutation tool with no output schema and minimal annotations, the description covers failure modes, ordering, concurrency guarding, and content-validation rules. It stops short of describing what a successful response contains and how partial failures across multiple edits are reported.

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 carries the load and does it well for the two non-obvious params: the edits array's two accepted shapes ({find, replace} and {after, insert}), ordering, and anchor uniqueness, plus base_hash's purpose. slug and path are left entirely unexplained, which is the only remaining 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?

States a specific verb and resource (change an existing draft file in place) and explicitly frames it as 'the way to modify a page', which distinguishes it from whole-file writes. It also names the sibling it replaces (write_site_files), so an agent can choose without opening schemas.

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

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

Gives an explicit prerequisite ('Call get_site_context first') and an explicit preference with reasoning ('Prefer this to rewriting the page with write_site_files: whole-file rewrites from memory drop or duplicate things'). It also specifies when a patch is refused (anchor must appear exactly once) and when to supply base_hash.

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

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

Annotations already declare destructiveHint=true, 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.

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds genuinely new behavioral facts: encoding switches to base64 for binary content, there is a 512 KB read cap, and the response includes a hash of the current bytes. These are the exact constraints an agent needs before deciding whether this tool can carry a file's content. It does not describe behavior for a missing path or an over-cap file.

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 dense sentence with the resource up front, then encoding, size cap and return value in order of decreasing importance. No filler and nothing that restates 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?

With no output schema, the description carries the burden of explaining returns and does mention the hash, but it omits the overall response shape (where the content lives, how binary vs text is signaled) and never covers the two undocumented parameters. Adequate to attempt a call, not sufficient to call it confidently.

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 both slug and path are bare strings with no documentation in either place. The description only gestures at their meaning through "a site's draft tree" and never clarifies whether path is absolute or relative, whether it needs a leading slash, or what a slug identifies. This is the clearest gap in the definition.

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?

"Read one file from a site's draft tree" gives a specific verb plus resource and, importantly, scopes it to a single file in the draft tree, which implicitly separates it from list_site_files, write_site_files and patch_site_file. It stops short of naming those siblings explicitly, so an agent must infer the boundary rather than read it.

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

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

The description never says when to reach for this tool versus list_site_files (to discover paths) or get_site (for site metadata), nor does it state any prerequisites or failure conditions. The only contextual hint is "draft tree," which implies unreleased content but is not framed as usage guidance.

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

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

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.

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.

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

Annotations already flag this as a destructive write, but the description adds critical behavioral details beyond them: per-call file limits (40), per-file size limit (2 MB), validation behavior ('a file that fails is refused and comes back in "refused" ... other files in the same call still write'), required analytics script inclusion, and site-level invariants. This is unusually rich context for a mutation 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 long but front-loaded with the most important routing instruction ('Call get_site_context first') and the key alternative (patch_site_file). Nearly every sentence carries actionable information, though the density is high and a couple of site-rule details could be skimmed.

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 complexity of writing validated site files, the lack of an output schema, and the destructive nature of the operation, the description covers all the decision-critical aspects: prerequisites, limits, validation/refusal behavior, content-type routing, required page invariants, and the recommended follow-up (publish_site).

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 reported at 0%, so the description must carry parameter meaning and does: it explains that text files belong in 'content' while binary files (images/fonts) belong in 'content_base64,' and that overwriting an existing .html requires base_hash. These distinctions are not fully captured by the input schema and materially affect correct invocation.

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: 'Push NEW files (HTML/CSS/JS/images) into a site's DRAFT.' It immediately distinguishes itself from the sibling patch_site_file, so an agent can tell when to use which 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?

It gives explicit routing guidance: 'Call get_site_context first,' 'To CHANGE an existing page use patch_site_file instead,' and 'overwriting an existing .html needs base_hash from read_site_file.' It also clarifies the authoring scenario ('when YOU are writing the code yourself instead of asking sitectrl's AI').

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