sitectrl

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses the asynchronous build status, approximate duration, expected_url and claim_token, unauthenticated guest behavior, 72-hour deletion of unclaimed sites, and free-tier constraints. This is rich, honest behavioral context that directly affects how the agent should invoke and follow up on the 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 dense but every sentence carries critical information. It front-loads the core purpose, then immediately states the async nature, the don't-call-twice rule, and the auth-dependent behavior. No filler or redundant restatement.

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

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

For a tool with no output schema and complex runtime behavior, the description covers everything an agent needs: how to handle the immediate response, where to poll, how to avoid duplicates, and how auth state changes the result. There is no missing guidance that would cause incorrect invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The main description adds value by explaining the consequences of parameters (guest builds vs signed-in builds, one-site limit, claim_url for unsigned users) and reinforces the 'plain-language description' requirement. The only reason it is not a 5 is that the schema already documents the parameters well, including minLength and examples; the description complements rather than fully compensates.

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: 'Build a brand-new hosted website from a plain-language description.' This clearly distinguishes create_site from siblings like edit_site, publish_site, and get_build_status. It does not merely restate the name or 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 gives explicit operational guidance: it returns before the site is ready, so the agent must poll get_build_status with claim_token; it warns never to call create_site twice for the same site; and it explains the signed-in vs guest flows. This goes well beyond vague 'use for creating sites' guidance.

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

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

Annotations already declare 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 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.

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?

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

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?

Beyond annotations, the description reveals important behavioral constraints: the 40-file/2MB limits, the content vs content_base64 split, the mandatory sc-track.js include and that publish re-adds it, placeholder contact info expectations, and the form submission mechanism with the no-mailto rule. This is substantial context that annotations alone do not provide.

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

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

The description is dense but every sentence adds actionable guidance: when to use, file placement, limits, required script, placeholder rules, form handling, and next step. It is front-loaded with the core purpose and avoids filler.

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

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

For a write tool with no output schema, the description covers input semantics, limits, required content conventions, and the follow-up publish step. Nothing critical is missing for an agent to correctly invoke the tool and understand the draft vs live workflow.

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 carry parameter meaning. It explicitly maps text files to 'content' and binary files to 'content_base64', and the path parameter already has schema guidance. The slug parameter is not explicitly explained, but the phrase 'a site's DRAFT' makes its role inferable.

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 starts with a specific verb and resource: 'Push files into a site's DRAFT' and clarifies the author is writing code directly rather than delegating to sitectrl's AI. It also names publish_site as the follow-up, distinguishing the write action from 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 states the trigger condition: 'use this when YOU are writing the code yourself instead of asking sitectrl's AI.' It also gives post-condition guidance with 'Follow with publish_site to go live,' which tells the agent what to do next after writing files.

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