Revdoku

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

Annotations already indicate this is not read-only and not idempotent; the description adds a meaningful behavioral prerequisite about unpublishing active websites. It does not, however, disclose whether archiving is reversible, what happens to the bucket's contents, or any side effects on publication, which would be valuable given the destructiveHint is false but not explanatory.

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 short sentences with no filler. The core action is stated first, and the key prerequisite follows, making it highly efficient and well-structured.

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 two parameters, an output schema, and existing annotations, the description covers the main prerequisite and is mostly complete. It would be slightly better to mention that bucket_unarchive can reverse the action or clarify the archived state's visibility, but these are minor gaps given the modest complexity.

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 account_id already described in the schema. The description adds no parameter-specific meaning beyond the schema, 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 states a specific action and resource: 'Archive one bucket.' This is clear and aligns with the tool name, but it does not explicitly contrast with related operations like bucket_delete_permanently or bucket_lock, leaving some ambiguity about what 'archive' entails relative to those 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 phrase 'Active websites must be unpublished first' provides a concrete precondition and implies the tool should be used only after unpublishing active sites. However, it does not name alternatives or specify when not to use this tool versus bucket_unarchive, bucket_delete_permanently, or bucket_lock, so guidance is implied rather than explicit.

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

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

With only false hints in the annotations, the description carries the full burden of behavioral disclosure. It explains that the tool returns the incoming email address and receiving state in bucket.inbound_email, that null means unconfigured, that search indexing is on by default for public sites, that writing files saves private storage without publishing a live site, and that separate policies apply to private storage vs. publications. This goes well beyond the annotations and provides rich behavioral detail with no contradictions.

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 four sentences, each contributing essential information: purpose, return behavior, search indexing guidance, and form/storage semantics. It is front-loaded with the primary action and avoids fluff, though its density is moderately high. It could be slightly tighter but remains clear and well-organized.

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 (multiple nested metadata objects) and the availability of a detailed input schema and output schema, the description covers the most critical operational behaviors: return value semantics, search indexing default, the relationship between storage and publishing, and applicable policies. It does not re-explain schema fields, which is appropriate, and leaves no major gaps for an agent to call the tool incorrectly.

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 beyond the schema by explaining the effect of allow_search_indexing (default true, set false only when the owner asks) and by summarizing what metadata.publication_forms can configure (resource form, system or website-file success response). It also clarifies that writing files saves private storage rather than updating a live website, which informs the metadata usage. This is meaningful addition, though not exhaustive for every nested field.

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 'Create a private Revdoku bucket for agent-generated files, reports, or websites,' which is a specific verb plus resource with a clear scope. It distinguishes this from the sibling bucket_create_from_template by emphasizing a new private bucket rather than one created from a template, and it clarifies that writing files does not create a live website.

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 for when to use the tool: when a new private bucket for agent-generated content is needed. It also provides parameter-specific guidance, such as setting allow_search_indexing=false only when the owner asks, and distinguishes private storage from publications. However, it does not explicitly mention alternatives like bucket_create_from_template or state when not to use this tool.

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

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

Annotations only provide empty booleans, so the description carries the behavioral burden. It adds that the result is private and not published, which are real side effects an agent should expect. It also signals a trust/authorization constraint ('trusted Revdoku template manifest'), though it does not detail import failure behavior or visibility changes.

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

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

Two short sentences with no filler; the core action and privacy outcome are front-loaded. Every phrase contributes either to purpose or to expected side effects.

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

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

For a one-required-parameter creation tool with a full input schema and an output schema, the description covers the essential purpose, result visibility, and source of files. It could add explicit guidance that template_key must come from bucket_template_list, but the schema already states that, so the gap is minor.

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 coverage is 100%, providing the baseline, and the description adds meaning for the main parameter by explaining that template_key refers to a manifest of ready-to-serve static files and must be trusted. It does not re-explain title, description, or account_id, but those are already fully documented in the schema.

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

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

States a specific action ('Create a private Revdoku bucket') and a distinctive method ('importing ready-to-serve static files from a trusted Revdoku template manifest'), which separates it from the plain bucket_create sibling. It also sets the visibility outcome ('The bucket is not published').

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 tool is for template-based creation ('from a trusted Revdoku template manifest') and names the private/not-published outcome, but it never explicitly tells the agent when to choose this over bucket_create or how to recognize an applicable template. No when-not or alternative routing is given.

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

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

Annotations already signal destructive behavior (destructiveHint=true, readOnlyHint=false). The description adds concrete behavioral specifics: the operation is permanent, applies only to archived/unpublished normal buckets, and requires a confirmation token. It does not reveal error behavior for non-archived buckets, but the key irreversible-destruction trait is clearly communicated.

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 crisp sentences front-load the action and conditions with zero filler. 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?

The description covers the key preconditions (archived, unpublished, normal bucket) and the confirmation requirement, which are the critical pieces of context for a destructive tool. It doesn't elaborate on failure modes or return values, but the schema and annotations cover the rest adequately.

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 detailed descriptions for bucket_id, confirmation, and account_id. The description adds only a minor reminder to obtain bucket_id and delete.confirmation from bucket_list/bucket_get; it does not add substantive meaning 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 uses a specific verb (

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

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

The description states exactly when the tool is valid—only for archived, unpublished normal buckets—and tells the caller to obtain bucket_id and delete.confirmation from bucket_list or bucket_get. It stops short of explicitly naming alternative tools for other cases, but the preconditions and sourcing guidance cover the core decision of when to call it.

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

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

Annotations already mark this as read-only and idempotent, but the description goes further by stating variables are returned in full while secrets are encrypted and only names/last 4 characters are shown. This is important behavior that prevents an agent from expecting secret values to be returned.

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 short, dense sentences: the first states the action, the second explains the public vs. secret distinction, and the third adds the naming convention. No filler or redundant opening like 'This tool is used to...'.

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 annotations and an output schema present, the description fills the remaining gap: it clarifies the public/variable vs. server-only/secret behavior and defines the output shape for secrets. This is complete enough for an agent to call it safely and interpret results.

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 has 100% coverage with clear descriptions of bucket_id and account_id. The description adds no parameter-specific meaning beyond what the schema already says, 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?

States a specific verb and resource: 'Read a bucket's integration variables and secrets.' It clearly differentiates itself from bucket_env_set and other bucket operations, and the title aligns with the read 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?

Descriptive context is clear: use it to read public variables and truncated secret metadata. It does not explicitly say 'use bucket_env_set to modify' or list exclusions, but the read-vs-write distinction is made evident by the verb and sibling tool names.

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

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

The description discloses that variables REPLACES the entire public set (destructive to existing vars unless preserved), while secrets is a PATCH with empty-string deletion. It also adds naming conventions (UPPER_SNAKE_CASE) and a security warning ('Never put a secret value in variables'). These go well beyond the annotations (which only indicate non-read-only, non-idempotent, non-destructive) and are crucial for correct 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 dense but every sentence earns its place. It front-loads the core action, then efficiently explains the replacement vs. patch distinction, naming convention, and security note. No fluff, and the use of backticks for parameter names improves scannability.

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 4-parameter, nested-object write operation, the description covers all critical aspects: the main purpose, prerequisite call, variable replacement semantics, secret patch behavior, naming rules, and security warning. The output schema exists, so return details are not needed. There are no significant gaps that would prevent an agent from using 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 schema already documents each parameter with its behavior (e.g., 'Replaces the full public set' for variables, 'Patch: non-empty sets, empty string deletes, omitted kept' for secrets). The description adds extra value by emphasizing the security constraint, naming rule, and the need to call bucket_env_get first. Since schema coverage is 100%, the baseline is 3, and this description elevates it with additional meaningful 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 clear verb+resource statement ('Set a bucket's integration variables and/or secrets') and adds the write-access prerequisite. It distinguishes itself from the sibling bucket_env_get by the set/get contrast, and from other bucket_* tools by the specific resource (env vars/secrets). The purpose is unambiguous.

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

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

It explicitly instructs the agent to call bucket_env_get first when using variables to preserve existing entries, and clarifies the exact semantics for secrets (patch behavior). This is direct, actionable guidance on when and how to use the tool, going beyond a generic 'use this to set env vars'.

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 (readOnlyHint=false, destructiveHint=false), the description discloses several important behaviors: the file must already exist, the operation does not publish, content is appended without parsing or validation, and lock failures should be retried briefly and then surfaced with error.details. This adds meaningful behavioral context beyond what annotations 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?

Three sentences, each earning its place: the first establishes the operation and scope, the second sets important format limitations, and the third covers lock handling. The main purpose is front-loaded, and there is no redundant or filler 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?

Given the output schema exists and the input schema covers all parameters, the description supplies the remaining operational context needed: file existence, no publishing, text-only scope, CSV/JSON caveats, and lock retry behavior. Nothing essential for correct invocation or for understanding side effects is missing.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters thoroughly. The tool description adds general context such as text-format suitability and JSON invalidity, but it does not provide additional per-parameter semantics beyond what the input schema already contains. 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 opens with a specific verb and resource: 'Append UTF-8 text to an existing private Revdoku bucket file without publishing.' It clearly limits the operation to text files, excludes binary-file use, and distinguishes appending from the sibling bucket_file_write operations by focusing on append semantics.

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-not guidance: it is not a binary-file API, it does not parse CSV or JSON, and raw appends to .json can produce invalid JSON. It also advises retrying briefly on lock contention. It does not name an alternative sibling tool such as bucket_file_write, but the exclusions and context are clear enough to guide 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 this is a mutating, non-idempotent, non-destructive operation. The description adds valuable behavioral context beyond annotations: it copies by storage reference (server-side), supports archived sources, and explicitly states bytes are never downloaded or reuploaded. It does not mention overwrite behavior or return values, but the output schema covers that, so this is adequate.

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

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

The description is a single, well-structured sentence that front-loads the primary action and destination, then packs in key constraints (writable target, no download/reupload) without redundancy. Every clause earns its place; 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?

Given the tool has 7 parameters, a detailed input schema, an output schema, and annotations, the description covers the essential behavioral aspects (copy to path/bucket, archived support, server-side operation). It does not explain the interplay between target_path and target_folder or clarify overwrite semantics, but the schema descriptions handle parameter specifics and the output schema covers return values. This is complete enough for an agent to invoke correctly in most cases.

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%: every parameter has a detailed description with examples (e.g., bucket_id from bucket_list, path example index.html). The tool description adds no parameter-specific meaning beyond what the schema already provides. Baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states a specific verb (copy), resource (file), and destination (path or bucket), and adds distinguishing detail ('by storage reference, including archived sources'). It is immediately obvious this duplicates a file rather than moving or renaming it, differentiating it from siblings like bucket_file_move and bucket_file_rename.

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 on when to use this tool (to copy a file, including archived ones) and notes a key prerequisite (target bucket must be writable) and an operational distinction (bytes never downloaded/reuploaded). However, it does not explicitly contrast with move/rename or state when not to use it, so it falls short of the 'explicit when/when-not/alternatives' bar.

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

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

Annotations already cover readOnlyHint and idempotentHint, and the description adds valuable non-obvious behavior: it returns metadata only and does not download content, and prefers file_id over path. This enriches the annotation-provided safety profile without contradicting it.

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

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

Two sentences with no filler. The key action and constraint are front-loaded, and the use case is provided in a compact second sentence. Every word adds value.

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, the read-only annotations, and full schema parameter descriptions, this description is complete. The agent knows what it returns, why it is used, and how to select it without needing missing details.

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 useful selection guidance beyond the schema by marking file_id as the preferred identifier and path as the alternative ('by file_id (preferred) or path'), which adds semantic value.

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

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

The description uses a specific verb-resource pair ('Get full metadata for one bucket file') and explicitly clarifies it does not download content. It distinguishes this from writing, listing, and reading tools by stating it expands lean file_id/version_id results into full details.

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 a clear use case: expanding the lean file_id/version_id returned by bucket_file_write and bucket_file_write_many. It implies not to use this when content is needed by saying 'without downloading its content', but it does not explicitly name the alternative tool or provide a when-not-to-use list.

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 readOnlyHint, idempotentHint, and destructiveHint annotations, the description discloses meaningful behavior: incoming email layout, folder returning only immediate files rather than nested message folders, and offset-listing limitations. This enriches the agent's understanding of real-world results without contradicting any 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 front-loaded with the core purpose and then efficiently covers parameter behavior, the email use case, and the offset-listing caveat. Every sentence adds operational value, and the structure moves from general listing behavior to specific usage guidance.

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

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

Given that an output schema exists, the description does not need to explain return values. It is complete for an agent to call the tool correctly: it covers pagination, search, folder scoping, email-specific file layout, and the important distinction between offset listing and a durable cursor. The read-only annotations plus these details leave no major operational 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?

Even though the schema already documents all parameters, the description adds behavior not in the schema: omitting limit/offset returns all files for compatibility, query is a case-insensitive contains-search, folder lists name-ordered immediate files, and folder=_email/in has special nested-folder semantics. This goes well beyond the baseline for 100% schema coverage.

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

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

The description opens with 'List files in a Revdoku bucket,' a specific verb and resource that make the tool's purpose immediately clear. It also distinguishes itself from related file operations by noting it is an offset file listing rather than a durable inbox cursor, which separates it from read/get tools.

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

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

The description gives concrete guidance: use limit/offset for pagination, omit them for all files, use query for name/path search, and use folder for immediate files. It also provides a practical email-inbox pattern ('Use query=_email/in/ and paginate') and explicitly warns that this is not a durable inbox cursor, which is strong when-not guidance.

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

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

Annotations already mark destructiveHint=true and idempotentHint=false. The description adds valuable context beyond the annotations: it specifies that same-bucket moves create a rename revision and cross-bucket moves copy then soft-delete the source without reuploading bytes. This discloses the side effects (soft-delete, revision creation) and clarifies the mechanism, which is more than the annotations alone provide.

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

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

Two sentences, zero filler. The first sentence states the core action, and the second fronts the key behavioral nuance (same-bucket vs cross-bucket). Every word earns its place; the description is efficient and well-ordered.

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

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

Despite 7 parameters, only 2 are required and all are schema-documented. The description covers the essential contextual difference (rename vs copy+soft-delete) that is not obvious from the schema alone. An output schema exists, so return values need no explanation. Missing minor details like permission prerequisites or error behaviors, but these are not critical given the annotations and schema richness. Slightly short of 5 because it doesn't explicitly note that the operation alters the source bucket, but that is implied.

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 all 7 parameters are already documented with descriptions in the schema. The description text does not add any additional meaning to the parameters (e.g., relationships between target_path and target_folder, or the optionality of target_bucket_id). Baseline 3 is appropriate because the schema carries the parameter documentation, and the description adds no extra value here.

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?

Clearly states the action ('Move one file') and the resource ('by storage reference'). It differentiates from sibling tools like bucket_file_rename and bucket_file_copy by explaining the behavioral difference (same-bucket creates a rename revision; cross-bucket copies then soft-deletes). This is specific and unambiguous, not a tautology.

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 (move a file) but does not explicitly guide the agent on when to choose this over bucket_file_rename, bucket_file_copy, or bucket_file_reorganize. There is no when-not or alternative naming, only an implicit context around same-bucket vs cross-bucket behavior. This is adequate but lacks explicit routing guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the bar is lower; the description adds substantial behavior beyond that: 750000-byte cap, .eml returning original MIME, attachment path semantics, the need to download larger originals, and the security warning to treat email content as untrusted data. 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 longer than average but every sentence earns its place: core behavior first, then email specifics, size limits, binary exclusions, and a security warning. It is well-structured and front-loaded with the most important identifying information.

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

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

Given the tool's complexity, the annotation set, the output schema, and the sibling context, the description is complete. It covers scope, limits, email parsing expectations, attachment path handling, alternative routes for binaries/large files, and a security warning; nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters, giving a baseline of 3. The description adds useful parameter-level context by specifying the exact email path pattern (_email/in/<receipt-time>--<id>/message.json) and clarifying that attachment paths are relative to the message folder, which directly helps the agent construct the path parameter.

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

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

The description states a specific verb and resource: read one text bucket file from Revdoku, with a clear size cap and text-type scope. It also differentiates itself from binary-handling/download paths and the email-specific use case, so an agent can tell it apart from siblings like bucket_file_get.

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 guidance on when to use this tool for inbound email message.json files and clearly excludes binaries and large originals, directing those to downloads/REST/CLI. It does not name a specific sibling alternative like bucket_file_get, but the when/when-not guidance is still 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 already indicate this is a mutation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds useful context about creating a rename revision and avoiding byte reupload, but it does not disclose edge-case behavior such as handling of existing new_path, permission requirements, or failure modes. With annotations covering the basic safety profile, this is adequate but not thorough.

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 that efficiently conveys the action, scope, and key benefit. No wasted words, and the most important distinction (same-bucket) is placed early. Slightly more context could be added, but it is appropriately 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?

There is an output schema, so return values are covered. The description and schema together cover parameters and mutation behavior. However, the existence of a sibling tool bucket_file_move creates ambiguity about when to use this rename tool vs that move tool; the description does not clarify the boundary. This is a notable completeness gap for an agent deciding between tools.

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 all 5 parameters, so the schema fully documents each parameter. The description adds no additional parameter-specific meaning (e.g., formatting, constraints, or relationships). Baseline of 3 is appropriate given complete schema coverage.

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

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

The description states a specific action (rename or move), the resource (same-bucket file path), the mechanism (by blob reference), and the effect (creates a rename revision without reuploading bytes). This clearly differentiates from copying or cross-bucket moves, though it does not explicitly name sibling tools. It is a distinct, non-tautological purpose.

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

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

The description implies use for same-bucket renames/moves ('same-bucket') but does not explicitly state when to prefer this over the sibling bucket_file_move or when not to use it. No exclusions or alternative conditions are given, leaving some ambiguity for an agent.

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

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

Annotations already indicate destructiveHint=true (modifies/destroys) and readOnlyHint=false. The description adds only the server-side efficiency aspect, which is also present in the schema. It does not disclose operation ordering, failure semantics, or side effects, leaving the agent with minimal behavioral insight 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?

Two concise sentences front-load the core purpose and use case, with no redundant information. The structure is efficient, though the content is sparse.

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 (batch operations, multiple parameter fields, destructive hint), the description is insufficient. It does not explain operation-specific field requirements, ordering, or error behavior, making it hard for an agent to construct correct operations without additional reasoning.

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?

While schema coverage is 100%, the description does not clarify the confusing parameter combinations (e.g., which fields to use for rename vs move vs copy, or the relationship among to_path, new_path, target_path, target_folder). Additionally, the schema's operation description mentions 'delete' but the enum excludes it, adding ambiguity that the description fails to resolve.

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: batch rename, move, or copy files using server-side path/blob references. It highlights the efficiency (no byte transfer) and typical use case (folder cleanup/reorganization). While it doesn't explicitly differentiate from siblings like bucket_file_move, the 'batch' aspect sets it apart clearly enough.

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 for folder cleanup or reorganization without reading or reuploading bytes'), but it does not mention alternatives or explicitly state when not to use this tool. It implies that for batch operations this is the right choice, but it doesn't contrast with the single-operation 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?

The description reveals behavior beyond annotations: the file is private, does not affect a live website, does not install dependencies or compile source, honors optimistic concurrency, and the response should be surfaced via dashboard_url/public_url. Annotations only carry basic hints, so this added context is valuable. No contradiction found.

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 focused sentences: core capability, non-publishing caveat, concurrency guidance, and alternative-upload/response guidance. The core statement is front-loaded 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?

For an 8-parameter tool with a rich schema and output schema, the description covers scope, supported file types, non-functional constraints, concurrency, and user-facing response handling. Nothing critical is missing for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters. The description reinforces expected_bucket_revision_id's purpose and mentions the response link, but it does not add substantial parameter-level meaning 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 opens with a clear verb-object pair—'Write or replace one private UTF-8 file in Revdoku'—and lists supported content categories. It distinguishes from related tools by stating it handles one file and is not for website publishing or binary/folder uploads.

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

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

It explicitly states when not to use it (publishing, binary assets, whole folders) and points to alternatives (ready-to-serve static files, CLI/REST direct-upload API). It also gives concurrency guidance for expected_bucket_revision_id, but it does not explicitly name the sibling bucket_file_write_many for multi-file writes, so it falls just short of fully explicit.

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

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

Annotations declare destructiveHint true and readOnlyHint false, but the description adds valuable nuance beyond that: delete_missing performs soft-deletes while preserving managed/generated files, the operation does not publish a live site, and concurrency conflicts are prevented via expected_bucket_revision_id. These are meaningful behavioral details not inferable from annotations alone.

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

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

The description is compact and front-loaded, starting with the core purpose and then covering publishing exclusions, concurrency, binary assets, and deletion semantics in four sentences. Every sentence earns its place and no content is repeated from the 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 potentially destructive batch-write tool with six parameters and an output schema, the description covers all needed context: usage scope, publishing limitations, alternative upload paths, concurrency protection, delete_missing behavior, and user-facing response links. The output schema covers return value structure, leaving no critical gap for safe 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 description coverage is 100%, providing a baseline of 3. The description adds procedural meaning by instructing the agent to pass expected_bucket_revision_id from bucket_get to avoid overwriting concurrent edits, and it clarifies delete_missing semantics (soft-delete, preserve managed/generated). This goes slightly beyond the schema's own field comments, so a 4 is warranted.

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

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

The description names a specific verb and resource: 'Write multiple private UTF-8 files ... in one Revdoku bucket edit.' It clearly distinguishes this from a single-file write by emphasizing the batch aspect, and explicitly states it does not publish or update a live website, preventing confusion with publishing tools.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: it excludes website publishing, says Revdoku does not install dependencies or compile source, and routes binary assets or whole local folders to the CLI or REST direct-upload API. It also tells the agent to pass expected_bucket_revision_id from bucket_get, providing concrete procedural context.

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

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

Annotations already cover read-only/idempotent/non-destructive safety, and the description adds substantial behavioral context: sensitive subobjects require upload/write or write-capable access, counters are not a message cursor, deep links are stable and login-required, and inbound_email provides decoded metadata guidance. 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 lead sentence is an effective front-loaded summary and every following sentence adds information. It is long, but the density is justified by eight parameters and access-dependent behaviors; some output-format detail could arguably live in the output 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 complex aggregate getter, the description covers permissions, pagination, optional sections, and follow-up actions (reading message.json and sharing review/settings URLs). With annotations and a full input schema, an agent has everything needed to call the tool appropriately.

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 value beyond the schema by explaining what include_form_submissions yields (submitter identity, document selections, exact 3x3 ASCII minimap), what include_inbound_email exposes, and how file_limit/file_offset page bucket.files.

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 first sentence identifies a specific verb ('Get one bucket') and enumerates a precise bucket-level payload: files/current revision, website state, GitHub sync status/setup link, and archive/delete guidance. This scope is distinct from sibling bucket_list or bucket_file_get operations, even though no sibling is named.

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?

Clear conditional usage is provided: set include_inbound_email vs include_form_submissions, access-level prerequisites, and file_limit/file_offset pagination. The description does not explicitly name alternatives or say 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?

Annotations already establish readOnly, idempotent, and non-destructive behavior; the description adds that only 'visible' buckets are returned and enumerates the status/guidance fields shown. This is useful context beyond the annotations, with no contradiction.

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

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

Three short sentences with the main purpose front-loaded and no filler. Each sentence earns its place by adding either output content or actionable usage guidance.

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

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

For a read-only list operation with a rich output schema, clear annotations, and fully documented optional parameters, the description covers what is returned, when to use the tool, and how to filter. No critical calling information is missing.

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

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

Schema coverage is 100%, and both parameters already have detailed descriptions, including the case-insensitive contains-filter and the account_id authorization caveat. The description only restates the query filter ('Pass query to filter by title') and adds nothing about account_id, so it meets the schema-driven baseline of 3.

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

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

The description uses a specific verb ('List'), names the resource ('Revdoku buckets'), and enumerates what is returned (website state, GitHub sync status/setup links, archive/delete guidance). It doesn't explicitly contrast with sibling bucket_get, so sibling differentiation is only implicit, but the purpose is unmistakable.

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

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

The description explicitly frames the tool as a precursor: 'Use this before follow-up bucket actions,' which tells an agent when to call it. It doesn't list exclusions or name an alternative such as bucket_get for singleton lookups, so it stops short of full routing guidance.

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

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

Annotations only give negative hints (not read-only, not idempotent, not destructive), so the description carries the burden. It adds one behavioral trait—other agents can observe the connector as working—but does not explain the lock's blocking semantics, expiration, or the need to release it via bucket_unlock. Some useful context, but key mechanics are missing.

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

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

A single, front-loaded sentence that wastes no words. It states the action, the condition, and the rationale in one concise statement.

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 rich schema and an output schema present, the tool is callable. However, the description omits lock lifecycle details—whether the lock blocks other agents, how duration_seconds interacts, and that bucket_unlock is the release path—so an agent may not fully understand the operational contract.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description does not add any parameter-level detail beyond what is in the schema, so the baseline 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 identifies the action ('Lock a whole bucket') and the timing ('before broad edits or uploads'), with a stated purpose ('so other agents can see this connector is working'). It distinguishes from siblings like bucket_lock_files by emphasizing 'whole bucket', though it does not explicitly name or contrast those 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 a clear trigger context: use before broad edits or uploads. It does not, however, state when not to use it or point to bucket_lock_files for per-file locking, so exclusions and alternatives are left implicit.

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

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

Annotations already indicate this is not read-only (readOnlyHint=false) so mutation is expected. The description adds context about the purpose (locking for editing and visibility to other agents), but does not disclose additional behavioral details like lock reversal, duration parameters, or side effects on concurrent access. Some value is added, but it is not extensive.

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 with no filler. It front-loads the core action and purpose, making it immediately understandable. Every word contributes to the meaning.

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 locking operation with a fairly simple interface, the description covers the essential purpose and timing. The presence of an output schema and high schema coverage compensates for missing return details. It lacks explicit mention of unlocking or related tools, but that is not critical for basic usage.

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 all parameters are documented. The description text adds little beyond the schema—it mentions 'one or more bucket files' which loosely relates to the paths parameter, but no deeper semantics like how message or duration_seconds affect behavior are provided. Baseline 3 is appropriate when schema covers everything.

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) and resource (bucket files) and adds the purpose (before editing). It is concise and unambiguous, though it does not explicitly distinguish from sibling tools like bucket_lock (which likely locks the whole bucket).

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 tool is for locking files before editing and mentions visibility to other agents, but it does not explicitly state when not to use it or point to alternatives such as bucket_lock or bucket_unlock_file. The usage context is implied rather than explicitly contrasted with 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?

Beyond the annotations (idempotentHint=true, destructiveHint=false), the description discloses the critical irreversibility trait: there is deliberately no unlock tool, unlocking is web-UI-only requiring the user to type 'confirm', and the agent must ask the user to unlock. It also specifies the precise operational scope (blocked visibility operations, applied to API and agents), shaping expectations about 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?

Two sentences front-load the action, scope, and purpose before the irreversible-unlock caveat. Slight redundancy: 'Locking is idempotent' restates the idempotentHint=true annotation, costing one clause that could have been trimmed, but the remaining content is dense and essential.

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 2-parameter tool with full schema coverage, annotations covering idempotency and safety, and an output schema present, the description covers all agent-relevant context: scope, purpose, irreversibility, and the required user workflow. Return values are handled by the output schema, so nothing material 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% with detailed descriptions for both bucket_id (origin and example format) and account_id (default-account omission rule plus the security constraint not to infer an account). Per the rubric baseline for high schema coverage, the description need not add parameter info, and it appropriately focuses on behavior instead.

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

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

States a specific verb and resource ('Lock a bucket's visibility') and enumerates exactly which operations are prevented (publish, unpublish, public/password switching, public URL changes), which clearly distinguishes it from siblings like bucket_lock and bucket_lock_files. The protective purpose ('protect a bucket holding private data from accidental publishing') further aids selection.

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 context ('use this to protect a bucket holding private data from accidental publishing') and warns about the no-unlock consequence so the agent knows to involve the user. However, it does not explicitly name sibling alternatives or state when NOT to use this in favor of them, so the guidance is strong but not exhaustive.

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 read-only/idempotent annotations, the description discloses retention behavior, retention_limited semantics, bot-inclusive versus bot-exclusive totals, null comparison handling, free versus detailed retention, and time-zone handling. These are meaningful operational traits an agent needs to interpret results correctly.

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?

It is front-loaded with the main usage modes, but the description is a long, dense block of prose with extensive return-field explanations that overlap with the existing output schema. It is informative but harder to scan than necessary for tool selection.

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 complex analytics modes, read-only annotations, full schema coverage, and an output schema, the description is complete enough to invoke the tool correctly. It covers scope selection, defaults, time handling, retention caveats, and result interpretation without leaving critical gaps.

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

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

Although schema coverage is 100%, the description adds conditional semantics: account summaries exclude previews and disallow 24h/custom ranges, publication_id sources are named, account_id authorization and default-account behavior are explained, and event time-zone behavior is clarified. This goes well beyond the structured 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 states a specific verb and resource: it returns publication analytics, with clear modes for account-level dashboard summaries versus bucket/website detailed reports. It distinguishes account scope, bucket_id, and publication_id usage paths in a way that lets an agent select the right invocation without inspecting 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?

It explicitly says when to use scope account for a quick overview and when to use bucket_id or publication_id instead. It also states range restrictions for summaries (no 24h or custom dates), defaults, and how exact from/to windows work, giving clear when/how guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the cardinality detail that it returns one publication, but otherwise provides no behavioral context such as error behavior or authentication nuances.

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 clear sentence with no redundant wording. It front-loads the core action and object without wasting space.

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 operation with two parameters, full schema coverage, a provided output schema, and safety annotations, the description is sufficient. An agent has everything needed 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 description coverage is 100%, so publication_id and account_id are already fully documented, including the account authorization caveat. The description adds no parameter-level detail, so the baseline score 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 states a specific action and resource: 'Get one bucket website publication.' The word 'one' distinguishes it from bucket_publication_list, and the singular object clearly differentiates this from bucket_get or 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 use when a single known publication is needed, but it does not explicitly state when to choose this over bucket_publication_list or mention exclusions. The 'one' phrasing provides only implied usage context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, and the 'List' wording aligns with those. The description adds genuine value beyond annotations by disclosing that this returns sensitive email data and requires elevated permissions (account-owner connector with publish permission and write access). 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 front-loads the purpose and scope, then covers return payload, use case, and auth requirement in a compact three-sentence structure. Each sentence adds new information with no filler or tautology.

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 list endpoint with one required parameter, a documented output schema, and safety annotations in place, the description covers purpose, scope, use case, and authorization. The only minor gap is that it doesn't hint at limit's 2500 max, but that is already specified in the input schema, so overall completeness is strong.

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 all three parameters are documented in the schema itself. The description does not add parameter-level semantics beyond implying that limit controls both lead and session counts, which the schema already states ('Maximum number of leads and of recent access sessions to return'). Baseline of 3 applies 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 opens with a specific verb+resource ('List visitor leads for one publication') and enumerates precisely what is returned (verified vs unverified emails, visit stats, per-path activity, and access sessions). No sibling tool covers leads/emails, so it is clearly distinguished from the analytics, recipient-links, and publishing 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?

'Use this to follow up without opening the Revdoku dashboard' gives a concrete invocation context, and the permission clause ('requires an account-owner connector with publish permission and write access to the bucket') communicates prerequisites. It stops short of explicitly naming which sibling to use instead in other scenarios, but the use-case framing is clear enough for an agent to route correctly.

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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable scope details: it lists both active and historical publications and limits the result set to those visible to this MCP connector, which clarifies expected behavior beyond the annotations.

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

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

A single, focused sentence with no filler or redundancy. Key qualifiers ('active and historical', 'visible to this MCP connector') are front-loaded and directly support the agent's decision-making.

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

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

For a simple read-only listing tool with full schema coverage and output schema available, the description covers the essential scope. It might be strengthened by naming sibling tools like bucket_publication_get, but the omission does not block 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?

Schema description coverage is 100%, so both bucket_id and account_id are already documented with meaningful context. The description adds no parameter-specific guidance, but the schema fully covers parameter semantics, 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 states a specific action ('List'), a specific resource ('bucket website publications'), and a clear scope ('active and historical', 'visible to this MCP connector'). It clearly identifies what the tool does and distinguishes it from retrieval tools like bucket_publication_get.

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 enough context to infer when to use it—when you want to enumerate publications visible to the connector—but it does not explicitly contrast it with sibling tools such as bucket_publication_get or mention any preconditions, exclusions, or alternative selection 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 the annotations (readOnlyHint false), the description discloses rich behavior: 'Recreating a recipient's link replaces its expiry and invalidates the previous URL', lifecycle effects ('Removing an address from the allowlist or deleting its Tracking Link revokes access'), shared quota ('share the account's recipient-link quota'), auth requirements ('Requires an account-owner connector with publish and bucket-write permission'), and a security caveat ('Never share these links publicly'). This adds substantial value 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 five-sentence description is dense but has no padding: the core purpose is front-loaded, followed by invalidation semantics, defaults, lifecycle, quota, permissions, and a security warning. Every clause earns its place and introduces new behavioral information.

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

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

For a mutating tool with no output schema, the description thoroughly covers permissions, defaults, lifecycle, quota, and revocation behavior. The only notable gap is that it never describes the return format of the created links, though an agent can reasonably infer the created links are returned.

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 meaning beyond the schema by explaining the emails parameter's default behavior ('Defaults to allowlisted addresses') and the per-person constraint that explains why bare domains are skipped. The other parameters (publication_id, expires_in_days, account_id) are already well-specified by their 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 leads with a specific verb and resource: 'Create personal links for a Require Email website', and immediately differentiates these from ordinary tracking by noting each URL 'admits one recipient without the emailed OTP step and appears in Tracking Links with its engagement analytics.' This clearly separates it from publishing, analytics, and general tracking siblings such as bucket_publish and bucket_publication_leads.

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

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

Usage conditions are explicit: 'Defaults to allowlisted addresses; bare domains are skipped because links are per person' tells the agent when a subset is required, and 'Pass `emails` for a subset' gives the concrete trigger. It does not name sibling alternatives explicitly or state when-not-to-use, so the guidance is clear context rather than full routing.

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 (destructiveHint=true, etc.), the description discloses async behavior, the need to check publish_state via bucket_publication_get, the BUCKET_VISIBILITY_CHANGE_LOCKED failure mode, web-UI-only unlocking, AUP approval requirements, and the political-content prohibition. It also clarifies that a failed republish preserves the previous site. There is no contradiction with 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 front-loaded with the core purpose and usage decision, then failure modes and policy constraints. It is long but earned: legal/policy and lock behavior need to be present. Some schema details (e.g., static/spa routing semantics) are repeated nearly verbatim, which slightly inflates length.

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, destructive, 10-parameter publish tool, the description covers workflow, alternatives, failure modes, prerequisites, policy restrictions, and where to verify success. It even notes the web-UI-only unlock limitation. The output schema exists, so return-value details are not 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 description coverage is 100%, so the baseline is 3. The description mostly restates schema-level guidance for site_mode and publication_root_directory rather than adding new parameter-level meaning. It adds only the contextual cue to pass description when the user wants explanatory text saved, which is already implied by 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 ('Queue an async publish or republish'), names the exact resource ('the bucket's saved draft'), and states the outcome ('as a live public website'). It also explicitly differentiates from bucket_publish_preview and bucket_publish_password_protected, so an agent can select the right tool without schema inspection.

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: use bucket_publish_preview first unless the user has reviewed the site or explicitly asks to publish immediately; use bucket_publish_password_protected for protected/password/private sites; pass description only when the user wants explanatory text saved; and check bucket_publication_get before claiming success. It also covers republish behavior and the visibility-lock failure path.

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 a mutating/destructive operation, but the description adds substantial behavioral context: async queuing, specific error codes (PUBLICATION_UPGRADE_REQUIRED, BUCKET_VISIBILITY_CHANGE_LOCKED), Free plan limitations, password generation and OTP verification behavior, failed republish preserving the previous site, and AUP restrictions. 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 long and dense, but front-loaded with a clear first-sentence purpose and every subsequent sentence adds operational, error-handling, or policy context needed for a high-stakes publish tool. It could be restructured with bullets, but the length is justified by the 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 16 parameters, protected access modes, async behavior, upgrade flows, visibility locking, and acceptable-use policy, the description is remarkably complete. An output schema exists, so return-value documentation is not the description's burden, and the tool's failure modes and follow-up actions are clearly covered.

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 mode-specific semantics beyond the schema: password auto-generation/rotation behavior, Require Email OTP/allowlist behavior, and the never-put-passwords-in-URLs rule. It does not walk through all 16 parameters, but the schema already documents 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 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 this tool from public publishing and preview siblings by naming the protected access modes and referencing 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 workflow guidance: preview with the requested protected access first, handle PUBLICATION_UPGRADE_REQUIRED by sharing upgrade_url, retry only after upgrade, and never silently fall back to Public. It also names bucket_lock_visibility_changes as a recommended follow-up and notes that unlocking is web-UI-only.

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

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

Goes well beyond the annotations by disclosing asynchronous queueing, 24-hour expiry, noindex handling, no impact on the main site, no live/private-site limit consumption, AUP approval requirements, and the political-content ban. These details align with annotations like openWorldHint=true and readOnlyHint=false while adding substantial context.

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

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

The description is long but front-loaded with the core action in the first sentence. Each subsequent sentence covers meaningful behavior, lifecycle, side effects, or compliance requirements, so the length is justified even though it could be tightened.

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 16 parameters and an output schema, the description covers all necessary operational context: async execution, polling via bucket_publication_get, what to share with the user, retry semantics, and hard policy constraints. Parameter-level details are already fully handled by 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?

The schema already documents all 16 parameters, so the baseline is 3. The description adds extra semantic value for access_mode/password/require_email by noting eligible paid access works in previews on Free and that form customization still follows the account plan, which is not apparent from the schema alone.

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?

Opens with 'Queue an async PREVIEW publish of the current saved draft to a temporary preview-<slug> URL,' naming the exact verb, resource, and output. This clearly differentiates the tool from live-publish siblings and even adds lifecycle traits like expiry and re-publishing 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?

Clearly frames when to use it: before upgrading, to evaluate paid access and presentation settings without affecting the main website. It also directs the agent to bucket_publication_get for status, but does not explicitly name bucket_publish or bucket_publish_password_protected as alternatives, so the guidance is clear 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?

Beyond the annotations, the description discloses meaningful behavioral details: live sites get files republished under the new prefix, unpublished sites only update the saved URL for the next publish, and the call fails with BUCKET_VISIBILITY_CHANGE_LOCKED if visibility is locked. This is substantial context for a mutation tool, though it does not cover every edge case such as old-slug redirect 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?

Three sentences with no filler. The first sentence states the core action, the second explains the live/unpublished behavior, and the third covers constraints and an error condition. Every sentence earns its place and the information 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?

Given the output schema exists, return values need no description. The description covers the operation, the live/unpublished distinction, slug constraints, and a specific failure mode. It is complete enough for confident invocation, though it does not enumerate reserved words or explicitly guide agents toward sibling tools.

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 bucket_id, account_id, and public_slug. The description repeats the slug format constraints already in the schema but adds little parameter-level meaning beyond that, so the 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 names a specific action and resource: renaming an existing website publication's managed URL slug. This clearly differentiates it from siblings like bucket_publish or bucket_update_publication_access, so an agent can identify what this tool is for 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?

The description gives clear context for when the tool applies: renaming a slug on any signed-in plan, with distinct behavior for live versus unpublished sites. It does not explicitly name alternatives or state when not to use it, so it stops short of a full when/when-not routing guide.

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

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

Annotations already cover readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds context about 'trusted' and 'ready-to-serve' files, but no further behavioral traits such as pagination, filtering, or auth scoping beyond what the schema already states. The description is transparent but not additive beyond the structured metadata.

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

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

Two short sentences, each earning its place. The core action 'list trusted static-file templates' is front-loaded, followed by the useful qualifier that templates contain ready-to-serve files. There is 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 an output schema present, annotations describing safety, and full schema coverage for account_id, the description supplies the remaining domain context: these templates are static-file templates meant for new private bucket import. It is complete for a simple listing tool, though it could briefly mention that results feed into bucket creation.

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% description coverage for the only parameter, account_id, which fully explains optionality, defaulting, and authorization. The description adds no parameter-level meaning, but with full schema coverage the description does not need to compensate. 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 uses a specific verb and resource: 'List trusted static-file templates that can be imported into a new private bucket.' It clearly differentiates from siblings like bucket_create_from_template (which creates) and bucket_list (which lists buckets) by scoping to reusable template artifacts. No ambiguity remains about what this tool returns.

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 phrasing 'that can be imported into a new private bucket' gives clear usage context: this list is a precursor to creating a bucket from a template. It does not explicitly name the sibling tool bucket_create_from_template or state when NOT to use it, so it stops just short of a perfect score.

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 destructive, not idempotent, and not open‑world. The description doesn't contradict these, and it adds the key behavioral detail that it moves a bucket from archived to active state. However, it doesn't mention potential side effects, such as whether the action is reversible or if any data is affected.

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?

Single, clear sentence with no filler. The key verb and object are front-loaded, and it's appropriately concise for a simple operation.

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 straightforward restore operation, this is adequate. The output schema is present, so return values are covered. The schema covers parameters. The only missing element is explicit guidance on when this tool should be used compared to bucket_archive or when it might fail, but that is minor given the simplicity.

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

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

The schema already provides full descriptions for both parameters (bucket_id with example format, account_id with usage and caution). The description adds no further parameter meaning beyond what the schema gives, so with 100% schema coverage, a 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 states a clear verb ('Restore') and resource ('archived bucket back to the active bucket list'), making the purpose unambiguous. It effectively distinguishes from sibling tools like bucket_archive and 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?

The description implies usage: it's for restoring archived buckets. However, it doesn't explicitly state when not to use it or mention alternative tools (e.g., bucket_archive for archiving). There's no guidance on prerequisites like bucket ownership or permissions.

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 the tool is a non-read-only, idempotent, and non-destructive mutation. The description adds the scope constraint 'locked by this MCP connector', which is useful, but provides no additional behavioral detail such as effects on access, failure handling, or reversibility. The description 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?

The description is a single clear sentence with no redundancy or filler. It is front-loaded with the primary action and object, making it immediately scannable and efficient 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?

For a simple unlock operation, the combination of the description, full parameter schema, and annotations covers the essential facts: what it does, that it is idempotent and non-destructive, and what parameters are needed. The description could mention how to verify a bucket is locked, but that is ancillary given the richness of the other structured signals.

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 fully documents both parameters. The tool description does not add any parameter-level meaning beyond what the schema already provides. Since the schema carries the full burden, 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 clearly states the verb 'unlock' and the resource 'a bucket', with a specific scope ('locked by this MCP connector'). This immediately distinguishes it from sibling tools like bucket_unlock_file or bucket_lock, which target different resources or actions. Even without naming alternatives, an agent can identify what this tool does.

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

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

The description implies when to use the tool: when a bucket is locked by this MCP connector. However, it offers no explicit alternatives or when-not-to-use guidance, such as pointing to bucket_unlock_file for files or bucket_lock for locking. The usage context is present but not fully elaborated.

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 communicate that this is mutating, idempotent, and non-destructive. The description adds the behavioral detail that only files locked by this MCP connector are affected, which is useful context, but it does not address error behavior or lock ownership beyond that.

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

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

One clear, front-loaded sentence with no wasted words. The action, object, and locking scope are all stated efficiently.

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

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

Adequate for a simple, well-schematized operation: the action and affected resource are clearuit, and the schema plus annotations cover parameters and side effects. Still, it lacks context about the locking lifecycle or relationship to the broader bucket lock/unlock tool family.

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 description does not need to re-document parameters. It adds no independent parameter meaning beyond the schema, which is acceptable but not compensational.

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 clear action ('Unlock') on a specific resource ('a bucket file'), with the qualifier 'locked by this MCP connector' adding useful precision. It is not a tautology, though it does not explicitly distinguish itself from the sibling tool bucket_unlock.

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 no guidance on when to choose this tool over alternatives such as bucket_unlock or bucket_lock_files, and no exclusions or preconditions. The description implies the context but does not explain it.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is covered. The description adds valuable behavioral context: the operation is async (must be polled), it preserves the reserved URL, it can fail with BUCKET_VISIBILITY_CHANGE_LOCKED, and unlocking is web-UI-only. This goes beyond the annotations without contradicting them.

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 action and its key side effect, the exact sequencing context, and the failure mode with remediation. Front-loaded with the core action before the conditional guidance.

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

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

The tool is a mutation with async behavior, a specific precondition, a polling requirement, and a known failure mode. The description covers all of these. The output schema exists, so return-value documentation is not the description's job. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description doesn't add parameter-level detail beyond what the schema provides, but it does reference bucket_list and bucket_publication_get as sources of the bucket_id and status, which is mild added context. 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 states a specific verb ('Queue an async unpublish'), a specific resource ('bucket website'), and a key constraint ('while keeping the reserved URL'). It clearly distinguishes this from sibling tools like bucket_publish and bucket_archive by naming the exact action and its purpose.

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

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

The description gives explicit when-to-use guidance: 'Use before archive/delete when bucket_list says required_action is unpublish_first'. It also names the follow-up step ('check bucket_publication_get separately until status is unpublished') and the failure mode with a user action ('ask the user to unlock it in the Revdoku app first'). This is exemplary routing and sequencing 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 the annotations, the description discloses important behavioral traits: the default search-indexing behavior by website type, the draft lifecycle for form changes, plan-based customization limits, and the Download-action behavior tied to metadata.publication_show_download_button. This gives the agent essential operational context that the bare annotations do not provide.

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

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

The description is a dense, run-on paragraph that embeds form rendering syntax, plan restrictions, and draft semantics in a single block. Many of these details are already present in the richly documented schema, so the description repeats rather than summarizes. It is not appropriately sized for a quick agent read, though the first sentence 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?

The description covers the most critical non-obvious context: searchability defaults, locked-off sites, Auto-Index viewer behavior, form configuration limits, and the draft-until-publish behavior. Because the schema is extremely detailed and an output schema exists, the description does not need to explain every field or return value. It is nearly complete for a tool of this complexity.

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 does restate some parameter semantics, such as metadata.publication_forms and metadata.publication_show_download_button, but it does not add meaning that is absent from the schema. Per the calibration rule, a 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 opens with a specific verb and resource: 'Update bucket title, description, metadata, or the affirmative allow_search_indexing setting.' This clearly identifies the tool's function and enumerates the main update targets, but it does not explicitly differentiate itself from sibling tools like bucket_update_publication_access or bucket_set_public_slug.

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

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

The description implies when to use this tool: whenever a bucket's title, description, metadata, or search-indexing setting needs to be changed. It also provides usage-related context such as 'Public permanent websites default to searchable' and 'Form changes are drafts until publish/republish.' However, it never explicitly states when NOT to use this tool or points to specific alternatives among 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 offer only readOnlyHint=false and non-idempotent info, so the description carries full behavioral disclosure. It uniquely reveals re-keying semantics (public <-> protected re-keys files and takes longer while staying live; same-storage-class changes are instant), the non-destructive operational nuance of keeping the site published, the locked-visibility error code and its exception, and a security rule ('Never put passwords in URLs'). This is rich context the annotations don't provide.

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

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

High information density — nearly every clause contributes (scope, instant vs re-key, alternating just, error path, security rule) — and the most important distinctive fact is front-loaded. It's a single dense paragraph rather than short bullets or labeled sections, so slightly harder to scan, but at 8 parameters and this behavioral nuance the length is justified.

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

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

For an 8-parameter, 1-required mutation tool with 100% schema depth, open-world annotation, and an output schema, the description covers what matters for correct invocation: when it applies, what to use instead, performance implications, failure conditions and their exceptions, and a security do-not. Return-value shape is presumably handled by the declared output schema, and safety profile by non-destructive annotation — nothing needed 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 coverage is 100% with detailed per-parameter descriptions, so the baseline is 3. The description adds meaningful behavioral meaning on top: it explains storage-class effects of access_mode (instant vs re-key) and that password rotation stays allowed even when visibility is locked. It doesn't enumerate the optional access-form fields, 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 opens with a specific verb, resource, boundary: 'Change an already-published website's access settings WITHOUT republishing its files or URL.' It then enumerates the exact mode switches it supports (public, password, Require Email, rotate password) and names the sister publish tools it is not. An agent can distinguish it from bucket_publish and bucket_publish_password_protected 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?

It explicitly states when to use (switch a live site's access settings, rotate password, apply access_form options) and when not to: 'To publish a NEW VERSION of the files, use bucket_publish / bucket_publish_password_protected instead.' The locked-visibility failure scenario plus 'unlocking is web-UI-only — ask the user' provides actionable routing for the error case too.

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

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

Annotations only declare write/idempotency/destructive flags. The description adds real behavioral context beyond them: an explicit authorization requirement tied to the Agency owner's connection, and the scoping caveat that account_id 'does not change the credential's default account.' It stops short of describing failure modes or duplicate-name 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?

Four short sentences, front-loaded with the action and scope, then the parameter clarification, then the authorization and account_id caveats. Every sentence carries information, though the account_id sentence is slightly redundant with the schema entry.

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, return values need not be explained, and all three parameters are fully described in the schema. The description covers the key auth prerequisite and account scoping for a mutation, leaving only edge cases like duplicate accounts or failure handling unaddressed.

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 parameters are already documented in the schema, which sets the baseline at 3. The description adds modest elucidation, clarifying that name is the account name while client_name separately identifies the client person or business, but no format or constraint detail beyond the schema.

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

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

The description states a specific verb and resource plus scope: 'Create a separate client account sharing the Pro Agency plan.' An agent immediately understands this provisions a distinct client account under the agency's plan, and the sibling bucket_*/revdoku_* tools are clearly a different domain, so differentiation is not needed.

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 a precondition ('Requires the Agency owner's explicitly authorized connection') and guidance on the optional account_id ('Pass the Agency account_id when needed'), which is useful context. However, it never states when to create a client account versus another account type, nor any when-not condition or alternative, leaving usage largely implied.

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 safe readonly, idempotent, non-destructive operation. The description adds useful behavioral context beyond annotations: the returned link is stable and does not sign the browser in, and user authentication happens separately when needed. This is genuinely helpful and not redundant.

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

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

Two concise sentences: the first states the purpose and scope, and the second adds relevant authentication behavior. There is no filler, repetition, or under-specification.

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

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

For a simple, read-only, parameter-light tool backed by an output schema and detailed parameter descriptions, the description covers everything an agent needs: what it returns, its stability, and the authentication boundary. No preservation or required side-effect disclosures are needed here.

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

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

Schema description coverage is 100%, and both parameters already carry detailed descriptions, including optionality, defaults, source of account ids, and authorization caveats. The description itself does not add parameter-specific semantics, so the 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 a specific verb and deliverable ('Return a stable Revdoku dashboard link') and the scope of what the link targets (buckets, websites, or connector access). It is easy to distinguish from sibling data-access tools like bucket_get or bucket_list because it is about producing a dashboard link rather than fetching data.

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 use context: when you need a dashboard link for buckets, websites, or connector access. It does not explicitly name alternative tools or state when-not-to-use, but the tool's purpose is singular enough that this is not a critical gap.

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, and non-destructive, but the description adds substantial behavioral context: how to relay suspension messages, which details must not be disclosed, what to do for onboarding states, and instructions to reconnect if tools are missing. This goes far beyond the annotation hints.

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 dense; nearly every clause covers an operational rule or documented field. It is organized by topic, though the opening sentence is a long run-on that packs many facts together.

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 status tool with many conditional behaviors and an output schema, the description is remarkably complete. It covers account selection, restriction handling, onboarding states, free plan details, publishing semantics, and even reconnect guidance, leaving no important invocation scenario unaddressed.

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

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

Schema coverage is 100% and the schema already explains the account_id parameter well. The description reinforces that the default account id stays fixed and that account_id selects another granted account per call, adding useful operational nuance beyond the schema.

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

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

The description states a specific verb ('Read') and resource (account, capabilities, publishing, restriction state), and names what it returns (server_version, latest_source, update_hint). It clearly distinguishes itself from the mutating and bucket-focused sibling tools.

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

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

It gives explicit call guidance: omit account_id for the default account, pass it per call to select another granted account, and never infer an account from a bucket id. It also describes conditional behavior for suspension, empty_account, and no_visible_buckets states, though it does not compare itself to sibling tools because no true status sibling exists.

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