Hostilo

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

Annotations already declare the safety profile (not read-only, not idempotent, not destructive), so the bar is lower; the description still adds real behavioral context by disclosing that the new site counts toward the plan's site limit, which is quota information an agent cannot get from annotations. It also advises that single-file HTML with inline CSS/JS works best. It does not mention name-collision behavior or failure modes.

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 short sentences, zero waste, with the concrete outcome (the generated URL) front-loaded and the caveats trailing. Every clause 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 two-parameter create tool with no output schema, the description covers the outcome (created URL), quota impact, and HTML format guidance. It stops short of saying what is returned or what happens on subdomain collision, which are minor gaps.

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 adds the practical hint that inline CSS/JS in a single file is the best format for the html parameter, but repeats the optionality and size constraint already documented in the schema.

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

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

States a specific verb and resource ('Creates a new website') and even shows the resulting URL pattern https://<name>.hostilo.app, which makes it immediately distinguishable from update_site and the read-only siblings. An agent knows exactly what this tool produces.

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

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

Implies creation context and notes HTML is optional, but gives no explicit when-to-use guidance relative to alternatives such as update_site, nor any prerequisites for choosing this over them. Usage is inferable but not 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?

Goes well beyond the read-only/idempotent annotations: it discloses the 1 MB cap, the TRUNCATED marker with full size, and the dangerous interaction with update_site, plus an explicit prompt-injection warning that returned HTML is data, not instructions. These are exactly the behavioral traits an agent cannot infer from the schema or 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 compact sentences, each carrying distinct information: what is returned, the truncation hazard, and the safety constraint. No filler or repetition of structured fields.

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 return-value burden and does so: size limit, truncation signaling, and content trust model. With a single documented parameter and full annotation coverage, nothing needed to call 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 coverage is 100%, and the schema already documents that 'site' accepts an id or a name with an example and a pointer to list_sites. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Returns the current HTML code of one site') plus scope (up to 1 MB) and the reason ('so you can edit it'). This clearly separates it from siblings like list_sites or list_versions, which do not return HTML.

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?

Strongly implies the usage context (fetch HTML in order to edit and republish it) and gives a concrete conditional warning about the truncated case and update_site. It stops short of naming alternative tools for retrieving site content or stating when not to call it, so it is clear context rather than a full routing rule.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so credit goes to added context: the newest-first ordering, the 100-item cap, and the has_more/next_cursor pagination contract. Returned fields are enumerated, though no rate limits or auth requirements are mentioned.

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

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

Three sentences, front-loaded with what the tool returns, followed by the when-to-call hint and the pagination rule. No filler; each sentence carries distinct 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?

With no output schema, the description compensates by naming the returned fields, and it fully specifies the pagination protocol and size limits. An agent has everything needed to call this tool correctly without further inference.

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 largely restates the schema ('up to limit sites (default and max 100)' and cursor = next_cursor) rather than adding format or edge-case meaning beyond it.

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 (Lists) and resource (websites/sites in the connected Hostilo account), plus the scope of returned data (live URLs, custom domains, last update time) and ordering (newest first). The phrase 'Call this first to find a site' positions it against siblings like get_site and list_versions.

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

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

Explicitly says 'Call this first to find a site,' giving clear entry-point guidance, and lays out the pagination loop (call again with cursor = next_cursor when has_more is true). It does not name which sibling to use instead once a site is identified, so it stops short of 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety and mutability profile is covered. The description adds genuinely new context the annotations lack: results are capped at 10 and ordered newest first, and each entry carries a version_id. It does not mention pagination or what happens beyond the 10-item cap.

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 sentence, front-loaded with the verb and resource, then the two most decision-relevant facts (cap and ordering) and the returned identifier. No filler or redundancy.

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 does the work of describing the return payload's key shape (version entries with version_id, newest first, max 10). The remaining gap is that it does not say what other fields a version entry contains or what happens when there are no saved versions.

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% for the single site parameter, including format examples and a pointer to list_sites, so the schema already carries the semantics. The description adds nothing about the parameter beyond what the schema says, making the baseline 3 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?

States a specific verb (Lists) and resource (saved previous versions of a site), and adds useful scope detail: capped at 10, newest first, returns version_id. It is clearly distinct from list_sites, but it never names restore_version, the sibling whose existence gives this tool its purpose, so it stops short of full sibling differentiation.

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?

There is no explicit when-to-use statement, no exclusions, and no named alternative. Usage is only implied: returning version_id signals that this is the discovery step before restore_version, but the agent must infer that pairing rather than being told it.

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 and idempotentHint=false. The description adds valuable context beyond them: the restore also publishes the version, and the current version is saved to history so the action can be undone. It does not mention permissions or confirmation requirements.

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 tightly written sentences with the core action and its safety/undo behavior front-loaded. No wasted words.

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

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

For a two-param mutation with no output schema, the description covers the action, its publish side effect, and undo capability. It could say more about resulting state or permissions, but the essentials are present.

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 with examples. The description only echoes that version_id comes from list_versions, adding little beyond the schema 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 (restores), resource (previous version of a site), and an additional consequence (publishes it), with the source of version_id named. This clearly distinguishes it from update_site and the read-only siblings.

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

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

Implies usage by pointing to version_id from list_versions, giving the agent a clear prerequisite path. It does not explicitly contrast with update_site or state when not to use it, so it stops short of full routing 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 cover the safety profile (non-readOnly, non-destructive, idempotent), so the bar is lower; the description still adds real value by disclosing that the previous version is retained in version history (last 10) and restorable, plus that publishing is immediate. It does not mention permissions or size/latency behavior, but the destructive-effect disclosure is the important part.

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 short sentences, zero filler, and the most important fact (immediate publish) is front-loaded before the recovery caveat.

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 adequately covers the mutation's effect and its reversibility, which is what an agent needs for a two-parameter write tool. Minor gap: no note on auth/permission requirements or what a successful response indicates.

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% (html with a 5 MB cap, site id/name format with list_sites reference), so the schema carries parameter meaning. The description adds nothing beyond what the schema already documents, which is the expected 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 ('Replaces the site's index.html... and publishes it immediately'), which precisely distinguishes this write path from get_site, list_sites, and restore_version. An agent can tell exactly what the call does 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?

Usage is implied by the atomic 'replace and publish' framing, but the description never states when to prefer this over restore_version or how it relates to create_site. No explicit when-not or alternative routing is given.

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