Revdoku

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

Annotations show destructiveHint: false, which aligns with archiving (non-destructive). The description adds that archiving requires the bucket to not have active published websites, disclosing an important constraint not present in annotations. It does not detail the result or confirm reversibility, but given standard MCP context, this is sufficient.

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 extremely concise: two sentences, zero wasted words. The first sentence states the action, and the second provides a critical constraint. No fluff or repetition.

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 has one parameter with full schema coverage, clear annotations, and an output schema not shown but implied, the description covers the essential behavior and prerequisite. It lacks mention of what happens upon success (e.g., bucket is no longer listed as active) or failure, but the output schema likely fills that gap. Overall adequate for a single-action 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?

The schema has 100% coverage for the single required parameter (bucket_id) with a clear description and example format. The description does not add new information about the parameter beyond what the schema provides, so a baseline score of 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?

The description clearly states the action ('Archive one bucket') and specifies the resource ('bucket'). It distinguishes the tool from siblings like 'bucket_delete_permanently' and 'bucket_unarchive' by implying archiving is reversible and not destructive.

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 includes a crucial prerequisite: 'Active websites must be unpublished first.' This guides the user not to attempt archiving a bucket with an active publication, providing direct when-not use guidance. However, it does not explicitly name alternatives like 'bucket_unpublish' for that prerequisite step.

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 a mutating, non-read-only operation. The description adds valuable behavioral context: the bucket is private, search indexing defaults to true, and writing files only creates a private draft rather than publishing content. It does not overclaim idempotency or safety, and it does not contradict 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 action and purpose, the second gives a crucial default-and-consent caveat, and the third surfaces forms configuration and the private-draft behavior. The description is front-loaded and free of filler despite the tool's complex schema.

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 creation tool with a rich input schema and an output schema, the description covers the key contextual points an agent needs: private bucket semantics, default search indexing, forms configuration, and the draft-only effect of writing files. It does not detail every nested form option, but those are already documented thoroughly in 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 description coverage is 100%, so the schema carries most parameter meaning. The description still adds useful guidance beyond the schema, such as 'set allow_search_indexing=false only when the owner asks' and orienting the agent to metadata.publication_forms for built-in forms. It does not redundantly restate title or description semantics.

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 ('Create a private Revdoku bucket') and the intended use cases ('agent-generated files, reports, or websites'). It is specific enough to distinguish the core purpose from other bucket tools, though it does not explicitly name or contrast siblings like bucket_create_from_template.

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 provides clear operational context: buckets are private by default, public websites allow search indexing unless the owner requests otherwise, and forms are configured via metadata.publication_forms. It does not explicitly state when to prefer this tool over bucket_create_from_template or bucket_update, but the provided context is sufficient for basic 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?

Annotations already indicate a mutating, non-destructive, non-idempotent operation. The description adds that the created bucket is private and not published, which is useful but minimal. 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?

The description is two sentences and 17 words, with no filler. It is front-loaded with the core action and ends with an important property. Every word earns its place.

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

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

For a creation tool with an output schema, the description covers the main action and a key property but lacks prerequisites (e.g., template key must be from a trusted manifest, which is mentioned but not detailed) and does not reference the expected output. It is minimally adequate.

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 all parameters. The tool description adds no additional parameter context such as constraints, examples, or usage notes beyond what is 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?

The description clearly states the tool creates a private Revdoku bucket from a template manifest, with the note that it is not published. This distinguishes it from sibling tools like bucket_create (plain creation) and bucket_publish.

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 a template key from a trusted manifest is available, but does not explicitly say when to use this tool over alternatives like bucket_create or how to prepare the template key. No exclusions or alternatives are mentioned.

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, but the description adds critical behavioral context: the deletion is 'permanent', requires a 'confirmation' step, and applies only to a bucket in a specific state ('archived, unpublished normal'). This goes beyond the raw annotations by describing the operational prerequisites and irreversibility.

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 sentences, front-loaded with the core purpose and followed by a concise parameter sourcing note. Every word earns its place; there is no fluff or repetition of schema details.

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

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

The tool has an output schema, complete parameter schema, and annotations. The description adds the essential preconditions (archived, unpublished, confirmation) and parameter provenance, making the tool's behavior clear enough for an agent. It stops short of detailing potential side-effects (e.g., what happens to associated data), but 'permanently delete' implies irreversibility, which is adequate for this destructive 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 input schema already provides 100% coverage with descriptions for both parameters. The description adds value by telling the agent exactly where to obtain these values ('Get bucket_id and delete.confirmation from bucket_list or bucket_get'), which helps sourcing the correct data. This extra guidance goes beyond the schema's static field descriptions.

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: 'Permanently delete an archived, unpublished normal bucket after confirmation.' It uses a specific verb ('delete'), names the resource ('bucket'), and includes preconditions ('archived, unpublished') that distinguish it from sibling tools like bucket_archive or bucket_unpublish. The phrase 'after confirmation' also signals the deliberate destructive nature.

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 provides clear context for when to use: for permanently deleting a bucket that meets the 'archived, unpublished normal' criteria, and it instructs to get bucket_id and delete.confirmation from bucket_list or bucket_get. However, it does not explicitly enumerate when not to use it or name alternative tools for other cases, though the conditions imply the boundaries.

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 this as read-only, idempotent, and non-destructive. The description adds crucial behavioral detail: secrets are encrypted and never returned—only names and last 4 characters—and variables are public config. This goes beyond the annotations and helps the agent set expectations.

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, each providing necessary information: purpose, variable semantics, secret semantics, and naming convention. 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 an output schema present and read-only annotations, the description covers the important domain distinction between variables and secrets and the naming convention. This is sufficient context for correct use.

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 single parameter bucket_id is fully documented in the schema with type and example (e.g., bkt_...). The description adds no parameter-specific details, and schema coverage is 100%, so 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?

The description opens with 'Read a bucket's integration variables and secrets', giving a specific verb and resource. It clearly distinguishes variables (public, returned in full) from secrets (server-only, masked), which differentiates it from sibling tools like bucket_env_set.

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

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

The description makes clear this is a read-only accessor for integration variables and secrets, implying use when you need to inspect them. It does not explicitly name alternatives like bucket_env_set, so it gets a 4 rather than 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?

The description richly discloses behaviors beyond the annotation hints: variables are PUBLIC and REPLACE the entire set, secrets are SERVER-only, encrypted, never returned, and use patch semantics (empty string deletes, omitted unchanged). It also warns 'Never put a secret value in variables.' This is exemplary behavioral 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?

Four dense sentences convey purpose, preconditions, parameter semantics, and a critical safety warning. Every sentence adds value, and the structure is front-loaded with the primary purpose followed by essential details. 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?

The description is complete for the tool's complexity: it covers permissions, replace-vs-patch semantics, naming conventions, secret handling, and a safety warning. With an output schema present, return values need no explanation. It is fully adequate for an agent to select and invoke this 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?

Although schema coverage is 100%, the description adds essential semantics: variables replaces the full public set (requiring a prior get), secrets is a patch operation with empty-string deletion, and names must be UPPER_SNAKE_CASE. This goes far beyond the schema's basic field type descriptions.

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 tool's function: 'Set a bucket's integration variables and/or secrets.' It identifies the specific verb ('set'), the resource ('bucket's integration variables and/or secrets'), and distinguishes itself from sibling tools like bucket_env_get (which reads rather than writes).

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 provides strong usage context, noting write access is required and explicitly instructing to 'call bucket_env_get first and include the entries you want to keep' to avoid overwriting the public set. It does not explicitly name alternatives or state when not to use the tool, but the guidance is clear and actionable.

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 (no readOnly, idempotent, destructive hints). The description compensates by disclosing that it is not a binary API, does not parse structured data, and can produce invalid JSON. It also explains the lock retry mechanism and error reporting, which are beyond basic annotation coverage.

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, zero filler. The first sentence defines the action and scope, the second covers limitations, exceptions, and lock behavior. 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 tool with 5 parameters (3 required), an output schema, and many siblings, the description covers purpose, limitations, lock handling, and error reporting. It could mention that the file must already exist (implied by 'existing text file') and that bucket_file_write is for creation or overwrite, but overall it is sufficiently 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 coverage is 100%, so the schema already documents all parameters including the newline_before behavior. The description does not add significant new meaning beyond the schema; it restates the file type limitation. Baseline 3 is appropriate since the schema carries the 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 uses a specific verb ('Append UTF-8 text') and resource ('existing text file in a bucket'). It clarifies the scope by listing supported formats (txt, md, csv, jsonl, js/code) and explicitly excludes binary files and CSV/JSON parsing. This distinguishes it from sibling tools like bucket_file_write (overwrite) and bucket_file_read.

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

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

The description clearly states when to use the tool (append to text files) and when not to (binary, CSV, JSON – warns about invalid JSON). It also provides guidance on lock behavior (retry briefly, report error with details). While it does not explicitly name alternative tools, the context is sufficient for an agent to decide.

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 adds valuable behavioral context beyond the annotations: it copies archived sources, never downloads or reuploads bytes, and enforces a writable target requirement. This helps the agent understand side effects, though it does not mention overwrite behavior, metadata preservation, or revision handling.

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 concise, front-loaded sentences. Every clause adds value, and the structure immediately states the action followed by key constraints.

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?

Core behavior is well covered: purpose, destination options, archived support, writability, and server-side nature. An output schema exists, so return values need not be described. Minor gaps remain around conflict behavior, revision comments, and metadata copying, but the description is sufficient for selection and invocation.

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

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

Schema descriptions cover all six parameters (100% coverage), so the baseline is 3. The description adds the high-level 'by storage reference' concept but does not add meaningful parameter-level detail beyond what the schema already provides.

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 the specific verb 'copy' and identifies the resource ('one existing file') and destination ('another path or bucket'), clearly distinguishing it from sibling tools like bucket_file_move or bucket_file_rename. It also notes the capability to copy archived sources, adding precision.

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 provides clear context: it copies by storage reference, can include archived sources, requires a writable target, and performs a server-side byte transfer. However, it does not explicitly name alternatives or state when not to use this tool versus move/rename, so it stops short of a full 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 and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by clarifying this is metadata-only ('without downloading its content') and that it enriches lean identifiers into 'complete file details.' This goes beyond the annotations to explain the tool's non-destructive, metadata-focused 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?

Two sentences, front-loaded with the primary action and key constraints. No filler or redundancy. Every word earns its place, making it highly effective and easy to parse.

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 low complexity (3 params, output schema present, clear annotations), the description is complete. It covers what the tool does, what it does not do (download content), when to use it (to expand lean IDs), and parameter preferences. No critical context is missing for a metadata fetch 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?

The schema provides 100% coverage of the three parameters, so the baseline is 3. The description adds value by indicating that file_id is 'preferred' over path, and by explaining that file_id is a 'lean file_id/version_id' returned by specific write operations. This enriches the parameter understanding beyond the schema's basic descriptions.

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 tool's function: 'Get full metadata for one bucket file by file_id (preferred) or path, without downloading its content.' It specifies the resource (bucket file), the scope (one file), and explicitly distinguishes from content-downloading tools like bucket_file_read. This is a specific verb+resource statement that differentiates 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 provides explicit guidance on when to use this tool: 'Use this to expand the lean file_id/version_id returned by bucket_file_write and bucket_file_write_many into complete file details when needed.' It also implies when not to use it by stating 'without downloading its content,' signaling that content retrieval is out of scope. This clearly directs the agent to appropriate scenarios and alternatives.

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 this as a safe, read-only, idempotent operation. The description adds meaningful extra context: pagination behavior ('omit to return all files for compatibility'), the case-insensitive search behavior, and the name-ordered folder listing with bucket-root handling. This goes beyond the annotation hints and provides a richer behavioral picture.

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 sentences, front-loading the core purpose and quickly covering pagination, search, and folder filtering. Every sentence carries useful information with 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?

With strong annotations (read-only, idempotent, non-destructive), a 100%-documented schema, and an output schema, the description fills the remaining gaps: pagination semantics, search/folder scope, and compatibility behavior. It is fully complete for an AI agent 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?

The input schema already has 100% description coverage for all five parameters, including details like 'up to 500', 'omit to return all files', and 'case-insensitive contains-search'. The tool description largely restates these schema details, so it adds little new semantic value beyond the structured 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 ('List files') and the resource ('Revdoku bucket'), and it distinguishes itself from siblings like bucket_file_get and bucket_file_read by focusing on listing, plus it specifies additional filtering modes (query, folder).

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 on usage: pagination with limit/offset, omitting to return all files, searching by query, and folder filtering. It stops short of explicitly naming alternatives or stating when not to use, but the context is unmistakable and sufficient for proper 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?

Discloses critical behavior beyond annotations: same-bucket creates a rename revision, cross-bucket copies then soft-deletes the source, and no reupload occurs. This clarifies what 'destructive' means and adds reversibility 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 sentences with front-loaded purpose and essential behavioral details. Every sentence adds value with no redundant 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?

Covers the primary behavioral scenarios and source-destination semantics, but doesn't address interactions between optional parameters (target_path vs target_folder). Output schema likely covers return details, so this is adequate.

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 baseline is 3. The description adds negligible parameter meaning beyond the schema, only implicitly clarifying that target_bucket_id omission means same-bucket destination.

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 clearly states the action ('Move one file by storage reference') and distinguishes between same-bucket and cross-bucket behavior, separating it from sibling tools like copy, rename, and reorganize.

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 behavior for same-bucket vs cross-bucket makes the use case clear, but no explicit alternatives are named. It implies when to use move over copy/rename, but lacks explicit 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 declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the text-only constraint and the fact that the file must already be stored in Revdoku, which is useful but not extensive behavioral detail.

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, direct, front-loaded with the core action, and no superfluous 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 tool with full schema descriptions, output schema, and safety annotations, the description is complete. It clarifies the text-only scope and the 'already stored' requirement, leaving no significant ambiguity.

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 covers 100% of parameters with descriptions and examples. The description adds no extra parameter-specific meaning beyond the schema, so 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?

The description clearly states the tool reads a text bucket file and specifies eligible formats (HTML/CSS/JS/JSON/Markdown/etc.), with an explicit exclusion of binary files. However, it does not explicitly distinguish from sibling bucket_file_get, so it misses the top tier.

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 provides clear context: use for already-stored text files, and explicitly excludes binary files, giving a when-not condition. It does not name an alternative tool, but the text-vs-binary boundary is sufficient guidance for most cases.

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

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

Beyond the annotations (which already indicate non-read-only and non-destructive), the description adds meaningful behavioral context: it creates a rename revision and avoids reuploading bytes. This gives the agent insight into the operational effect and efficiency of the operation.

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, well-structured sentence that front-loads the core purpose (rename or move) and follows with key constraints (same-bucket, by blob reference, no reupload). Every phrase earns its place with no 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?

Given the simple single-file rename operation and the presence of an output schema (which covers return values), the description is adequately complete. It clearly scopes to one same-bucket path and explains the revision behavior, though it does not cover edge cases like destination existing or permission requirements.

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 provides complete descriptions for all 4 parameters (100% coverage), so the schema already carries the parameter semantics. The tool description does not add parameter-specific meaning beyond that, and the 'by blob reference' phrase is more about internal behavior than parameter semantics.

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 explicitly states the tool renames or moves one same-bucket file path by blob reference, creating a rename revision without reuploading bytes. This clearly distinguishes it from siblings like bucket_file_copy or bucket_file_move by scoping to same-bucket operations and emphasizing the no-reupload behavior.

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 same-bucket usage and mentions 'without reuploading bytes' as a key characteristic, but it does not explicitly state when to use this tool over alternatives such as bucket_file_move or bucket_file_copy. No exclusion conditions or alternative tool references are provided.

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 adds value beyond annotations by revealing that operations are server-side and avoid downloading/reuploading. Annotations already indicate destructiveness, so the description's additional behavior info (batch, no data transfer) earns a solid score.

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, no wasted words, front-loaded with the core action. 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?

Given the output schema exists, return value details are not needed. The description covers the main purpose, usage scenario, and key behavioral trait. Minor ommission: no mention of operation atomicity or failure handling, but these are not essential for agent selection.

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 100% schema description coverage, the baseline is 3. The description does not elaborate on parameters, but the schema already documents all fields adequately, so no additional value is provided.

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 it performs batch rename, move, or copy operations using server-side references, distinguishing it from single-file siblings like bucket_file_rename. The verb+resource combination is specific and 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 explicitly targets 'folder cleanup or reorganization' and highlights the benefit of avoiding byte transfer. While it doesn't name alternatives, the context of siblings makes the intended use case clear.

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

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

Annotations indicate this is not read-only, not idempotent, and not destructive. The description expands on the behavioral profile: it mentions the BUCKET_REVISION_CONFLICT error for stale expected_bucket_revision_id, notes that JavaScript is served as-is (no transpilation), and explains the response includes a dashboard_url (and public_url) for the user to see. Minor gap: does not explicitly state whether the tool overwrites existing content or only creates new.

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 5 sentences covering all critical aspects without being verbose. It front-loads the primary purpose and then adds context for usage, alternatives, and output. Could be slightly more streamlined by removing 'show that link to the user' instruction (a UX directive rather than tool behavior), but still 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 the tool has an output schema, it's not required to describe return values. The description covers the main workflow request/response cycle, error conditions, and integration tips. However, it omits the return format of the bucket object and does not explain what happens when content_type is omitted (auto-detection?). For 7 parameters and a write operation, this is a comprehensive but not exhaustive treatment.

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%, meaning every parameter already has a description in the schema. The tool description provides no additional detail about any parameter beyond what the schema already states. Baseline 3 is appropriate since the schema does the full 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 clearly states the tool writes or replaces one TEXT file in a bucket, listing supported formats (HTML/CSS/JS/JSON/SVG/Markdown/etc.). This specific verb+resource combination distinguishes it from siblings like bucket_file_append_text, bucket_file_write_many, and bucket_file_copy.

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 tells when to use this tool (writing individual text files) and when NOT to (binary assets via CLI or REST, whole local folders via CLI). Even provides project-specific workflow guidance for Wbuilder buckets (read AGENTS.md, edit data/**, leave _config/** read-only). Additionally, clarifies the relationship with bucket_file_read and bucket_get.

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?

Elaborates beyond annotations (destructiveHint: true) with details: save-time validation, Preview compilation, soft-deletion for delete_missing, and response fields (dashboard_url, public_url). No contradiction 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?

A single paragraph of ~120 words, front-loaded with purpose. It is efficient but could be broken into bullet points for clarity. Still, every sentence adds value 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?

Complete for a multi-file write tool: covers purpose, constraints (text-only), usage guidelines, behavioral details, and response hints. With an output schema and 5 parameters, the description addresses all key aspects an agent needs 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining expected_bucket_revision_id's concurrency role, delete_missing's preservation of managed/generated files, and the text-only nature of content. This improves agent understanding 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 clearly states the tool writes multiple TEXT website files in one bucket edit, distinguishing it from siblings like bucket_file_write (single file) and binary asset uploads (CLI/REST). The verb 'write' and resource 'multiple text files in a bucket' are explicit.

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

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

Provides explicit guidance: read AGENTS.md for Wbuilder, edit data/**, leave _config/** read-only, pass expected_bucket_revision_id, and use CLI/REST for binary assets. It also explains delete_missing behavior and when to use alternatives.

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, idempotentHint: true, destructiveHint: false. The description adds further behavioral context: include_form_submissions requires write-capable access, pagination behavior is explained, and the minimap structure is described. 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?

The description is quite dense and front-loaded with the main purpose, but contains multiple details that could be more concise or structured for easier scanning. For example, the minimap description and deep link guidance add length. An average score is appropriate because while informative, it is not the most concise.

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 6 parameters, an output schema, and annotations, the description is thorough. It covers pagination, special parameter effects, required access levels, and provides context for the returned data structure. No gaps are evident for an AI agent to correctly invoke the 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 coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that file_limit/file_offset paginate bucket.files, that include_form_submissions requires write access, and detailing the minimap and deep links for sharing submissions and GitHub sync. This adds value over the raw parameter descriptions.

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 explicitly lists all the data the tool retrieves: one bucket, its files, website type/revision, path permissions, website state, GitHub sync status, and archive/delete guidance. This is a specific verb+resource combination that clearly distinguishes bucket_get from siblings like bucket_list (which lists all buckets) or bucket_file_get (which gets a single file).

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 provides guidance on when to use pagination parameters (file_limit/file_offset) and the include_form_submissions flag. It also advises reading AGENTS.md and _config/wbuilder/contract.json before editing for Wbuilder buckets. However, it does not explicitly state when not to use this tool or suggest alternative tools for other tasks, though sibling tools make the distinctions clear.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds value by listing what is returned (state, sync status, links, guidance) and confirming the read-only listing behavior. However, it does not explain any potential performance implications (e.g., pagination, rate limits for 'visible' buckets), which would enhance transparency further. A score of 3 is justified because annotations do the heavy lifting.

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 sentences with zero filler. The first sentence front-loads the core purpose and output contents. The second sentence adds the usage guideline and parameter hint. Every clause earns its place, and the structure is optimal for quick agent parsing.

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

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

Given the tool's simplicity (1 optional parameter, no enums, read-only with full annotation coverage, and an output schema that describes return structure), the description is complete. It covers what is listed, why to use it first, and how to filter. There is no need for additional detail on return types since the output schema handles that. The description perfectly complements the structured fields.

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 meaningful value by explaining that the query parameter is a 'case-insensitive contains-filter on bucket title,' which goes beyond the schema's generic 'Optional ... filter' phrasing. This clarifies the matching behavior (contains, not exact) and the case insensitivity, making it easier for the agent to craft effective queries.

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 specifies a clear verb ('List') and resource ('visible Revdoku buckets'), and enumerates what information is returned (website state, GitHub sync status/setup links, archive/delete guidance). It also distinguishes itself from 40+ siblings by stating its purpose as a prelude to follow-up bucket actions and offering a query filter, which none of the sibling names imply.

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 to use this tool 'before follow-up bucket actions,' providing a clear when-to-use directive. It also mentions the optional query parameter for filtering by title, which helps the agent decide on parameter usage. The guideline is specific and practical, given the large sibling set focused on individual bucket operations.

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 must carry the behavioral burden. It hints at a mutating, non-readonly action (locking) and explains the purpose (visibility to others), but it does not disclose important behavioral traits such as whether the lock is exclusive, what happens if the bucket is already locked, or how the duration_seconds parameter affects the lock. The description provides some context but lacks depth for a locking operation.

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 of 18 words, front-loading the action and purpose. Every word is necessary, and there is no redundancy or extraneous information. It is optimally concise.

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 has 3 parameters and an output schema, the description covers the basic purpose and usage context. It omits some details about the locking mechanism (e.g., that bucket_unlock can release it), but the presence of an output schema reduces the need to describe return values. Overall, it is reasonably complete for a straightforward locking 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 baseline is 3. The description does not add any additional meaning to the parameters beyond what the schema already provides. For example, 'duration_seconds' and 'message' are not elaborated upon in the 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 clearly states the action 'Lock a whole bucket' and distinguishes it from siblings like bucket_lock_files by specifying the scope 'whole bucket'. It also provides context about when to use it ('before broad edits or uploads') and why ('so other agents can see this connector is working'), making the purpose highly specific and 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 explicitly says 'before broad edits or uploads' and explains the benefit of visibility to other agents, giving clear context for appropriate use. However, it does not mention when not to use this tool or present alternatives such as bucket_lock_files for locking individual files, which would be helpful given the many sibling 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 are all false and provide no safety profile. The description adds that other agents can see the connector is working, but fails to disclose side effects, reversibility, or required permissions. For a mutating lock operation, this is insufficient.

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 is front-loaded with the action and object. It is concise and every phrase contributes meaning, though the rationale 'so other agents can see this connector is working' is slightly vague.

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 has 4 parameters and an output schema, the description provides minimal context. It does not mention lock duration, how to unlock, or what happens if files are already locked. The required/optional mismatch for 'message' also creates ambiguity. This is incomplete for a mutating tool with no annotation support.

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 parameters are already well-documented. The description does not add parameter-specific meaning beyond stating 'bucket files', so 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?

The description clearly states the tool locks one or more bucket files, which is a specific verb+resource. It implicitly distinguishes from 'bucket_lock' by focusing on files, but doesn't explicitly name sibling alternatives.

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

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

Provides context 'before editing', implying when to use it. However, it does not offer exclusions or alternatives, despite siblings like bucket_lock and bucket_unlock_file that could be confused.

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

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

Beyond annotations (idempotentHint=true), the description adds that locking is idempotent, lists the specific operations that become locked, and crucially discloses that there is no unlock tool and that unlocking is web-UI-only requiring user confirmation. This provides full behavioral transparency for a safety-critical operation.

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 serving a distinct purpose: action + usage, idempotency, and unlock limitation. No redundancy, and critical information is front-loaded. 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?

Given the operation's complexity (locking with irreversible consequences from the tool's perspective), the description fully covers purpose, effect, idempotency, and the unlock procedure. The presence of an output schema is not needed for this tool's understanding. The description is complete enough for an agent to use the tool correctly and safely.

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?

There is only one parameter (bucket_id) with a clear schema description. The tool description does not add additional parameter semantics, but schema coverage is 100%, so the baseline of 3 is appropriate. The description's context about the lock operation is helpful but not about the parameter itself.

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 specifies the verb 'lock', the resource 'bucket's visibility', and details exactly which operations are prevented (publish, unpublish, switch public/password access, change public URL). This clearly distinguishes it from sibling tools like bucket_lock_files or bucket_lock.

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: 'to protect a bucket holding private data from accidental publishing.' Also describes the irreversible nature by noting there is no unlock tool and that unlocking requires user action in the web UI, guiding the agent to ask the user for help rather than attempting an unlock.

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 readOnly/idempotent/non-destructive; the description goes far beyond by explaining timezone handling, retention windows, bot inclusion/exclusion, null-vs-zero semantics, plan-dependent detail levels, and truncation flags. No contradiction 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?

The first sentence front-loads the core purpose and identifier options, and every subsequent sentence adds non-obvious decision-relevant detail such as retention limits, previous_period null behavior, and plan differences. It is dense but not redundant; the length is proportional to the tool's complexity.

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 complexity, the description is unusually complete: it covers calling conventions, timezone/date behavior, plan tiers, retention, bot filtering, uniqueness semantics, truncation flags, and content-type definitions. The output schema further covers return structure, so nothing needed for correct selection or invocation appears 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?

Input schema covers all parameters, so baseline is 3, but the description adds real value: it explains the live/daily distinction for range values, the inclusive from/to pairing, and which prior calls produce valid publication_id values. This is above baseline, though the schema already documents the basic parameter shapes.

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 action ('Get ... analytics') and resource ('bucket website's analytics'), and shows two identifier routes (bucket_id or publication_id). The description clearly separates it from sibling get/list tools by focusing on analytics, so an agent can tell it apart 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?

Gives clear invocation context: use bucket_id or supply publication_id from bucket_get, bucket_publish, or bucket_publication_list. It does not explicitly list when-not-to-use or name alternative analytics tools, but the identifier provenance and window semantics make selection unambiguous.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description 'Get one bucket website publication' is consistent with these annotations and adds no additional behavioral context (e.g., what the response contains or any rate limits). With annotations present, the bar is lower, and the description doesn't contradict them, but it contributes nothing 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?

The description is a single, concise sentence that communicates the core function without waste. It is front-loaded and easy to scan, satisfying conciseness requirements.

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 single-get tool with a strong output schema and full annotation coverage, the description is adequate. It could mention what a 'website publication' is or what fields are returned, but the presence of an output schema reduces that need. The main gap is the lack of any note about error conditions or how this relates to other publication tools, but the tool is simple enough that a 4 is justified.

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 the sole parameter publication_id is well-described in the schema as 'Website publication id returned by bucket_publish, bucket_publication_list, or bucket_get.' The tool description itself does not add parameter semantics, but since the schema fully covers it, a baseline score of 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?

The description 'Get one bucket website publication' uses a specific verb (get) and resource (one bucket website publication), clearly distinguishing it from sibling tools like bucket_publication_list (which lists multiple) and bucket_publish. The word 'one' signals a single-object retrieval, which matches the required publication_id parameter.

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 minimal usage guidance. It doesn't explicitly state when to use this tool vs alternatives, but the parameter description 'returned by bucket_publish, bucket_publication_list, or bucket_get' implies you need a prior call to obtain the publication_id. No explicit exclusions or comparisons to similar tools are provided, but the read-only get-by-ID pattern is inferable.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavior beyond annotations by flagging that emails are sensitive and that an account-owner connector with publish permission and write access is required, which is important context for invocation.

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 sentences with no filler. The action and scope are front-loaded, the output contents are summarized compactly, and the permission note earns its place because it is essential for correctly invoking the tool.

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 is complete for a read-only list tool: it covers purpose, scope, included data, use case, and access requirements. An output schema exists, so return values do not need to be described. It slightly falls short of a 5 by not explicitly steering the agent toward or away from sibling analytics tools, but 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 description coverage is 100%, so both limit and publication_id are already documented. The description adds context like 'for one publication' but does not provide significant new meaning beyond the schema's parameter descriptions, so the baseline score of 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?

The description opens with a specific verb and resource: 'List visitor leads for one publication.' It enumerates exactly what is included—verified and unverified emails, visit timing, visit count, per-path activity, and recent access sessions—so the agent can distinguish it from related publication tools without opening their schemas.

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

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

The description provides a clear use case: 'Use this to follow up without opening the Revdoku dashboard.' It gives contextual guidance but does not explicitly name alternatives or state when not to use this tool, though sibling names such as bucket_publication_analytics are available for the agent to consider.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful scoping note about "visible to this MCP connector" and "active and historical," but it doesn't describe pagination, error behavior, or edge cases such as invalid bucket_id.

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, tightly worded sentence that starts with the action and clearly defines the scope. Every word earns its place, with no filler or repetition.

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 a full output schema, rich annotations (read-only, idempotent, non-destructive), and a single well-documented optional parameter, the description sufficiently covers the tool's behavior. Additional details like pagination are likely handled by the output schema, so no major gaps remain.

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

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

The only parameter, bucket_id, is fully documented in the schema with its source and format ("returned by bucket_list or bucket_get, for example bkt_"). The description adds no additional parameter semantics, so the baseline of 3 applies given 100% schema description 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?

The description uses the specific verb "List" and clearly identifies the resource as "bucket website publications" with the scope "active and historical." This distinguishes it from siblings like bucket_publication_get or bucket_publication_analytics, which target specific publications or analytics.

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 provides clear context by specifying that it lists both active and historical publications visible to the MCP connector. However, it doesn't explicitly name alternatives or state when not to use it, though the sibling tool list implies distinct use cases.

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 richly discloses behaviors beyond annotations: recreating invalidates previous URLs, removes access on allowlist removal, shares quota, requires specific permissions, and warns against public sharing. This is valuable context that annotations (all false) do not convey.

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 bit long but every sentence adds critical information—purpose, behavioral effects, permissions, quota, and security. It is front-loaded with the core action and well-structured, though slightly dense.

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 complexity (permissions, revocation, quota, security), the description covers all key operational aspects. It doesn't specify the return value, but since there is no output schema, the description could be slightly more explicit about what the API returns; however, the omission is acceptable for a create 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful nuance: 'Pass emails for a subset' clarifies that parameter, and 'Defaults to allowlisted addresses' clarifies omission behavior. This extra context justifies a 4.

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 tool's purpose with a specific verb ('Create') and resource ('personal links for a Require Email website'). It distinguishes itself from siblings by explaining the unique OTP-free access and tracking link integration, making it 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?

Provides clear context for when to use the tool—for creating per-person links for Require Email publications. It explains default behaviors, how to subset via emails, and security constraints. While it doesn't explicitly name alternative tools, the context is sufficient, and no direct alternatives exist among 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 flag this as destructive/non-read-only, and the description adds needed behavioral detail: the operation is asynchronous, it can fail with BUCKET_VISIBILITY_CHANGE_LOCKED on first publish or access-mode change, unlocking is web-UI-only, and published content is subject to the AUP. It also warns not to confirm liveness without checking publish_state.

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 main purpose is front-loaded in the first sentence, and each subsequent sentence carries operational value rather than filler. It is long because the tool genuinely has multiple preconditions and alternatives, but the block is dense and well-organized. The AUP sentence is slightly generic.

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 async publish tool, the description covers the workflow, safety checks, alternative routing, failure modes, remediation, and policy context. With a rich output schema and 100% parameter schema coverage, there is no material missing information an agent needs 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 description coverage is 100%, so the input schema carries the parameter documentation burden. The description adds minimal extra parameter meaning beyond the schema, e.g., 'Pass description when the user wants Revdoku to save explanatory bucket text before publishing,' which is a modest trigger condition rather than substantial new semantics.

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

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

The description opens with a specific verb and resource: 'Queue an async publish or republish of the bucket's saved draft as a live public website.' It also differentiates itself from sibling tools by routing preview and password-protected publishing elsewhere, so an agent can distinguish bucket_publish from bucket_publish_preview and bucket_publish_password_protected.

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 decision rules: use bucket_publish_preview first unless the user has reviewed the site or explicitly asks for immediate publishing; use bucket_publish_password_protected for protected/password/private websites; and check bucket_publication_get before reporting the site is live. This is clear when-to-use and when-not-to-use 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?

Beyond annotations, the description discloses key behaviors: publishing is async, PUBLICATION_UPGRADE_REQUIRED is a possible failure, BUCKET_VISIBILITY_CHANGE_LOCKED occurs when visibility is locked, unlocking is web-UI-only, password generation returns copyable text to authorized owner publish keys, and Require Email uses OTP with optional allowlist. These details are highly valuable and do not contradict 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?

The description is longer than typical, but it is dense and front-loaded with the primary purpose before branching into upgrade handling, error cases, mode differences, and safety guidance. It could be more structured with separated guidance, but every sentence contributes useful operational context for a complex tool.

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 15-parameter schema and existing output schema, the description covers the critical operational context an agent needs: async queuing, upgrade fallback path, failure modes, mode-specific behavior, security restrictions, and follow-up recommendations. Nothing essential for correct invocation 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 baseline is 3. The description adds meaning for access_mode and password: Password mode auto-generates passwords and returns copyable share text, while Require Email verifies by OTP and supports an allowlist. It also clarifies security constraints like never putting passwords in URLs, which is not fully captured 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?

The description opens with a specific verb and resource: 'Queue an async publish or republish of the bucket's saved draft with Password or Require Email access.' It clearly distinguishes itself from related siblings such as bucket_publish_preview and bucket_publish, and names the lock-visibility sibling explicitly.

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 instructions: preview with protected access first, share the preview and error.details.upgrade_url if PUBLICATION_UPGRADE_REQUIRED, retry only after upgrade, and never silently fall back to Public. It also names bucket_lock_visibility_changes as a follow-up option, providing clear 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?

Adds substantial behavioral detail beyond annotations: async execution, 15-minute expiry, re-run republishing to same slug, noindex/no-impact/no-limit guarantees, and explicit pointer to bucket_publication_get for status. This is exactly the kind of side-effect documentation needed.

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 focused sentences, each carrying a distinct piece of information: action, expiry, free-tier evaluation benefits, re-run behavior, and follow-up steps. No redundancy; the most important action is front-loaded.

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?

Covers the full async workflow (queue, monitor via bucket_publication_get, share URL/password/expiry) and addresses open-world side effects (no index, no impact, no limits). Output schema handles return values, so description is complete for invocation.

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

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

Schema already describes 100% of parameters, so description doesn't need to iterate them. It adds a small semantic link by mentioning password/require_email as paid settings evaluated via preview, but this is marginal and doesn't go beyond schema descriptions.

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 specifies a clear action ('Queue an async PREVIEW publish') with a distinct resource ('current saved draft' to 'preview-<slug> URL'). It differentiates from siblings like bucket_publish and website_preview_create by emphasizing the temporary, async, preview-specific nature.

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

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

Provides clear usage context: previews expire in 15 minutes, allow evaluating paid settings on Free, stay noindex, and don't affect the main site. Does not explicitly name alternatives or state when NOT to use this tool, so it stops 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?

Description discloses republish behavior for live sites, saved URL changes for unpublished sites, and the BUCKET_VISIBILITY_CHANGE_LOCKED error – all beyond the annotations' basic flags. This gives the agent concrete expectations about side effects and 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 sentences convey plan restriction, action, conditional behavior, and error condition with no filler. First sentence front-loads the most critical constraint.

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 2-parameter schema and output schema, the description covers essential context: eligibility, behavior in both states, and an error case. The tool is simple enough that no additional details are required.

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 descriptions already cover both parameters (bucket_id format and public_slug rules), so the description adds no extra parameter info. With 100% schema coverage, no compensation is needed.

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 states 'rename an existing website publication's <slug>.revdoku.site URL' – a specific verb and resource, clearly distinguishing from sibling tools like bucket_publish or bucket_update. The paid-only prerequisite is also front-loaded.

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?

Mentions 'Paid plans only' and 'Free websites retain their randomized URL', providing an explicit condition for use. However, it doesn't name alternative tools or explicitly say when not to use other bucket_* tools, so it falls short of full alternative 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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false) fully cover the safety profile. The description adds domain-specific context about the templates being 'trusted' and suitable for import into a new private bucket, which helps agent selection.

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 redundant information; it states the verb, object, and qualifier 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 zero-parameter read-only list tool with an output schema, the description provides enough context about what is listed and the purpose. No additional details are necessary.

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 empty schema is fully described. The description doesn't need to explain parameters, and the baseline for zero-param tools is 4.

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 defines the action ('List') and the specific resource ('trusted Revdoku bucket templates') and adds the purpose (importable into a new private bucket), distinguishing it from sibling tools like bucket_list and bucket_create_from_template.

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 the use case of discovering available templates before creating a bucket from a template, but it does not explicitly contrast with alternatives or state when not to use it. However, the context is clear for a simple list operation.

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 indicate destructiveHint false (non-destructive), readOnlyHint false (write operation), and idempotentHint false (not idempotent). The description adds the key behavioral trait: this is a state-changing operation (restores a bucket) but not destructive. Since annotations already hint at safety (destructiveHint false), the description's added value is modest. It does not detail failure modes (e.g., what if bucket is already active?), side effects, or permission requirements. With existing annotation coverage, a score of 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 of 11 words that conveys the full purpose. There is zero fluff, no repetition, and it front-loads the key action ('Restore'). Perfectly concise and structurally 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?

The tool has 1 parameter with 100% schema coverage, a clear annotation set, and an output schema (not shown). The description is sufficient for a simple restoration operation. However, it lacks context about what happens if the bucket is already active (idempotency not guaranteed), confirmation of success criteria (does it return the bucket object?), or how to know which buckets are eligible for unarchiving. For a state-changing operation, a bit more context would improve completeness. Score 3 reflects adequate but not comprehensive 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 description coverage is 100% for the single parameter (bucket_id), and the schema already states the format ('Revdoku bucket id returned by bucket_list or bucket_get, for example bkt_...'). The description does not add any further semantics about the parameter beyond what the schema provides. Therefore, the baseline score of 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?

The description clearly states the verb ('Restore'), the direct object ('an archived bucket'), and the target state ('back to the active bucket list'). It effectively distinguishes itself from sibling tools like bucket_archive (which does the reverse). The only slight gap is not naming the exact resource type (Revdoku bucket) explicitly in the description, but the title and schema make it clear.

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 that this tool is the inverse of bucket_archive (by 'back to the active bucket list'), and from the sibling list one can infer when to use this vs bucket_archive or other mutating tools. However, there is no explicit guidance on when to use this tool (e.g., 'use when you need to reverse an archive operation'), nor are any prerequisites (e.g., only works on archived buckets) or alternatives mentioned directly. The context is clear but not 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 already indicate idempotentHint=true (safe to retry) and destructiveHint=false (not destructive). The description adds the scoping detail 'locked by this MCP connector', but does not disclose behavior like response when the bucket is not locked or any side effects. With annotations providing the core safety profile, the description adds limited extra value.

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

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

The description is a single sentence that directly states the purpose. No filler or redundant information. Every word earns its place.

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

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

Given the simplicity of the tool (one parameter, idempotent, not destructive) and the presence of an output schema (signaled), the description is largely sufficient. It identifies the key constraint (bucket must be locked by this connector) but could briefly mention the condition under which unlock fails.

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 only parameter 'bucket_id' has a clear description in the schema. The tool description does not add any additional meaning beyond what the schema already provides, so 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?

The description clearly states the action 'unlock' and the resource 'bucket', and specifies that it applies to buckets locked by this MCP connector. This distinguishes it from siblings like 'bucket_lock' and 'bucket_unlock_file'.

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 implicitly tells when to use this tool (to unlock a bucket locked by this connector), but it does not explicitly state when not to use it or mention alternatives. A brief mention of prerequisites would improve clarity.

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, destructiveHint, idempotentHint, and openWorldHint, covering safety and side effects. The description adds value by scoping to connector-created locks, but does not describe behavior for already-unlocked files or return details.

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 sentence that is immediately informative and contains no redundant words. It earns its place by stating the core action and scope.

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 2-parameter tool with output schema and comprehensive annotations, the description covers the essential behavior. It lacks explicit failure-mode info, but does not need much more given the available structured metadata.

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%, with both bucket_id and path having meaningful descriptions and examples. The tool description does not add parameter-level detail, so the baseline score of 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?

The description uses the specific verb 'Unlock' targeting 'a bucket file', and clarifies the scope with 'locked by this MCP connector'. This distinguishes it clearly from sibling tools like bucket_unlock (whole bucket) and bucket_lock_files (multiple files).

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 phrase 'locked by this MCP connector' provides clear context on when the tool applies, implicitly excluding locks from other sources. However, it does not explicitly mention alternatives like bucket_unlock for whole-bucket locks.

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 adds substantial behavioral context beyond the annotations (destructiveHint=true): it explains async nature, that the reserved URL is kept, and specifies the exact error code (BUCKET_VISIBILITY_CHANGE_LOCKED) and its resolution (web-UI unlock, ask user). This goes well beyond what annotations alone convey.

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 sentences, front-loaded with the main action, followed by usage conditions and error handling. Every sentence delivers essential information without redundancy or padding. It is concise yet comprehensive for a tool with async behavior and error states.

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 complexity (async workflow, error condition, dependency on bucket_list and bucket_publication_get), the description fully covers usage context, prerequisites, and error handling. The existence of an output schema means return values don't need explanation. The description is complete for selecting and invoking this 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 input schema has 100% coverage with a description for bucket_id, so the baseline is 3. The description does not add new parameter-specific semantics, but it does reference the parameter indirectly through context (e.g., 'bucket_list says required_action'). No score above baseline is warranted since the schema already handles parameter documentation.

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 primary function: 'Queue an async unpublish of a bucket website while keeping the reserved URL.' The verb 'unpublish' is specific, the resource is identified, and the 'async' and 'keeping the reserved URL' details distinguish it from sibling tools like bucket_publish or bucket_delete_permanently.

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 guidance is provided: 'Use before archive/delete when bucket_list says required_action is unpublish_first, then check bucket_publication_get separately until status is unpublished before archiving or deleting.' This gives a clear when-to-use condition and workflow, and the failure mode (visibility locked) with user action further clarifies appropriate usage.

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 this as non-read-only and non-destructive, so the bar for additional disclosure is lower. The description adds meaningful behavior beyond the annotations: searchability defaults and lock-offs for protected/preview sites, the macro-based form selection rule, and the crucial draft-until-publish/republish behavior. This gives the agent a realistic model 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?

The description is dense but not bloated; the first sentence captures the core purpose and the following sentences add high-value behavioral nuance about searchability, form loading, and draft semantics. Given the complex nested form configuration, the length is justified and 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?

The tool has a rich nested schema and an output schema, so return-value documentation is unnecessary. The description covers the headline update operation, the most complex sub-resource (publication_forms), and the draft/publish lifecycle. It could still be more explicit about whether omitted fields are preserved or reset, but overall the agent has enough to invoke the tool deliberately.

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 in detail. The description adds useful context such as 'affirmative' search indexing and form plan restrictions, but it mostly summarizes information already present in the schema rather than introducing meaning the schema lacks. The baseline score of 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?

The description opens with a specific verb and resource: 'Update bucket title, description, metadata, or the affirmative allow_search_indexing setting.' This precisely identifies what the tool changes and separates it from publication-specific siblings like bucket_update_publication_access. The additional form-configuration detail reinforces that this is the general bucket-update entry point.

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 operational context, especially that form instances are configured through metadata.publication_forms, that plan restrictions apply, and that form changes remain drafts until publish/republish. It does not explicitly name alternatives or say when not to use this tool, but the context is strong enough for an agent to infer when this tool applies.

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 provide readOnlyHint=false, destructiveHint=false, but description goes far beyond by explaining performance implications (instant vs re-keying), that the site stays live, the BUCKET_VISIBILITY_CHANGE_LOCKED error, and that unlocking is web-UI-only. It also adds safety context about never putting passwords in URLs. No contradiction 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?

The description is dense but every sentence earns its place: core purpose, mode-switching semantics, timing differences, alternative tools, password safety, and error handling. The main verb and resource are front-loaded in the first sentence, and the length is justified by the tool's complexity.

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 7 parameters, mutating nature, and output schema, the description covers all critical aspects: what it changes, what stays unchanged, performance implications, failure mode, usage boundaries, and security. It is complete enough for an agent to select and invoke correctly without additional context.

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 already has 100% parameter documentation, so baseline is 3. The description adds meaningful nuance: omitting password keeps current, regenerate_password rotates it, switching public<->protected triggers re-keying, and passwords must never go in URLs. This supplements the schema without redundancy.

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 clearly states the tool changes access settings on an already-published website without republishing files or URL, and lists the specific modes (public, password, Require Email). It distinguishes itself from sibling publish tools by explicitly noting this is not for publishing new file 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?

Provides explicit when-to-use guidance (switching access modes or rotating password on a live site), and explicitly directs to bucket_publish / bucket_publish_password_protected for publishing new versions. Also covers the locked-visibility edge case with instructions to ask the user, giving clear 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 declare readOnly, idempotent, non-destructive hints. The description adds a meaningful behavioral detail: 'The link never signs a browser in; the user authenticates normally if needed.' This goes beyond annotation hints and helps set expectations for the link's behavior.

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

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

The description is two sentences, concise, and front-loaded with the core purpose. Every word earns its place, with 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?

Given the tool's simplicity (one optional parameter, output schema present, strong annotations), the description adequately covers purpose and key behavioral nuance. The output schema handles return value details, so no additional return information is needed.

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 provides 100% coverage for the single parameter (redirect_path) with examples. The description's mention of 'buckets, websites, or connector access' loosely aligns with parameter values but doesn't add substantive meaning beyond the schema. Baseline of 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?

The description clearly states it 'Return a stable Revdoku dashboard link' for specific targets (buckets, websites, connector access), using a specific verb 'return' and resource 'dashboard link'. This distinguishes it from sibling tools that manage buckets, files, publications, etc.

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 provides clear context for when to use the tool (when a dashboard link is needed) and its scope (buckets, websites, connector access). It doesn't explicitly mention alternatives or exclusions, but the context is unambiguous enough that an agent can infer appropriate usage.

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 goes far beyond the readOnlyHint and idempotentHint annotations, explaining what the tool actually reports and how the agent should behave in edge cases. It explicitly instructs the agent not to retry when account restriction reports moderation, when to offer suggested projects, and when to follow recommended next steps instead of attempting disallowed bucket creation. This gives the agent safety-relevant behavior that annotations alone do not convey.

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

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

The description is long, but it is dense with actionable information and organized around meaningful conditionals: account.restriction, onboarding.state, free_plan, and connector health. Each sentence carries operational value, though a lighter structure with section breaks or explicit bullets would make it easier to scan. It is still well front-loaded with the overall purpose.

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 scope, the description covers what the tool returns, how to interpret key states, when to involve the user, and how to recover if tools are missing. The presence of an output schema reduces the need to exhaustively document return values, but this description also documents the important behavioral consequences of reading the status. No significant gap is left for an agent to stumble into.

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

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

The tool has no input properties, so parameter selection is not a challenge. The description does not clutter parameter meanings, and there is no schema gap to compensate for. This matches the 0-parameter baseline of 4.

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

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

The description opens with a specific verb and resource: 'Check the authenticated Revdoku account and remote MCP capabilities.' It goes on to name the exact data areas inspected, including onboarding, publishing, restrictions, and server version. This distinguishes revdoku_status from the many bucket and website preview 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 provides clear situational context: check account state, capabilities, and whether the connector is functioning. It also gives conditional guidance for empty_account, no_visible_buckets, and missing tools, which tells the agent what to do after calling this tool. It does not explicitly contrast this tool with sibling tools, but the read-only account-level status role is clear 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?

Annotations already signal non-readOnly, open-world, non-idempotent, non-destructive, so the bar is lower. The description adds critical behavioral context: expiration in 24 hours, password protection genuinely protects, form Send is mock, claim ownership does not activate features, URL is randomized, no stored submissions/contacts/analytics. This is exactly the kind of context that prevents an agent from making false assumptions about a generator/preview tool.

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

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

The description is a single dense paragraph with multiple distinct clauses; it is not minimal, but it earns each sentence by adding operational rules. The most important behavioral trait (expiration, anonymous) is front-loaded. It could be split into separate behavior and session-tracking sections for readability, but it remains concise and scannable enough for an agent.

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?

An output schema exists, so return values do not need to be described. The description fully covers the tool's scoped behavior, limitations, session-tracking requirement, and user-communication rules. For a complex lifecycle tool with open-world and idempotency annotations, this is complete and leaves no obvious procedural gap.

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 most parameters already have descriptive labels and enums. The description adds practical parameter-level meaning by explaining the generated password, never-ask-for-password rule, and the form preset behavior that maps to form_preset. It does not redundantly recite the schema, and it enriches the semantic context.

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

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

The description opens with a specific verb and resource: 'Create one anonymous website preview that expires in 24 hours.' It also enumerates functional boundaries (public/password access, one built-in form) and clarifies the intended user-facing outputs. This strongly distinguishes it from siblings like website_preview_update and bucket_publish_preview.

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

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

The description gives explicit when-to-use guidance, including the session-level rule about tracking distinct ready preview IDs and the messaging to surface on second creation. It also states what the agent must never ask for (link name, password) and explicitly explains that Send is a mock and claimed previews require republishing. This goes beyond a vague 'when to use' and provides direct operational guardrails.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable stateful semantics: republish_required stays true until the claimed bucket is successfully republished, the connection token is one-time, and local vs hosted clients have different post-claim flows. This goes well beyond annotation data.

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 dense, purposeful sentences with no filler. The first sentence states purpose, the second captures the key stateful behavior, and the third provides an important operational warning about token handling and sign-up. 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 two-parameter, read-only status tool with an output schema, the description covers prerequisites, state semantics, and post-claim workflows well. The only minor gap is that the 'authenticated Revdoku tool' for hosted clients is not explicitly named, leaving a small ambiguity in the workflow guidance.

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%, but the schema descriptions are only 'Value for preview id' and 'Value for update token' — placeholders. The description adds useful meaning by calling the preview 'anonymous' and the update token 'opaque', but it does not provide format, constraints, or additional parameter context 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?

The description opens with a specific verb ('Check') and names the exact resource: an anonymous preview's publish or claim status, using preview id and opaque update token. This clearly separates the tool from preview create/update and bucket publish 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 clearly states when the tool applies — checking status via preview_id and update_token — and gives useful post-claim context about token exchange and hosted-client behavior. It does not explicitly name sibling alternatives or exclusion cases, but the use case is clear 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?

Annotations already indicate destructive and idempotent behavior, and the description adds valuable detail: all files are replaced, the URL and expiry are preserved, and omitted settings remain unchanged. This gives the agent a clear model of side effects with no contradiction against 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?

Two information-dense sentences contain the action, constraints, preserved invariants, and required credential without filler. The most important behavior is front-loaded.

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 6-parameter mutation with annotations and an output schema, the description covers prerequisites, scope, side effects, and preservation semantics. The only notable gap is that the schema requires files even for settings-only changes, and the description's 'Replace all files or change settings' phrasing could mislead an agent into thinking files are optional for a settings-only update.

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 meaningful parameter context: update_token provenance, the semantics of omitted optional settings, and that files are a full replacement set. It does not enumerate enum values, but the schema already covers those.

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 precise operations: replace all files or change access/mock-form settings on an unclaimed anonymous website preview. It also names preserved invariants (randomized URL and 24-hour expiry), clearly distinguishing this tool from website_preview_create and website_preview_status.

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

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

The description makes the prerequisite explicit: the agent must have the opaque update token returned by website_preview_create. It does not enumerate exclusions versus siblings, but the unclaimed-preview scope and token requirement provide enough context for correct selection.

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