Hostsmith

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

Annotations already declare destructiveHint=true, so the write/create nature is covered; the description adds substantial extra context — the list_domains dependency, active-status requirement, partition-matching constraint, and the apex/subdomain capability rules. It doesn't describe rollback or quota behavior, keeping it just short of a 5.

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

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

Front-loads the purpose and the deploy follow-up path before the parameter rules. Dense and mostly earned, though the apex/subdomain paragraph is lengthy and partly duplicates schema guidance.

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

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

For a mutation tool with no output schema, it names the return values, the prerequisite lookup tool, the confirmation flow location, and the capability constraints. An agent has everything needed to call it correctly without opening the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real cross-parameter semantics beyond the schema: domain must come from list_domains, partition must match domain, and subdomain validity depends on the domain's enableApexDomain/enableSubdomains capabilities. The www/apex rule overlaps with the schema text, 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+resource ('Create a new Hostsmith site') and names the return payload (siteId, URL, configuration). It clearly routes the agent away from sibling deploy tools and delete_site, so selection is unambiguous.

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

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

Explicitly states when to use it ('publish or host new content and no suitable site already exists') and names the correct follow-up alternatives, deploy_files vs deploy_create_upload + deploy_finalize, with the condition (inline text vs binaries > ~1 MB) that selects between them.

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

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

Annotations only declare destructiveHint=true; the description adds substantial context beyond that: irreversibility, immediate URL unreachability, deletion of deployed files, and the confirm safeguard that returns an error rather than silently proceeding. This is exactly the extra behavioral detail the annotation bar asks for.

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

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

Three tight sentences, with the destructive warning bolded and front-loaded before the mechanics of confirm. No sentence is wasted.

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

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

No output schema exists, and the description covers the error path and irreversibility well, which is the key information for a destructive tool. It does not describe the success response, but that is a minor gap against otherwise complete coverage.

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, but the description adds meaning to confirm beyond the schema by describing the safeguard's runtime behavior (error returned when not passed). The other parameters are left entirely to the schema, which is acceptable given full 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 (permanently delete), resource (Hostsmith site), and scope (all deployed files), which cleanly separates it from the create/get/list siblings. An agent can identify the tool without opening the 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 states the precondition ('only call after explicit user confirmation') and the required confirm: true, plus the failure mode if omitted. It does not name an alternative, but no alternative delete operation exists among the siblings, so the routing guidance is effectively complete.

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 only destructiveHint=true in annotations, the description carries the burden and exceeds it: it documents the full three-step protocol, the ETag capture requirement, single- vs multi-part handling, the 1-hour token expiry, overwrite behavior, and explicit anti-patterns. This is far more behavioral context than the annotations supply.

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

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

The purpose and alternative are well front-loaded, but the definition runs extremely long, embedding multiple bash and Python templates, escalation ladders, and per-sandbox config snippets. Much of that material is genuinely useful yet disproportionately heavy for a tool description, diluting the selection-relevant signal.

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

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

For a complex multi-step tool with no output schema, the description supplies the response envelope shape, the finalize handoff, the prerequisite chain, and failure recovery. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter (fileName, fileSize, siteId, partition, conversation_id). The description shows how to construct the `files` array and what the response envelope contains, but adds no per-parameter syntax or constraints beyond the schema. Baseline 3 is appropriate.

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

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

First sentence states a specific verb and resource ('Start a direct-to-S3 upload for binary or large files') and immediately names the sibling it replaces (`deploy_files`) along with the condition that selects it. An agent can distinguish it from `deploy_files`/`deploy_finalize` 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?

Explicit when-to-use (binaries, >1 MB), when-not (trivial single small file), the zipping rule (>3 files or >1 MB), prerequisites (site must exist, call create_site first), and a required user-confirmation step for overwrite. Alternatives and exclusions are fully spelled out.

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

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

Annotations only declare destructiveHint=true; the description adds substantive context beyond that: it overwrites existing content and requires user confirmation, returns deployment version and status, points to get_site for the public URL, and explains the binary anti-pattern with rationale (bloat, broken caching, reshipping bytes).

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

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

Front-loaded with the core action and usage, then the anti-pattern block. Mostly earns its place, though the anti-pattern paragraph is long and somewhat repetitive in its justification, edging toward over-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?

No output schema exists, yet the description states the return (deployment version and status) and the follow-up (get_site for the URL). Prerequisites, destructive behavior, and the sibling route are all covered, so an agent has everything needed 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 100%, so the description carries little param burden. It only implicitly references siteId ('if you do not have a siteId') and adds no format or constraint detail for files/partition/conversation_id beyond the schema.

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

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

States a precise verb+resource+scope: 'Publish in-memory file contents to a Hostsmith site without writing to disk.' The 'in-memory'/'without writing to disk' qualifier distinguishes it from siblings like deploy_create_upload, so an agent can route correctly 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?

Explicit when-to-use ('just generated content... user wants it live'), a prerequisite ('site must already exist - call create_site first'), an overwrite-confirmation rule, and a clearly-named alternative for the binary case (deploy_create_upload). Names the when-nots and the alternative, which is the top of the scale.

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 flag destructiveHint=true; the description adds real behavioral context on top: the site must belong to the authenticated user, bearer-token auth is re-validated server-side, and holding presigned URLs is insufficient to finalize. It also discloses the return value (live site URL). Does not cover idempotency or partial-failure behavior, hence a 4 rather than 5.

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

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

Four sentences, no padding, and the prerequisite call is front-loaded before the parameter detail. Slightly dense in the completions sentence but every clause carries load-bearing information.

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

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

For a terminal mutation step with no output schema, the description covers the prerequisite call, the conditional parameter shape, the auth/ownership constraint, and the success return value. It is nearly complete; only failure and retry semantics are absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains that versionId comes from the start response and that the completions array exists only for multi-part uploads, with the empty-uploadId exemption for single-part files. This clarifies the cross-call data flow the schema cannot express on its own.

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 ('Commit a deploy') plus the resource and the exact sibling that must precede it ('deploy_create_upload'). An agent can distinguish this from deploy_files or create_site without opening any schema.

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

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

Gives clear triggering context: it must follow deploy_create_upload and consume that call's versionId. It also states the conditional rule that single-part uploads (empty uploadId) need no completion entry. It stops short of naming an alternative tool or describing failure/recovery paths, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses exactly what is returned and the non-obvious aggregation rule 'Usage is summed across all partitions,' which prevents an agent from misreading per-partition numbers.

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, both load-bearing: the first front-loads the returned payload, the second front-loads the use case. No filler, no restatement of the tool name, and the aggregation caveat is placed immediately after the data inventory it qualifies.

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 carries the burden of describing return values — and it does, listing org identity, home partition, plan limits (sites, domains, storage, bandwidth), and usage counts. For a zero-argument read tool with annotations covering safety, nothing an agent needs is missing.

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

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

Schema description coverage is 100%, and both parameters (`llm_model`, `conversation_id`) are thoroughly documented in the schema itself, including the analytics-only purpose and the conversation_id chaining rule. The description adds nothing about parameters, so the baseline 3 applies; the tool exposes no business parameters to explain.

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

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

Specific verb-plus-resource ('Get the user's account') followed by an enumeration of the returned data: org details (`orgId`, `orgName`), `user.homePartition`, subscription plan limits, and usage counts. This clearly separates it from the site/domain/deploy siblings, which operate on resources rather than account metadata.

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 when to reach for it: 'to check how much headroom the user has before creating new sites or to confirm plan-tier features.' It gives concrete intent without naming an alternative tool or a when-not-to-use condition, so it stops just short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the shape of the URL returned, that deployment status is included, and that partition defaults to the user's home partition. It stops short of describing pagination or freshness/error behavior, but for a read tool this is solid.

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

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

Three sentences, all front-loaded: purpose first, then the two workflow triggers, then the partition caveat. No filler and no repetition of schema-level detail that would waste the reader's attention.

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 convey return content, and it does (public URL, deployment status, configuration). Combined with the fully documented 4-parameter schema and readOnlyHint, an agent has everything needed to call this 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 the baseline is 3. The description's note about partition defaulting to the home partition and being visible in list_sites largely restates the schema's own wording, and it says nothing about siteId, llm_model, or conversation_id, which the schema already documents thoroughly.

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 ('Get full details of a specific Hostsmith site by ID') and enumerates what is returned: public URL, deployment status, and configuration. It explicitly names the sibling it follows (list_sites) and can be told apart from create_site/delete_site without opening a schema.

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

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

Gives explicit when-to-use conditions tied to concrete workflows: after list_sites to inspect one site, or after deploy_files/deploy_finalize to confirm the site is live and obtain the URL. It also states when to override the partition parameter and where that value comes from.

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 already declares a safe read. The description adds meaningful behavior beyond that: it discloses the default (queries all partitions and merges results) and how the narrowing parameters change that, which is not derivable from the annotations.

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

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

Three tight sentences, front-loaded with purpose, then the return contents, then usage and narrowing. Every sentence earns its place with no filler.

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

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

With no output schema, the description carries the return-value burden and does so by naming both domain categories and giving a concrete example. Enough context 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 description coverage is 100%, so the baseline is 3. The description clears that bar by explaining the default merge-across-partitions behavior and the effect of `partition`/`shared`, adding default-value semantics the schema doesn't state.

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 ('List domains the user can host sites under') and immediately specifies the contents: shared hosting domains plus organization-owned custom domains. It also distinguishes its role from siblings by naming create_site as the downstream consumer of the returned domain value.

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 frames the use case: 'Use this to pick a `domain` value before calling `create_site`.' It also gives narrowing guidance for `partition`/`shared`, but stops short of stating when NOT to use this tool or any explicit alternative for other domain-related needs.

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 tells the agent this is a safe read, so the bar is lower. The description adds behavior beyond the annotations: it discloses the returned field set and the default cross-partition query-and-merge semantics. It stops short of describing pagination or result-size limits, so it is strong but not exhaustive.

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

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

Four sentences, front-loaded with the verb+resource, then returns, then routing guidance, then the partition nuance. No sentence is redundant with another, and the most decision-relevant information (what it returns and when to call it) comes early.

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

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

With no output schema, the description compensates by naming the returned fields, and with readOnlyHint covering safety and 100% schema coverage on parameters, there is little left unstated. An agent has what it needs to resolve a site reference and route the siteId into a sibling tool.

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

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

Schema description coverage is 100%, so the llm_model and conversation_id parameters are fully documented in the schema and the baseline is 3. The description adds meaning beyond the schema for `partition`: it clarifies that the default is to query all partitions and merge the results, whereas the schema only says 'omit to query all partitions'.

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 (List) and resource (Hostsmith sites) scoped to the user's account, and enumerates the exact fields returned (siteId, subdomain, domain, status). It also names the downstream siblings that consume siteId (get_site, deploy_files, deploy_create_upload, delete_site), so an agent can distinguish it from any other listing tool without opening a schema.

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

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

Explicitly prescribes when to call it: 'call it before any create/deploy/delete to resolve the user's site reference', and frames it as 'the source of truth for does the user already have a site at FQDN X'. That is a clear precondition tying it to the create_site/deploy_*/delete_site siblings rather than leaving usage to inference.

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