nippy

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

Annotations are all false, so the description carries the full burden. It discloses the key behavioral traits: nothing is published, staged bytes are cleaned up, and the timeout context (15 minutes). This goes beyond the structured fields and gives the agent a clear picture of side effects.

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 with no fluff. The primary purpose is front-loaded, followed by usage guidance and a parameter hint. Every sentence earns its place, and the structure is optimal for quick 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?

For a two-parameter operation with no output schema, the description covers all necessary aspects: what it does, when to use it, and the specific parameter nuance. The timeout context adds operational completeness, and nothing an agent needs 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%, so both parameters are already described. The description adds value by explicitly tying batchId to start_upload/start_revision and clarifying when to pass previewId ('Pass previewId for a preview batch'), which is slightly more specific than the schema's 'Set when aborting a preview upload batch'.

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 (abort), the resource (pending batch from start_upload or start_revision), and the effect (nothing published, staged bytes cleaned up). It explicitly distinguishes from sibling tools by specifying the source of the batch and mentioning previewId for preview batches.

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 provides explicit when-to-use guidance: 'Use when an upload went wrong instead of leaving the batch to time out (15 minutes).' It also clarifies the alternative (letting it time out) and the parameter condition for preview batches, leaving no ambiguity about selection.

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 safety expectations. The description adds a useful scoping detail (the name must be a subdomain of nippy.site) but does not describe the return shape or what 'available' means in edge cases.

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 states the action, target, and domain constraint without redundant wording.

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 read-only availability check with one parameter technique, the description is largely complete. It could explicitly state the result semantics (e.g., boolean available/unavailable), but the phrase 'check whether' sufficiently implies the outcome.

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 has no parameter description (0% coverage), but the description adds meaning by defining the parameter as a site name/subdomain of nippy.site. This is adequate for a single, self-explanatory parameter.

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 identifies the action (check availability) and the resource (a site name in the nippy.site subdomain space), distinguishing it from sibling file, upload, analytics, and publish tools.

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 purpose implies the usage context — check whether a potential site name is available before using it. It does not explicitly state when not to use it, but the intended use is clear from the description.

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 destructiveHint annotation is true, and the description meaningfully expands on it by stating exactly what gets destroyed (files) and what happens to the preview's URL. It also adds the 24-hour auto-expiry behavior, which is not available from annotations alone.

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 no filler. The core action and effects are front-loaded, followed by necessary context about expiration and use cases. Every sentence 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 simple one-parameter destructive tool, the description is complete: it explains the action, consequences, when to use it, and the automatic expiration behavior. No output schema is needed for this operation, and nothing essential 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%, with previewId documented as 'Preview id from publish_preview or list_sites'. The description adds no extra parameter-level detail, so the baseline of 3 is appropriate since the schema already carries the full burden.

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 action ('Discard a preview immediately') and its concrete effects: the URL stops serving and files are deleted. This clearly distinguishes it from siblings like update_preview or publish_preview, which modify or create rather than destroy.

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 when the tool is needed ('only needed to free a cap slot early or retire a shared link') and when it is not ('Previews also expire on their own after 24 hours'). This gives the agent clear selection criteria, including the alternative of simply letting the preview expire.

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 agent knows this is destructive. The description adds important behavioral context: it verifies file sizeshare, lists missing/mismatched files in failures, and requires restarting on rejection. This goes beyond the annotation, but does not fully explain the destructive nature (e.g., what exactly gets destroyed) or potential side effects on the batch.

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, dense sentence that front-loads the core purpose ('Finish a ... batch'), then includes the precondition, verification behavior, and failure handling. No wasted words; 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 tool with only 2 parametershare (both documented in the schema) and no output schema, the description covers the main operational steps: when to call, what it does, and what happens on failure. The only gap is that it doesn't explicitly state the return value (though the output schema is absent), but given the simplicity of the operation, it's reasonably 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 100%: both parameters (siteId and batchId) have descriptions. The description adds the cross-reference between siteId and start_revision, which is a useful nuance not in the schema. However, it doesn't elaborate on parameter formats or relationships beyond that, so it adds minimal extra value.

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 identifies the tool as the 'Finish' step for an upload batch begun by start_upload or start_revision, distinguishing it from abort_upload (its sibling that cancels). It specifies the action 'Finish' and the resource 'upload batch', which 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?

The description states the precondition ('after every file has been PUT') and the consequence of failure ('must be started again'), which implies when to use it. It also references the sibling start_upload and start_revision by name, giving context. However, it does not explicitly mention when NOT to use it (e.g., if files are incomplete) or mention the alternative abort_upload, which could be a valid choice in some situations.

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 agent knows this is a safe read operation. The description adds the paid-plan restriction and the date-range scoping, which are useful behavioral constraints. It does not disclose return format, pagination, or aggregation behavior, but with annotations covering the safety profile, a 3 is appropriate.

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 resource ('visitor analytics') and includes the key qualifiers (ISO date range, paid plans). It is concise and free of filler, though it could arguably add a bit more context without becoming bloated.

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 read-only analytics tool with three required parameters and no output schema, the description is adequate but minimal. It tells the agent what the tool does and the paid-plan constraint, but it does not describe the response shape, whether data is aggregated, or any limits on the date range. Given the tool's simplicity, this is a passable but not rich definition.

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 67%, with 'from' and 'to' documented as ISO dates and examples, while 'siteId' has no description. The description adds the context that the date range is ISO and that analytics are for a site, but it does not compensate for the undocumented siteId parameter. Baseline 3 is appropriate because the schema does most of the work.

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 ('visitor analytics for a site') and adds a date-range qualifier, which distinguishes it from sibling tools like get_site_files or list_sites. It does not explicitly name a sibling alternative, but the scope is clear enough to identify what it does.

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

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

The description implies usage context: it is for retrieving visitor analytics over an ISO date range, and the '(paid plans)' note gives a prerequisite. However, it does not explicitly say when to use this tool versus alternatives, nor does it mention any exclusions or conditions beyond the paid-plan requirement.

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, the annotation already signals no side effects. The description adds the nuance that the listing reflects files 'currently' on the resource-moderate but does not disclose potential caveats such as pagination, ordering, or permissions. Overall it is consistent but provides only a small behavioral addition beyond 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?

The description is a single, front-loaded sentence with no filler. It states the action, the target, and the key parameter constraint in a compact manner.

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 two parameters and no output schema, the description covers the essential call semantics: what it liststemp, which parameters identify what, and that exactly one parameter is required. It could mention return format or item types, but the description is adequate for a read-only list operation.

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 description maps siteId to a site and previewId to a preview, and explicitly states that exactly one must be passed. This adds crucial meaning not present in the schema, where siteId has no description and no mutual-exclusivity constraint is declared.

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 uses a specific verb ('List') and a clear resource ('files currently on a site or a preview'). It clearly distinguishes this from sibling tools like list_sites, list_previews, and read_site_file by indicating it returns files, not the resources themselves.

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 clear context: this tool lists files, and it instructs the agent to 'pass exactly one' of siteId or previewId. It does not explicitly contrast with sibling tools, but the resource type ('files') makes the appropriate use case obvious enough.

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 annotations already declare readOnlyHint=true, so no further safety disclosure is needed. The description adds useful context about completeness ('COMPLETE list') and the 'no expiry' distinction, but does not add rich behavioral details beyond that. This is comparable to a straightforward read-only list tool with reasonable but minimal added 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?

Two tight sentences with no filler. The most important fact ('COMPLETE list of permanent sites') is front-loaded, and the preview exclusion and alternative tool are stated efficiently.

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 no-parameter, read-only list tool with no output schema, the description is complete: it identifies what is returned, what is excluded, and which sibling to use for the broader view. No critical information 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 zero parameters, so the schema fully documents everything an agent needs. The description reinforces the scope and content of the result, but there is no parameter ambiguity to resolve. Baseline 4 is appropriate for a no-parameter tool.

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 ('list') and a precise resource ('permanent sites on this Nippy account'), and clarifies that it excludes previews. This clearly distinguishes it from list_sites and list_previews without needing to inspect 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?

It explicitly says previews are not included and directs the agent to list_sites for a combined overview of sites and previews. This gives a clear selection rule and names the relevant alternative 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?

Annotations already provide readOnlyHint=true and openWorldHint=false, establishing that the tool is read-only and returns a complete set. The description adds behavioral context beyond annotations by stating it returns 'expiry times' and excludes 'permanent sites,' which are not captured in the structured metadata. This adds value without contradiction, though it could mention ordering or limits for full transparency.

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 concise two-sentence structure, front-loaded with the key action and scope ('COMPLETE list...'), followed by an exclusion and an alternative pointer. Every sentence earns its place with no redundancy or fluff.

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 no parameters, no output schema, and annotations covering read-only and closed-world behavior, the description fully specifies what the tool returns (temporary previews with expiry times), what it excludes (permanent sites), and when to use an alternative. An agent has all necessary information to invoke 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 tool has zero parameters and an empty schema, so schema coverage is effectively 100% (trivially). The description does not need to explain parameters, and the baseline for 0 params is 4. No additional parameter semantics are required.

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 a specific verb ('list') and resource ('temporary previews on this Nippy account'), and explicitly differentiates from the sibling tool list_sites by noting it provides a combined overview. It also specifies what is excluded (permanent sites), leaving no ambiguity about the tool's 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 explicitly tells the agent when to use this tool versus an alternative: 'For a combined overview of sites and previews, use list_sites.' This is a direct and clear usage guideline, and the exclusion of permanent sites further clarifies the intended context.

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 description explains grouping, truncation to the first 10, presence of totals, and expiry-time display for previews. These behavioral details go beyond the readOnlyHint annotation, letting an agent accurately predict what the result will contain even without an output 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 description is one well-organized sentence that front-loads the core purpose, then adds the behavioral boundaries and a pointer to alternatives. Every phrase provides useful information and there is no repetition of schema or annotation 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?

Given the tool's simplicity (no parameters, no output schema), the description is complete: it explains what the response is, how it is structured, the truncation rule, and how to reach a full enumeration if needed. Nothing an agent needs to call this tool correctly is left unstated.

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 parameter semantics baseline is 4 and the description needs no parameter explanation. The input schema is empty and fully covered by nature, so nothing additional is required.

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 the tool provides a combined OVERVIEW of all published content, split into permanent sites and temporary previews. It also distinguishes itself from siblings list_permanent_sites and list_previews by positioning itself as the summary view rather than the complete list.

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 tells the agent when this tool is appropriate (a truncated overview) and when it is not (when a complete list of one kind is needed), naming the alternative sibling tools. This gives the agent a clear selection rule without ambiguity.

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 destructiveHint already set, the description adds concrete behavioral detail: wholesale content replacement, unchanged settings/address, permanent redirect, slot-gated name minting, and grace-window behavior. This meaningfully goes beyond the annotation flags.

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 the core actioncars, then mode-specific behaviorholistic, then edge conditions. Every sentence earns its place with no repeated schema 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?

The description covers the two invocation modes, slot gating, grace-window support, post-condition redirect behavior, and irreversibility hints. For a mutation tool with no output schema and one required parameter, an agent has enough 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?

Input schema already defines parameter names and coverage is high, but the description adds crucial relational semantics: exactly one of name/siteId must be chosen)Skip and what each mode does to the target site. This is value 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?

The description states a specific verb ('make permanent') and resource ('preview'), then clearly distinguishes two modes: minting a NEW site via name vs. replacing an EXISTING site via siteId. This clearly differentiates from sibling tools like discard_preview or publish_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?

The description gives clear usage context: exactly one of name or siteId, behavior on live previews and expired previews still in the grace window, and the permanent redirect effect. It does not explicitly name sibling alternatives to route to, but the two-mode usage guidance is strong.

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 description discloses important behavioral details beyond annotations: 24-hour serving window, random slug, update_preview resetting the clock on the same URL, and the 5-preview limit on free accounts. This meaningfully informs the agent of lifecycle and side effects.

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 paragraph is dense but every sentence earns its place: it covers the address format, expiration behavior, update preference, use-case guidance, and account limits. Information is front-loaded and there is 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?

The description covers the tool's purpose, lifecycle, alternatives, and constraints well. It does not explicitly state what the invocation response contains, but it gives the address pattern and the schema is rich enough for a competent agent to 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?

The description itself adds little parameter-level detail, but the input schema contains rich nested descriptions for files, path, sha256, content, encoding, and sourceUrl. The schema effectively carries the parameter semantics, so the description's lack of field detail is acceptable but not exceptional.

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 the exact verb and resource: 'Publish files as a TEMPORARY preview' at a concrete address pattern. It clearly distinguishes this from permanent site publishing and from update_preview by emphasizing temporariness.

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 when-to-use guidance: 'Use this for drafts, iterations, and unclear intent' and prefers updating an existing preview unless a fresh address is needed. It even names the alternative behavior and explains that a preview is the 'cheap mistake'.

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 are all false, so the description carries the burden. It discloses permanence (no expiry), the free-plan limit (1 site, 25 MB), and error handling ('errors state limits honestly — relay them'). It does not mention auth requirements or side effects on existing resources, but for a creation tool this is adequate.

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?

Five concise sentences, each earning its place: core purpose first, then usage guidance, then file-handling tips, then limits. No fluff; information is front-loaded and logically ordered.

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, so the description must explain returns ('returns the live URL') and error behavior ('relay them'). It covers key constraints (inline limits, free plan cap) and points to alternatives. It could mention name-collision suffix behavior, but that is documented in the schema, so the overall picture is 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 schema already documents name and files thoroughly, but the description adds valuable non-obvious facts: the index.html convention for single-page artifacts, base64 for binaries, and the direction to start_upload for larger files. It also reiterates size limits that are partially in schema. This is more than a restatement.

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 is specific: 'Publish files as a new PERMANENT website on nippy.site — returns the live URL, no expiry.' It clearly identifies the verb (publish), resource (files), and result (live URL), and immediately contrasts with publish_preview, making the distinction 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: 'Use only when the user clearly wants a lasting result,' and when not to: 'for drafts, iterations, or unclear intent, publish_preview is the right verb.' Also provides routing for large files to start_upload. This is textbook 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 readOnlyHint=true, so the safety profile is covered. The description adds the ≤1 MB size limit and the exclusivity requirement ('pass exactly one'), which are behavioral constraints beyond the schema. It does not mention what happens if the file is missing or exceeds the limit, but the core behavior is transparent.

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 no filler. The core action, size limit, parameter choice, and usage context are all front-loaded and each sentence 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 simple read tool with readOnlyHint=true and no output schema, the description covers the essential selection criteria and constraints. It could mention what happens on error or whether the file must be text, but the ≤1 MB and 'text file' qualifiers already provide adequate context 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 only 33% (only previewId has a description). The description compensates by explaining the roles of siteId and previewId ('from a site (siteId) or a preview (previewId)') and the exclusivity rule. The path parameter is still undocumented, but its meaning is self-evident from the tool name and description.

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 ('Read'), a resource ('a text file from a site or preview'), and a size constraint (≤1 MB). It also distinguishes itself from siblings by naming update_site / update_preview as the follow-up tools, and the 'pass exactly one' instruction clarifies the siteId/previewId choice.

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 says to pass exactly one of siteId or previewId, and notes it is useful before editing with update_site / update_preview. It does not explicitly list when NOT to use it or name alternative read tools like get_site_files, but the context is clear enough for an agent to select it for reading a single file.

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 read-only, idempotency, and destructiveness. The description restates the basic removal operation but adds no extra behavioral context such as side effects, authorization requirements, or edge-case 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?

A single, front-loaded sentence that communicates the operation without 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 one-parameter, idempotent mutation with a clear sibling relationship, the description plus annotations are nearly sufficient. It could still mention prerequisites or reversibility, but the operation is simple and the annotations cover safety.

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 siteId with no descriptionhe, and the tool description does not explain what siteId refers to or any constraints. With 0% schema description coverage, the description should compensate but 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?

‘Remove a site's password protection’ is a specific verb+object statement that clearly distinguishes this tool from its sibling set_site_password.

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?

No guidance is given about when to use this tool versus set_site_password or other sibling tools. The intended context is implied but never 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 indicate it is not read-only, not destructive, and idempotent. The description adds one meaningful behavioral detail, that opting out (probably indexable=false) is a paid feature, which is not in the annotations. It does not mention error conditions, side effects, or permission requirements, so it gives only partial transparency.

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 fluff. It states the core action and immediately adds the crucial paid caveat. There is no redundant information, making it highly efficient.

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 only two simple parameters and no output schema, the description covers the essential context: the boolean toggle and the paid restriction. It does not explain the return value or specific error behavior, but for a tool of this complexity, these omissions are minor and its usefulness remains high.

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?

With zero schema description coverage, the description carries the burden of giving meaning. It clarifies that the 'indexable' parameter maps to allow (true) or disallow (false), and that disallowing is the paid opt-out. It does not add much for 'siteId', but the parameter names plus this explanation are a partial compensation.

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 verb-resource pair: allow or disallow search-engine indexing for a site. It also distinguishes this from sibling tools (e.g., set_site_meta, set_site_password) by referring specifically to indexing, so an agent can easily identify the tool's purpose.

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 you need to control search engine indexing), and the paid-feature note suggests when opting out may have constraints. However, it does not explicitly state when to prefer this over alternatives or when not to use it, though no clear alternative is apparent among the shown 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the mutation and idempotency profile. The description adds the paid-plan restriction, which is useful behavioral context. However, it does not explain null-value semantics (likely clearing fields) or error behavior, leaving some gaps beyond what annotations provide.

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

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

A single, direct sentence that front-loads the action and constraint. No wasted words; every element 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 simple tool with 3 parameters and no output schema, the description is adequate but incomplete. It lacks clarification on null semantics, potential errors, and what a successful call returns. Given the low schema coverage, more detail would help, but the tool's simplicity keeps the baseline acceptable.

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 meanings. The description only refers to 'SEO title/description' collectively, giving no detail on metaTitle, metaDescription, or siteId. It does not explain that null values are allowed or what they signify, so agents are left without critical parameter guidance.

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 verb 'Set', the resource 'SEO title/description of a site', and adds a qualifying constraint ('paid plans'). This distinguishes it from general site update tools like update_site and set_search_indexing, making the purpose 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?

It provides a specific condition ('paid plans') but does not explicitly mention when to prefer this tool over alternatives such as update_site or set_search_indexing. The guidance is implied rather than explicit, and no when-not-to-use exclusions are given.

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=false, idempotentHint=true, and destructiveHint=false. The description adds useful context by stating that visitors will need the password to view the site, but it does not disclose whether an existing password will be overwritten or whether any site-owner permissions are required.

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 tight sentences with no filler. It front-loads the core action and immediately supplies the key constraint and the visitor-facing consequence.

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 mutation, the description captures the essential action, the paid-plans restriction, and the resulting behavior, with annotations covering idempotency and non-destructiveness. It misses only minor context like overwrite behavior or a pointer to the inverse sibling tool, so it 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?

With 0% schema description coverage, the description must compensate, and it only partially does so: 'site' maps to siteId and 'password' is implied as the credential visitors will need. It does not explain value formats, length rules beyond the schema's minLength, or how siteId should be determined.

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 leads with a specific actionable phrase, 'Password-protect a site,' clearly naming the resource and the intended effect on visitors. The paid-plans qualifier and the visitor-password explanation further distinguish it from sibling tools like remove_site_password.

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 identifies the main scenario and a clear eligibility condition: use it to password-protect a site, and only on paid plans. It does not explicitly mention alternatives such as remove_site_password for the reverse operation, so it does not fully route the agent away from related tools.

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 mark it destructive and not read-only. The description adds useful behavioral details beyond that: it returns presigned PUT URLs rather than uploading directly, deletePaths operates within the same revision, and finalize_upload is the required follow-up. No contradictions with 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?

Two sentences with no filler. Purpose, return behavior, and continuation step are all front-loaded, and every sentence adds operational 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 moderate-complexity tool with no output schema, the description gives the essential call flow: presigned URL outcome and the mandatory finalize_upload follow-up. It doesn't specify the exact shape of the returned URL map, but an agent can invoke the tool correctly with the schema and this high-level contract.

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?

Only siteId is described in the schema, so the description carries some weight. It adds semantics for deletePaths ('removes files in same revision') and connects files to presigned PUT URLs, but it doesn't explain path/sizeBytes/contentType requirements; the nested schema descriptions compensate for that detail.

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 names a specific verb ('Start updating') and resource ('EXISTING site'), then sharpens it with behavior ('returns presigned PUT URLs', 'deletePaths removes files'). This makes the tool's role distinct from start_upload/update_site without needing to open 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?

Clearly frames when to use it (updating an existing site) and gives an explicit workflow handoff ('Complete with finalize_upload, passing the same siteId there'). It doesn't explicitly exclude alternatives like start_upload for new sites, so it stops short of a full when/when-not statement.

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 provide readOnlyHint=false, openWorldHint=false, destructiveHint=false, which are minimal. The description adds meaningful behavioral context: it returns presigned PUT URLs, points to Cloudflare R2 storage, warns about sandbox egress requirements, and notes that finalize verifies byte sizes. It doesn't fully describe failure modes or what happens if finalize is never called, but it discloses the key operational behavior beyond 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 sentences, each earning its place: the first states the core function and mechanism, the second adds the critical egress constraint, the third gives routing and workflow guidance. No filler, no repetition of schema content.

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

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

For a tool with no output schema, the description explains the return value (presigned PUT URLs) and the follow-up steps. It covers the key operational constraint (R2 egress) and the alternative for small files. It doesn't mention error cases or the exact shape of the presigned URL response, but for a two-parameter tool with clear workflow context, 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 50% (name and files are described in the schema). The description adds context about the files parameter (declares files, returns PUT URLs) and the name parameter (auto-suggested if omitted), which complements the schema. It doesn't detail every parameter, but the schema already covers the basics, and the description adds workflow-level meaning.

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 ('Start publishing'), a specific resource ('a NEW site'), and the key mechanism (declares files and returns presigned PUT URLs). It also distinguishes itself from publish_site and names the sibling tools for completing or abandoning the flow. This is a clear, specific purpose statement that an agent can act on.

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 says when to use this tool vs alternatives: 'For small text or base64 files, publish_site is simpler.' It also names the required follow-up tools (finalize_upload, abort_upload), giving the agent a complete workflow context. This is explicit usage guidance with alternatives and exclusions.

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 mark the tool as destructive and not read-only, so the description builds on that by specifying what exactly gets altered: only the listed files, with the same URL and a reset 24-hour clock. This adds context about scope and side effects beyond the annotations, without contradicting them. It does not mention rate limits or authorization, but the key behavioral traits are disclosed.

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 deliver the core purpose, key behavioral fact (clock reset), scope, and a usage recommendation. Every clause earns its place; there is no fluff 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?

For an iterative update tool with no output schema, the description covers the essential facts: what it does, when to prefer it, and how scope is controlled. It does not explicitly mention the required previewId or the exact parameters, but the schema provides those. The missing details (e.g., file size limits) are already in the schema's nested descriptions. Overall, an agent gets enough context to select and invoke 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?

Schema coverage is only 33%, with the top-level 'files' parameter lacking any description. The tool description mentions 'deletePaths' but does not clarify the structure of 'files' or the interplay between files, content, and sourceUrl. The schema has detailed nested property descriptions, but the description fails to compensate for the overall low coverage, leaving some parameters underspecified for an agent that doesn't read the schema deeply.

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 ('Update files on an existing preview') and immediately distinguishes it from the alternative 'publishing a new preview.' It also clarifies the 'same URL' and the 24-hour clock reset, which are unique traits that differentiate it from other preview tools. The purpose is unambiguous and distinct from 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?

The description explicitly advises 'Prefer this over publishing a new preview when iterating,' giving a clear when-to-use condition. It also explains the scope of changes ('Only the listed files change; pass deletePaths to remove files'), which implicitly instructs when to use the parameter. This is explicit guidance without requiring inference.

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 annotations already carry read/write and destructive hints, and the description adds valuable scoping beyond them: 'Only the listed files change', 'pass deletePaths to remove files', and 'the URL stays the same'. This clarifies what is and is not affected by the destructive operation. It doesn't add rate-limit or return-behavior context, but the core destructive contract is well explained.

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 three tight sentences, each carrying distinct information: purpose, scope of changes, and a binary-size routing note. It is front-loaded with the most important fact and contains 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?

Despite the schema's richness, the description omits important call-relevant semantics: sourceUrl vs content selection, sha256 mismatch behavior, and the intended large-file alternate. The internal contradiction around start_revision vs start_upload is a serious completion failure because an agent following the description may invoke the wrong sibling.

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 description adds meaning to the sparse top-level schema: it clarifies that deletePaths removes files and that inline binaries use encoding="base64". However, with schema description coverage at 33%, it still does not explain the content-vs-sourceUrl choice or the sha256 verification role, leaving the agent to discover these semantics only in the nested 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?

The description clearly states the action ('Update files on an existing site in place') and adds a useful scoping signal: 'the URL stays the same.' This distinguishes it from a publish/create action that might mint a new URL. It could name sibling tools like publish_site or update_preview explicitly, but the core purpose is clear and well differentiated.

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 misleading guidance for larger binaries: it says 'bigger ones via start_revision', but the input schema's own encoding property says that beyond inline limits 'use start_upload'. This directly contradicts the schema and could route the agent to the wrong sibling. It also provides no concrete guidance about when to choose update_site vs update_preview or publish_site.

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