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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description is consistent with them. It adds genuine behavioral detail beyond annotations by clarifying that this is the 'indexed view' and that a page may be short or empty while more results remain, which is important for correct pagination.

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: purpose and features first, sibling routing second, pagination caveat third. No filler or redundant restatement of 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 read-only listing tool with 100% schema coverage, the description covers purpose, alternatives, a required parameter, and a non-obvious pagination behavior. It doesn't detail the exact return shape, but the tool has no output schema and 'files and sub-folders' gives a sufficient high-level expectation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by emphasizing that bucketName is required and by explaining cursor semantics ('keep calling until no cursor comes back') beyond the schema's one-line cursor definition.

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

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

The description opens with a specific verb and resource: 'List the files and sub-folders inside a folder of a drive (the indexed view), with sorting and pagination.' It also names sibling tools search_files and list_files as alternatives, so an agent can clearly distinguish this tool from similar ones.

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 states a hard requirement (bucketName), routes keyword filtering to search_files, and recursive storage listing to list_files. It also instructs the agent to keep calling with the returned cursor until none comes back, covering the correct iterative usage pattern.

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

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

The description adds useful behavioral context beyond annotations: "a denial means the API key lacks this tool's scope, not a tool failure." It also notes the need for bucketName. However, it does not disclose what happens if the folder already exists, whether the operation is idempotent (though annotations mark idempotentHint=false), or what the successful response contains. Annotations already declare readOnlyHint=false and destructiveHint=false, lowering the bar for extra disclosure, but some gaps remain.

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

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

The description is two sentences, front-loaded with the core action. The first sentence states the purpose immediately; the second adds necessary prerequisite and error-context details without redundancy. Every clause contributes value, and there is no wasted 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?

The tool has a simple create-folder operation, no output schema, and annotations cover safety flags. The description explains the prerequisite (bucketName) and error interpretation, which is sufficient for basic usage. However, it does not mention the return value or behavior on duplicate folders, which would help the agent fully model the operation. Still, it is more complete than many tools at this complexity level.

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 each parameter (name, bucketName, parentPath) already described in the input schema. The description does not add semantic detail beyond what the schema provides, such as format constraints or examples. Baseline 3 is appropriate since the schema fully documents parameters.

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

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

The description clearly states the action: "Create a new folder at the given path in a drive." This is a specific verb+resource pairing that distinguishes it from sibling tools like upload_file or delete_files. The mention of 'given path' adds precision.

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

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

The description provides a key prerequisite: "Requires the drive (bucketName)," and explains the meaning of authorization denials. However, it lacks explicit when-to-use versus alternative tools, such as when to choose create_folder over upload_file or browse_folder. There is no mention of alternatives or conditions for non-use.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds significant context beyond that: the asynchronous queued behavior with a RequestId, background completion under ~2 minutes, verification via listing, the confirm=true requirement, and the RBAC authorization note. These are valuable behavioral disclosures not captured in 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 action, addressing requirements, async behavior, confirm requirement, and RBAC context. It's front-loaded with the destructive nature and key prerequisites. Slightly verbose but not wasteful.

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 destructive, asynchronous tool with no output schema, the description covers all necessary information: exact key and storageId requirements, id space pitfalls, background completion and verification, confirm requirement, and RBAC failure interpretation. An agent has everything needed to call it correctly without further clarification.

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% – all parameters have descriptions in the input schema. The tool description repeats some of that (storageId space note) but adds little new meaning for the parameters themselves. It clarifies the async behavior but that's not parameter-specific. Baseline 3 applies because 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?

Description states a specific verb and resource: 'Permanently delete one or more files/folders from a drive.' It also distinguishes itself from siblings by clarifying which id space is valid (StorageId from search_files/browse_folder/get_file_metadata, not list_files/recent_files), so an agent can tell this apart from other file operations.

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

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

Provides explicit when-to-use guidance: for permanent deletion, with exact addressing requirements, and the confirm=true prerequisite. It also warns against using ids from list_files/recent_files and explains the RBAC denial meaning, giving clear conditions for successful invocation. While it doesn't name an alternative tool, the instructions effectively prevent misuse.

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 and openWorldHint annotations, the description discloses that the URL is short-lived, grants read access to one object only, is time-limited, and returns the URL rather than the file bytes. This adds valuable behavioral context that the annotations do not cover.

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

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

The description is two sentences, front-loaded with the primary action, and each sentence earns its place: the first states purpose and requirement, the second explains behavior and return value. No wasted words.

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

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

For a simple URL-returning tool, the description fully covers what it does, what it requires, what it returns, and the key behavioral nuance (does not load bytes). With readOnlyHint and detailed schema, no essential context is missing.

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

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

The input schema has 100% description coverage for all parameters, so the schema already explains filePath, storageId, bucketName, and forceDownload. The description adds no parameter-level meaning beyond stating that bucketName is required, which is already in the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get a short-lived pre-signed download URL for a file.' It clearly states the action and result, and distinguishes itself from siblings by noting it does not load file bytes into the conversation, differentiating from upload or content-fetching 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 provides context (requires bucketName, URL is time-limited, share with care) but does not explicitly mention when to use this tool versus alternatives like share_link, nor does it state exclusion conditions beyond not loading bytes. The 'does not load file bytes' is more a behavioral fact than a usage guideline.

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 read/write and non-destructive nature. The description adds valuable context about server-side RBAC authorization and explains that a denial means missing scope, not a tool failure. However, it does not disclose naming conventions or behavior when a duplicate name exists.

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

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

The description is two sentences, front-loaded with the core action, and includes only necessary context about requirements and authorization. No wasted words.

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

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

The tool has no output schema, so the description should explain what the tool returns or what the copied file is named. It does not. While it covers purpose and auth behavior, the missing success-result info leaves a clear gap for a mutation tool.

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

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

The input schema provides 100% parameter coverage, including descriptions for objectKey, storageId, and bucketName. The description only reiterates the bucketName requirement without adding new syntax or format details, so it stays at the baseline 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 explicitly states 'Create a copy of a file in the same location', which is a specific verb+resource+location. It clearly distinguishes itself from siblings like move_file and rename_file by emphasizing same-location copying.

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 a clear prerequisite (requires bucketName) but provides no explicit guidance on when to use this tool versus alternatives like move_file or upload_file. Context is implied but not stated.

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

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

The description adds a list of returned metadata fields (size, type, timestamps, storage class) beyond what annotations declare. However, the readOnlyHint and openWorldHint annotations already cover safety, and the description does not disclose potential error conditions (e.g., not-found behavior, permission requirements). It provides modest added context but not rich behavioral detail.

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

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

The description is two sentences, tightly written, front-loaded with the primary action and clarifying scope. Every phrase earns its place without redundancy or fluff.

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

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

For a simple read-only metadata tool with well-documented parameters and annotations, the description is sufficient. It lists key metadata attributes and the required context (bucketName). It slightly lacks behavioral expectations like error handling or return format, but the simplicity of the tool and rich schema make it adequately complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the phrase 'by its object key' and 'Requires the drive', which loosely aligns with the schema, but it does not add new meaning beyond the already detailed schema descriptions for objectKey and bucketName. The schema carries the full parameter semantics.

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

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

The description clearly states the tool's function: 'Get detailed metadata for a single file or object' with specific attributes (size, type, timestamps, storage class). It distinguishes from siblings like get_file_tags (tags only) and list_files (multiple files), and the 'by its object key' qualifier clarifies the access method.

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

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

The description provides clear context for when to use the tool: for a single file/object, requiring the object key and the drive (bucketName). It does not explicitly name alternatives or exclusions, but the 'single' scope and reference to the drive give enough guidance. The sibling tool names (e.g., list_files, search_files) are implicitly differentiated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a read-safe operation and the output may depend on external factors. The description adds no further behavioral details beyond the purpose and the bucketName requirement; it does not mention error cases, empty results, or response format. With annotations covering safety, a neutral score is appropriate.

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

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

The description is a single, compact sentence that immediately states the action and the key requirement. There is no fluff or repetition; each phrase adds essential information. The structure is front-loaded and easy to parse.

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

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

Given the tool's simplicity, the description covers the core purpose and a critical prerequisite. No output schema exists, but the description implies the return concept (tags). The annotations cover the safety profile, and the schema fully documents parameters. Minor missing details like what an empty tag set returns are non-essential for this low-complexity tool.

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

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

The input schema provides thorough descriptions for both parameters: objectKey defines the full path, and bucketName explains the drive naming and default behavior. The tool description only restates these concepts ('by object key', 'requires the drive'), adding no new meaning beyond the schema. Since schema coverage is 100%, the baseline of 3 is justified.

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: 'Get the S3 object tags (key/value pairs) attached to a file, by object key.' This is a specific verb (Get) and resource (S3 object tags), and the 'by object key' scope distinguishes it from the sibling get_file_metadata, which presumably retrieves broader metadata.

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

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

The description gives clear context for when to use this tool: when you need to retrieve S3 object tags for a specific file identified by object key. It also notes the prerequisite of requiring the drive (bucketName), which helps the agent understand a necessary condition. It does not explicitly mention alternatives or exclusions, but the context is sufficient for basic selection.

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

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

Annotations already mark readOnlyHint=true, but the description adds genuinely useful behavior: it makes no API call, never reports the API key or secret, and reveals the stale-cache caveat. These are exactly the behavioral facts an agent needs beyond the structured 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 compact yet complete, front-loads the tool's core purpose, and each sentence earns its place—including the warning about stale tool lists. No filler or repetition of schema details.

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

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

For a no-argument, read-only introspection tool with no output schema, the description fully covers invocation constraints, behavioral side effects, and the key context about cached tool lists. 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?

There are zero parameters, so the schema carries no semantic load. The description explicitly confirms it takes no arguments, which is all that is needed. This earns the baseline of 4 for a parameterless tool.

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

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

The description names a specific verb ('Report') and a precise resource: the CloudSee Drive connector version, registered tool count, and configured API host. This clearly distinguishes it from the file-operation siblings, which all act on files or buckets.

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

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

It explicitly tells the agent to answer from the tool rather than from an assumed package version, and explains the stale-tool-list scenario that motivates this. This gives clear when-to-use guidance and prevents a common misuse.

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 convey readOnlyHint and openWorldHint, and the description adds meaningful context: results are filtered by caller permissions and the tool returns drive names used as identifiers elsewhere. This is useful behavioral detail beyond the annotation flags, though not exhaustive.

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

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

The description is two sentences, front-loaded with the action, and every clause earns its place. It is both concise 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 simple list tool with no schema and strong annotations, the description provides sufficient context: what is listed, permission scoping, usage order, and a critical naming convention. No return schema is needed because the description explains the key output field.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters; it instead clarifies the output semantics (Name = bucketName), which is valuable for downstream tool usage.

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

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

The description uses a specific verb 'List' and identifies the resource as 'drives registered to the authenticated CloudSee Drive account that the caller is allowed to see,' clearly distinguishing it from sibling file-level tools like list_files and browse_folder.

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

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

It explicitly instructs to use this tool first before browsing or searching, and explains that the returned 'Name' corresponds to the 'bucketName' expected by other tools. This provides direct guidance on when to use it and how it relates to alternatives.

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

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

Annotations already declare readOnlyHint=true, but the description adds substantial behavioral context beyond that: object ids are regenerated on every call, pages may be short or empty even when more results remain, and recursive-by-default behavior. This is exactly the kind of non-obvious runtime behavior an agent needs to avoid misusing results or terminating pagination early.

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 information-dense with no filler. It front-loads the core purpose and default behavior, then covers requirements, return content, pagination, and a critical id-stability warning — every sentence earns its place and the structure makes the most important caveat (unstable object ids) prominent.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does: names, sizes, storage classes, keys, and pagination. It also covers the full pagination loop and the unstable-id caveat, making the tool correctly invocable for a complete listing with no missing operational detail.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantic context for the cursor and bucketName parameters: it explains that the cursor must be followed until absent, warns that a page may be short/empty, and clarifies the bucketName requirement. It doesn't fully redefine each parameter, but it enriches the pagination semantics beyond the schema's one-line cursor description.

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

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

The description states a specific verb and resource ('List the files in a drive straight from storage') and clarifies the key behavior ('recursively by default'). It also distinguishes itself from siblings by asserting it is 'the most reliable way to see what a drive actually contains' and by warning that its object ids are unsuitable for mutation tools, implicitly contrasting with browse_folder/search_files/recent_files.

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

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

The description explicitly states the prerequisite ('Requires the drive (bucketName)') and gives precise operational guidance for pagination ('keep calling with the returned cursor until no cursor comes back'). It also names alternatives for a stable StorageId (search_files, browse_folder, get_file_metadata) and explicitly excludes recent_files, giving the agent clear when-to-use vs when-not-to-use signals.

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

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

The description goes well beyond annotations by disclosing asynchronous queued behavior ('returns a RequestId... completes in the background'), the destructive nature of a move, the confirm=true guard, RBAC denial semantics, and the id-space incompatibility of list_files/recent_files ids. This is rich, actionable behavioral information not available from the structured 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 front-loaded with the core action, then adds necessary caveats in a logical order: addressing, queued behavior, destructive semantics, and authorization. Every sentence earns its place; despite the length, there is no filler or repetition of 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 complex, destructive, async tool with no output schema, the description is complete: it explains the returned RequestId, the verification-by-listing pattern, the confirm requirement, the storage id constraint, the bucket prerequisite, and the meaning of RBAC denial. An agent has enough information to call the tool correctly.

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

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

The input schema already has 100% parameter coverage, so the baseline is 3. The description adds critical semantic detail beyond the schema, especially the warning that storage ids from list_files and recent_files belong to a different id space and will not work, and the note that bucketName is required unless a default bucket is configured. This makes parameter misuse less likely.

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: 'Move (or copy, with asCopy=true) a file or folder to a new location.' It distinguishes between move and copy, and adds the precise addressing requirement (object key plus storage id), which separates it from related sibling tools like rename_file or duplicate_file.

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

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

The description gives clear operational context: it explains when the tool is appropriate (moving/copying to a new location), how to verify completion, and the confirmation requirement for destructive moves. It does not explicitly name alternatives or state when not to use this tool, but the context is 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?

The readOnlyHint and openWorldHint annotations already convey that this is a safe read operation. The description adds useful behavioral context beyond those annotations: newest-first ordering and the explicit instruction to keep following the cursor until none is 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?

Two sentences with no filler: the first defines purpose, scope, and ordering; the second gives the necessary pagination instruction for complete traversal. Every sentence earns its place.

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

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

For a simple read-only list tool with zero required parameters and detailed schema descriptions, the definition is mostly complete: it covers what is listed, the ordering, and how to paginate through all results. There is no output schema, so a note on item shape would add value, but the absence does not prevent correct 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%, and the limit parameter is already richly documented, including the adaptive page-size behavior. The description adds little parameter-level meaning beyond reinforcing the cursor loop, 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 states a specific verb ('List'), a clear resource ('the account's most recently accessed or modified files'), and adds ordering ('newest first') and pagination. This cleanly distinguishes it from generic listing siblings like list_files and search_files.

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

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

The description provides a clear context: use this when you need recently accessed or modified files for the account. It does not explicitly name excluded alternatives, but the recency-focused framing is enough to guide tool selection among siblings.

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

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

Even though annotations already mark the tool as destructive and non-read-only, the description adds substantial behavioral context: it returns a RequestId and completes asynchronously, the StorageId becomes stale during the rename, and a permission denial means the API key lacks scope rather than a tool failure. This aligns with the annotations and adds real behavioral value.

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

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

The description is dense but not bloated; every major point (id source, async behavior, stale id, bucketName, confirm, RBAC) earns its place. It is longer than strictly necessary, but the added caveats are operationally important for safe invocation.

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 destructive asynchronous tool with no output schema, the description covers invocation prerequisites, completion timing, verification steps, and error interpretation. No critical operational information needed to call the tool correctly is missing.

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

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

Schema coverage is 100%, and the schema already documents storageId id-space caveats and confirm. The description reinforces these and adds operational meaning beyond the schema by warning that StorageId goes stale in flight and that delete_files/move_file depend on re-reading a fresh StorageId.

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 precise verb and resource ('Rename a file or folder in a drive') and distinguishes the required addressing mode: exact object key plus storage id. It also names the exact source tools that produce a compatible storage id, making it clear what this tool operates on.

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

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

The description conveys clear operating context: queued background execution, verify by listing until the new name appears, and the requirement for bucketName and confirm=true. It does not explicitly contrast with move_file as an alternative, so it stops short of full when-to-use versus when-not-to-use guidance.

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

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

Annotations already mark it as destructive and non-read-only, but the description adds critical context: confirm=true is required, the operation incurs retrieval cost, may take minutes to hours, and RBAC denials are scope errors rather than tool failures. It also clarifies this is Glacier un-archiving, not file recovery. 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 four sentences, front-loaded with action and resource. Each sentence earns its place: action, prerequisite, clarification/cost/time, and confirmation/auth behavior. There is no filler or redundant restating of the title or 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?

The description covers prerequisites, side effects, cost, latency, auth behavior, and the mutating nature requiring confirmation. The only gap is that with no output schema, it does not mention what the tool returns (e.g., job status or async tracking), which would be useful for an operation that takes minutes to hours. Overall, it is quite complete for selection and invocation.

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

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

The input schema already covers all six parameters with 100% description coverage, so the baseline is 3. The description adds value by emphasizing the bucketName prerequisite and the confirm=true gate, reinforcing critical parameters beyond their schema descriptions. It does not redundantly restate each parameter, making it useful emphasis rather than repetition.

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: 'Begin restoring an archived (S3 Glacier) object so it can be downloaded.' It further distinguishes itself with 'NOT recovery of a deleted file,' clearly separating it from deletion/recovery tools. The purpose is unambiguous and distinct from sibling tools like download_file or delete_files.

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

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

Explicitly describes when to use: to restore an archived object for download. Provides exclusions ('NOT recovery of a deleted file'), states required prerequisites (bucketName, confirm=true), and warns of cost/time implications. This gives clear decision-making guidance beyond simply naming the action.

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 and openWorldHint, but the description adds crucial behavioral nuance beyond them: the pagination contract that a page may be short or empty while more results remain. This prevents a real failure mode (premature termination) and gives actionable guidance 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?

Every sentence earns its place: the first states the core function, the second a prerequisite, and the third the critical pagination behavior. It is front-loaded with the key warning and contains no filler or redundant restatement of the title.

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

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

The description is complete enough for a read-only search tool: it covers prerequisites, pagination loop, and termination condition. The main gap is that it doesn't specify match semantics (substring vs. exact, case sensitivity, wildcards), which could matter to an agent, and it doesn't describe the result payload since there is no output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds semantic value by explicitly noting bucketName is a requirement (unless a default is configured) and by clarifying that cursor existence, not page content, signals more results. These details amplify the schema's own parameter descriptions.

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

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

The description uses a specific verb ('search') with a specific resource ('files and folders by name keyword') and adds the distinguishing qualifier 'within a drive (the indexed view)'. This clearly separates it from generic list/browse tools and makes its function 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 implies when to use it (when searching by name keyword) and provides a strong usage pattern around pagination, but it never explicitly contrasts it with sibling tools like list_files or browse_folder. There are no 'when not to use' exclusions or alternative routing, leaving some ambiguity.

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

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

The description goes well beyond the annotations by disclosing that this is a write that publishes the file to anyone with the link until expiry. It also states that no tool can list or revoke shares, and that the only revocation path is the dashboard. This is exactly the kind of behavioral context an agent needs.

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 with no filler: purpose, requirements, return value, and critical side-effect warning. The warning is placed at the end where it still reads naturally and is easy to retain.

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?

Even without an output schema, the description explains what is returned: a CloudSee share page URL, its expiry, and a share id. Combined with 100% schema coverage and annotations covering mutation and non-idempotence, an agent has everything needed to call the tool correctly and set expectations about irreversibility.

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 restates the expireTime default and cap and the conditional bucketName requirement, both of which are already present in the schema. It adds little new meaning beyond the structured parameter documentation.

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

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

The description opens with a specific verb and resource: 'Create a shareable link to a file.' It clearly distinguishes this tool from sibling tools like download_file, move_file, and delete_files because it is the only one about creating public share links.

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

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

The description gives clear operational context: use this tool to create an expiring shareable link, with the bucketName requirement and expiry defaults explained. It also warns that listing or revoking shares is not possible through this or any tool, directing revocation to the CloudSee dashboard. It does not explicitly name alternative tools, but there are no sharing siblings, so the usage context 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 signal mutating/destructive behavior, and the description adds substantial context beyond that: merge vs replace destructive cases, ETag/LastModified side effects, the S3 copy rewrite, size limits, the confirm preview mechanism, and the RBAC denial meaning. This gives the agent a precise model of the tool's side effects.

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

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

The description is long and dense, but nearly every sentence carries essential behavioral or safety information. The opening sentence front-loads the core purpose, and the later sentences earn their place by covering destructive cases, side effects, and constraints.

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

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

For a complex mutation tool with nested objects, no output schema, and destructive annotations, the description is remarkably complete. It covers prerequisites, mode semantics, destructive edge cases, server-side authorization, size limits, and post-update side effects like ETag changes and multipart copy.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic value beyond the schema: the storageId id-space warning, the tags: [] destructive case, the field-clearing semantics, and the S3 copy implication. It reinforces and expands on the schema descriptions rather than merely repeating them.

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 ('Update'), an explicit resource ('a file's metadata (category / description / project) and tags in a drive'), and the addressing requirement (storageId). It also distinguishes itself from the read-oriented sibling tools by naming the correct id source and explicitly excluding list_files and recent_files ids.

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

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

Provides clear context for correct invocation: requires bucketName and confirm=true, explains the default merge behavior, and identifies the only way to remove a single tag. It does not explicitly enumerate when to prefer this tool over alternatives, but no sibling tool performs metadata updates, so the guidance is sufficient.

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

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

Beyond annotations, the description discloses several non-obvious behaviors: the file is read from the local machine, files over 8 MiB are split automatically, existing files are never overwritten, indexing is asynchronous, and RBAC denials indicate a scope issue rather than a tool failure. This is exactly the behavioral context an agent needs.

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 each subsequent sentence covers a distinct, operationally relevant behavior. It is dense but every clause earns its place, including the parenthetical RBAC clarification.

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?

It covers the local-path requirement, bucket requirement, size handling, collision behavior, async indexing, and auth errors—most of what an agent needs to invoke this correctly. The only notable gap is the absence of an explicit statement about the tool's return value or confirmation of success, and no output schema is provided to fill that 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?

Input schema coverage is 100%, so the schema already documents all five parameters. The description adds useful context for localPath and bucketName and explains collision behavior related to fileName, but it does not add meaning beyond the schema for storageClass or destinationFolder.

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 action and resource: 'Upload a file into a folder of a drive.' This is unambiguous and clearly distinguishes it from siblings such as download_file, move_file, and create_folder.

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

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

The description makes the intended use clear: upload a local file into a drive folder when you have its path. It also gives strong operational guidance, such as verifying with browse_folder/search_files/list_files instead of re-uploading while indexing lags, but it does not explicitly contrast this tool with alternative creation or upload 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?

Beyond the readOnlyHint annotation, the description discloses that the tool reads progress held in the server process and makes no API call, making it safe to poll. It also explains that RBAC denials reflect API key scope, not tool failure, which prevents misinterpretation of errors.

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 tightly-packed sentences cover purpose, input, behavior, state semantics, safety, and error interpretation. Every sentence contributes meaningful information, and the most important usage guidance appears at the beginning.

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

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

With no output schema, the description partially compensates by enumerating the possible states and their meaning. It does not specify the exact response shape or whether progress percentages, timestamps, or other details are returned, but for a simple status-checking tool with one optional parameter, the provided context is nearly sufficient.

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 fully documents uploadId, including the instruction to omit it to list all tracked uploads. The description essentially restates the schema's parameter guidance, adding no substantially new semantics, 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 states the tool's purpose: report progress on an upload started by 'upload_file' that was too large to finish in one call. This distinguishes it from the many file-list and metadata siblings, and the title reinforces the same function without being the sole source of meaning.

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

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

The description explicitly tells the agent when to use the tool, what input to provide (the uploadId returned by upload_file), and what happens if omitted (list every tracked upload). It also gives the key behavioral rule: a file is only in the drive once its upload reports completed.

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