stagenth · file-relay

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

With no annotations, the description must reveal behaviors. It discloses recursive creation (mkdir -p) and idempotency, which are key. It does not mention permissions, error cases beyond idempotency, or limitations, but for a folder creation tool, this is adequate.

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

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

The description is concise (two short sentences) and front-loaded with the primary purpose. It avoids unnecessary detail but could be slightly expanded without losing conciseness. Every sentence 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 tool's simplicity, one required parameter, and presence of an output schema, the description is sufficiently complete. It explains core behavior and idempotency. It could mention authentication or path constraints, but the schema already covers path format.

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

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

The input schema has 100% coverage and a very detailed parameter description. The tool description adds the mkdir -p analogy and idempotency, which reinforce the parameter semantics. Together, they provide rich meaning beyond just the schema.

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

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

The description clearly states the tool creates folders, using the analogy '类似 mkdir -p'. This distinguishes it from sibling tools like delete_folder, list_folders, and rename_folder. The idempotency behavior is also mentioned, adding specificity.

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 explains that the tool is idempotent and behaves like mkdir -p, which gives clear usage context. However, it does not explicitly state when not to use it or suggest alternatives, though the sibling tool set provides some implicit 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?

With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states the action without describing side effects (e.g., link creation, access implications, or whether the operation is reversible).

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, efficient sentence with no unnecessary words. It is front-loaded with the key action. However, it lacks any structure or additional details that could be included without bloat.

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 4 parameters and presence of an output schema, the description covers the basic purpose. However, it omits contextual details such as how the link behaves, constraints on file types, or relationships to other file operations.

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. The tool description adds no additional meaning beyond that provided by the schema, so it meets the baseline but does not enhance understanding.

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: generating a share link for a file. The verb '生成' (generate) and resource '分享链接' (share link) are specific. It is distinct from sibling tools, none of which create 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?

No guidance on when to use this tool vs. alternatives. No mention of prerequisites (e.g., file must exist or be owned), exclusions, or contexts where other tools are preferred.

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?

No annotations are provided, and the description only says 'Delete a file.' It does not disclose behavioral traits like irreversibility, permission requirements, or effects on shares. The description carries full burden and is insufficient.

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

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

The description is a single, clear phrase with no wasted words. It is appropriately concise for a straightforward tool.

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

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

Given that this is a potentially destructive operation with sibling tools and an output schema, the description is too brief. It lacks details on return values, side effects, and prerequisites, making it incomplete.

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% (file_id described as 'File Id' with Chinese description), and the description adds no extra meaning. Baseline 3 is correct since the schema does the heavy lifting and no additional value is provided.

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

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

The description clearly states the action (delete) and the resource (file), but it does not distinguish this tool from sibling tools like 'delete_folder'. A score of 4 is appropriate because it is specific but lacks differentiation.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., move_file or rename_folder). The description offers no context for when to delete vs. other operations.

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

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

With no annotations provided, the description carries the full burden of disclosure. It explains the soft-delete behavior, the 30-day retention period, and the recovery option via recycle bin. This goes beyond a simple 'delete' and gives the agent important safety and lifecycle information. The description is particularly transparent about the handling of 'ready/locked' files.

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 concise: one sentence for the core action and one for the critical behavioral detail. It front-loads the action and then adds nuance. It is slightly sparse in terms of use cases, but given the schema covers parameter details, this level of conciseness is effective.

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 (deletion with soft-delete workflow) and the existence of an output schema (which presumably documents return values), the description provides enough information for correct invocation. It covers the key behavioral aspects not in the schema: the soft-delete and recovery window. However, it does not mention any security or permission requirements, which could be a minor 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?

The input schema has 100% coverage with descriptions for both parameters. The tool description adds context about the overall deletion behavior (soft delete, recycle bin) but does not add specific parameter-level meaning beyond what the schema provides. Baseline score of 3 is appropriate since schema covers parameter semantics well.

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: deleting a folder, and provides an analogy to Unix commands (rmdir/rm -r). It distinguishes this from file deletion by mentioning the behavior for internal files, which adds specificity. The name 'delete_folder' itself is clear, and the description reinforces it with concrete examples.

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 does not explicitly state when to use this tool versus alternatives like delete_file. However, the context of sibling tools (delete_file, move_folder, etc.) implies that this is for folders. The description mentions recursive vs non-recursive behavior, which helps users choose the right mode, but no direct comparison to other tools is provided.

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

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

With no annotations, the description compensates well by disclosing rate limiting (membership-based speed), zero side effects (no share record), and content type mapping. Mentions signed URL validity (15 minutes) and auth-free access for resource_link. Missing details on error handling and auth requirements, but overall informative.

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 structured with bullet points and sections, but it includes excessive implementation details (e.g., 'astream_file', route path) that may not be necessary for an AI agent. While front-loaded with purpose, it could be more 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?

Covers content types, rate limiting, and side effects. With an output schema (not shown), the description appropriately focuses on behavior. However, lacks error scenarios, validation of parameters, and size limits. Adequate but not exhaustive for a 3-parameter tool.

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

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

Schema description coverage is low (33%). The description adequately explains 'as_text' (only for text/code files, ignored by others). However, it fails to describe 'file_id' and 'file_uuid' parameters, not clarifying that at least one is needed or their relationship. Does not compensate for the coverage gap.

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 '下载一个文件' (download a file) and details the MCP content type selection based on file category. It differentiates from sibling 'download_shared_file' by emphasizing zero side effects (no share record). However, it could more explicitly contrast with other download-related 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?

Provides guidelines on when to use each content type and explains the 'as_text' parameter behavior. Lacks explicit guidance on prerequisites (e.g., must provide file_id or file_uuid) and does not mention scenarios where this tool should be avoided. No comparison with alternatives like 'get_file_info'.

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 no annotations, the description carries full burden. It discloses that the tool does not consume user storage quota and counts towards the sharer's monthly traffic. It implies the download returns file content for direct reading. No side effects are mentioned, but the behavior is adequately transparent.

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

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

The description is brief (two sentences) and front-loads the core purpose. Every sentence adds value: purpose, usage scenario, storage/traffic behavior. No extraneous 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 that an output schema exists (not shown), the description does not need to explain return values. It covers purpose, usage, and key behavioral traits. It could mention error cases or link validity, but it is fairly complete for a tool with well-documented parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no new information beyond what the schema already provides for each parameter, though it reinforces the context of share_uuid and hints that as_text relates to content reading.

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: downloading a file via a share link without needing to be the owner. It distinguishes from sibling tools like download_file (which likely requires ownership) by specifying the shared link mechanism and usage scenario.

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 usage context: when someone sends a /s/<uuid> link for AI to read content. It implies not to use for own files, and notes storage and traffic behavior. However, it does not explicitly exclude alternatives like import_shared_file.

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

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

No annotations provided; description is minimal but implies a harmless read operation. It does not detail potential errors or scope of 'details'.

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

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

Two concise sentences with no wasted words, purpose 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?

Output schema exists, so return values are covered. Description adequately covers purpose and parameter usage for a simple query tool.

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

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

Schema covers both parameters fully; description adds 'one of' constraint, adding value beyond schema. Baseline 3 plus credit.

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 (query details) and resource (single file), and the 'one of' parameter constraint distinguishes it from list/search siblings.

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

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

The description indicates when to use (when you have file_id or file_uuid) but lacks explicit guidance on when not to use or 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?

No annotations provided, so description carries full burden. Describes output format including a truncated flag, but does not explicitly state read-only nature or other behavioral traits like performance limits.

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?

Extremely concise: one sentence of purpose followed by a code block. No wasted words, front-loaded with key 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 tree-view tool with full schema coverage and output format provided in description, it is reasonably complete. Could mention read-only nature, but overall 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?

Schema coverage is 100% with parameter descriptions. The description adds little beyond the schema; the sample output helps understand parameter effects but does not explain parameters directly. 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?

Description clearly states it returns an ASCII tree of folder/file hierarchy. Recommends use when user asks about directory structure, distinguishing it from sibling tools like list_files and list_folders.

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 recommends use when user asks about directory structure. No explicit when-not-to-use or alternatives, but context is clear and helpful.

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?

No annotations are provided, so the description must disclose behavioral traits. It states '查看' (view), implying read-only, but does not explicitly confirm no side effects, no authentication requirements, or any limitations like caching or rate limits. For a tool with no annotations, this is insufficient.

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

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

The description is a single, clear sentence with no unnecessary words. It is front-loaded and to the point.

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, zero-parameter query tool with an existing output schema, the description is complete enough. It tells the agent exactly what the tool does.

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

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

The tool has zero parameters and the schema description coverage is 100% (no parameters to describe). The description does not need to add parameter details. With zero parameters, a baseline of 4 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 tool retrieves the current user's storage quota usage (查看当前用户的存储配额使用情况). It is a specific verb ('查看/view') and resource ('存储配额使用情况/storage quota usage'). Among sibling tools, no other tool appears to relate to quotas, so it distinguishes well.

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 used for checking quota, but it provides no explicit guidance on when to use it versus alternatives, nor any exclusions. Given it is a simple zero-parameter tool, the usage context is clear, but the description could be enhanced with a hint that this is the definitive source for quota information.

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 no annotations, the description carries the full burden and adequately discloses key behaviors: server-side copy, quota/whitelist/dedup checks, traffic counting, and storage impact. It lacks mention of error handling or preconditions but provides substantial behavioral 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 concise, uses bullet points effectively, and front-loads the primary action. Every sentence adds value without redundancy.

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

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

Given the presence of an output schema, the description does not need to explain return values. It covers quota, traffic, and performance implications, but could mention error conditions. Overall, it is fairly complete 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?

Schema coverage is 100% and both parameters are described adequately in the schema. The description does not add extra parameter details, but the baseline of 3 is appropriate since the schema already covers the necessary 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 verb 'import' and the resource 'shared file', and distinguishes it from downloading by explaining it adds the file to the user's file list. This differentiates it from the sibling tool 'download_shared_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 implies when to use this tool (to import a shared file into the user's account) but does not explicitly state when not to use it or compare to alternatives. The context is clear enough for an agent to infer.

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?

No annotations are provided, so the description carries the full burden. It discloses key behaviors: recursive traversal by default, return includes 'subfolders' and 'has_subfolders', each item has a 'folder_path' to avoid confusion from recursion. It does not mention pagination or performance implications, but the information provided is sufficient for safe use.

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 well-structured and front-loaded: the first sentence states the main purpose. It uses line breaks to separate key points without unnecessary words. Every sentence adds value, including the hint about get_folder_tree and the note about folder_path preventing confusion.

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 moderate complexity and the presence of an output schema (which likely documents return values), the description covers essential aspects: default behavior, return structure, parameter guidance, and alternative tool. It leaves no critical gaps for an agent to misunderstand.

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

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

Schema description coverage is 67%, with page and size lacking descriptions. The description adds context for folder_path (default '/', use list_folders to explore) and recursive (default true, keep true for 'all files'). It also explains the return structure, which aids understanding of parameter effects. It partially compensates for missing 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 clearly states that the tool lists the current user's files with recursive traversal by default. It distinguishes itself from the sibling tool get_folder_tree by noting that for directory tree visualization, get_folder_tree is more appropriate. The verb '列出' (list) and resource '文件' (files) are specific.

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 mentions an alternative tool (get_folder_tree) for when the user asks about directory structure or tree. It implies the default recursive behavior and suggests using list_folders to probe available paths. This provides clear guidelines on when to use this tool versus 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?

With no annotations, the description carries full burden. It discloses the error behavior and implies read-only nature (listing). The recursion behavior is described in the schema. It does not mention any destructive actions or permissions, but for a listing tool, this is sufficient.

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

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

The description is extremely concise: three short sentences that convey purpose, error handling, and alternative tool. Every sentence is valuable and 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 and covers return values, the description adequately covers purpose, behavior, error, and alternative. It is complete for a simple listing tool with no required parameters.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds the analogy to `ls -d` which provides semantic context, but does not elaborate on parameters beyond what the schema already provides. No significant added value.

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

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

The description clearly states the tool lists folders, analogous to `ls -d`, and explicitly distinguishes it from `list_files`. The error condition is also mentioned. This is specific and distinguishes from siblings.

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

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

The description gives explicit guidance: use this to list folders, and use `list_files` for files. It also mentions the error when path does not exist, indicating when not to use it (if path might be invalid).

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 explicitly states that the operation only changes the logical path, not the OSS bytes, and completes in milliseconds. This adds valuable behavioral context beyond the basic 'move' verb, compensating for missing 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 concise: two sentences, no fluff. The purpose is stated first, followed by a key behavioral detail. 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 core behavior and performance, but omits potential error scenarios, permissions, or output structure. However, the presence of an output schema reduces the need to describe returns. A bit more context about prerequisites would improve it.

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

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

With 100% schema coverage, baseline is 3. The description does not add significant detail beyond what the schema already provides for each parameter. The analogy helps with understanding but does not enhance 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 moves a file to a specified folder, using an analogy to Unix `mv`. The verb 'move' and resource 'file' are specific, and the sibling 'move_folder' implicitly distinguishes the scope.

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

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

No guidance on when to use this tool versus alternatives like 'move_folder' or 'create_folder'. The description does not mention prerequisites, error conditions, or when not to use 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?

No annotations provided, so description carries full burden. Discloses recursive logical path update and that OSS bytes are not moved (no payload movement). Does not mention permissions, rate limits, or synchronicity. Adds value but leaves gaps.

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 an example. No redundant information. Front-loaded and efficient. Every sentence 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?

Output schema exists, so return values not needed. Covers purpose, behavior, and parameter meaning. Could mention constraints like no cross-filesystem moves or subtree moves, but otherwise adequate for 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 covers all parameters. Description adds extra context: example usage, note that rename is separate for target_parent_path, and explanation of auto_create_folders. Provides meaning beyond 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?

Description clearly states the tool moves a folder, analogous to 'mv' command. It specifies recursive update of logical paths and that OSS bytes are not moved. This distinguishes it from siblings like move_file and rename_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?

Provides an example of usage and clarifies that renaming should use rename_folder. However, lacks explicit when-not-to-use or prerequisites. Context with sibling tools helps but not explicitly 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?

No annotations are provided, so the description must carry the full burden. It only states 'do not move parent,' but discloses nothing about permissions, side effects, or failure modes. Minimal behavioral 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 very concise (single phrase) but lacks structure or additional context. It is front-loaded, but its brevity sacrifices completeness, making it more under-specified than efficiently concise.

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

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

Given the simplicity of the tool (2 params, high schema coverage, no annotations, output schema exists), the description is insufficient. It does not explain return values, constraints like no duplicate names fully, or error conditions.

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 no additional meaning beyond what the schema provides. The schema itself has descriptions in Chinese, but the tool description offers no extra 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 '改名 (不动 parent)' clearly states the action (rename) and resource (folder), and the parenthetical 'do not move parent' distinguishes it from the sibling move_folder tool. However, it could be more explicit about the resource type.

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

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

No explicit guidance on when to use this tool versus alternatives. The phrase '不动 parent' implies it differs from moving, but there are no when-to-use or when-not-to-use instructions.

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 no annotations, the description carries the full burden. It covers security constraints (public-only) and basic behavior (fetching, format conversion). However, it lacks information on error handling, timeouts, concurrency, or rate limits. This is adequate but has gaps.

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 long, front-loading the main purpose and then adding key constraints. Every sentence earns its place with no redundant 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 three parameters and an output schema. The description covers the core function, output format, and usage constraints. It does not describe the output schema in detail, but that is provided elsewhere. For a straightforward web scraping tool, the information is largely 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 baseline is 3. The description adds a critical constraint on the url parameter (only public web pages), which goes beyond the schema's description. This adds meaningful context, raising the score to 4.

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

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

The description clearly states the tool fetches a public web page and returns clean Markdown for AI use. It uses a specific verb (抓取/fetch) and resource (公开网页/public web page), and the purpose is well-defined. The sibling tools are all file/folder operations, so there is no ambiguity.

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 when to use (public web pages) and when not to use (intranet/reserved addresses), along with a clear prohibition. It also clarifies that the tool does not generate content, only fetches and converts. This provides strong guidance for 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?

With no annotations provided, the description carries the full burden. It discloses the scope (current user's files) but does not disclose whether the search covers file content or metadata only, nor any other behavioral traits like potential rate limits or pagination. It adds some context beyond the schema but not enough.

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

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

The description is a single concise sentence with no wasted words. It could be improved by adding structure (e.g., bullet points) but is already efficient.

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

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

Given the tool's simplicity (2 parameters, output schema present), the description is minimal but sufficient. It states the core functionality but leaves questions about search scope (metadata vs. content) unresolved. The output schema helps but the description could be more complete.

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

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

Schema description coverage is 50%: the query parameter has a description, while limit lacks one. The tool description does not add any parameter-specific information. Baseline for 50% coverage is 3, as it is not low (<50%) but the description does not compensate.

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 searches in all files of the current user, using the specific verb 'search' and resource 'files'. This differentiates it from sibling tools like list_files (which lists files) or get_file_info (which retrieves a single file).

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

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

The description provides no guidance on when to use this tool versus alternatives like list_files or get_file_info. There is no mention of context, prerequisites, or 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?

No annotations provided, so the description carries full burden. It discloses concurrency, server-side index recording, and idempotency on retry. Missing details like failure modes, session expiration, or rate limits, but covers key behavioral traits.

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. Front-loaded with the tool's purpose and step position. Every sentence 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 tool complexity (part of a multi-step upload, concurrency, idempotency), the description covers concurrency and retry behavior. It assumes knowledge of upload_init for session_uuid and chunk_size. Output schema presence reduces need for return value explanation. Lacks explicit error handling info but adequate overall.

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% (3 parameters described). The description adds value beyond schema by explaining chunk index range (last = total_chunks-1) and data size constraints (matches chunk_size from upload_init). This aids correct 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 clearly states 'upload a single chunk' and identifies it as Step 2 of 3, making the verb and resource specific. It distinguishes from sibling tools that handle folders, shares, or 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?

The description mentions it is Step 2 of 3, implying a sequence with upload_init and upload_complete, and notes concurrency and retry safety. However, it does not explicitly state prerequisites or when not to use this tool, though the step context is helpful.

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?

No annotations provided, so description carries full burden. It discloses both behavioral paths (OSS server-side merge vs local merge), memory/bandwidth implications, and what is returned (final file metadata). This is comprehensive for a completion step.

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?

Description is well-structured with a clear purpose, bullet points for paths, and a final output line. Every sentence is meaningful and front-loaded with the core action. No wasted text.

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 complexity (multi-step process, two modes) and the presence of an output schema, the description is complete. It explains both paths, their trade-offs, and explicitly lists the return fields. No gaps observed.

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%, baseline 3. The description adds value by explaining the parts parameter with examples and behavior (e.g., '传了 parts 走 OSS...'), and session_uuid is clearly linked to upload_init. This exceeds what the schema alone provides.

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

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

The description clearly states it merges all shards (step 3 of 3) and distinguishes between direct and transit paths. It uses specific verbs and resources, and the context distinguishes it from sibling tools like upload_init and upload_chunk.

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

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

Explicitly states it's step 3, describes two paths with detailed guidance on when to use each (recommended for shim), and implies when not to use (e.g., not for initial upload or chunk upload). Alternatives are clear through 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?

With no annotations provided, the description carries the full burden. It mentions the upload process and size limit but fails to disclose error handling, overwrite behavior, or authentication requirements. The existence of an output schema partially compensates, but 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 concise and front-loaded with the main purpose. It uses a few sentences to convey process, size limits, and parameter notes without redundancy, though structure could be slightly improved.

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 complexity, schema coverage, and presence of an output schema, the description is largely complete. It covers purpose, usage context, and key parameter behavior, though it omits error scenarios and idempotency 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 coverage is high (80%), so the baseline is 3. The description adds value by clarifying the folder_path and auto_create_folders behavior, but does not significantly enhance understanding of filename or content_base64 beyond the schema.

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

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

The description clearly states it uploads a file in base64 format, using a specific process (init + single chunk + complete). It mentions size limits and folder path, distinguishing it from related tools like upload_chunk and upload_init.

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 size guideline (suitable for files <20MB) and advises using web-based chunked upload for larger files. It also explains the folder_path parameter. However, it does not explicitly state when not to use this tool versus upload_chunk or other 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?

No annotations are provided, so the description carries the full burden. It clearly explains the two possible return scenarios: instant (file metadata) and non-instant (session_uuid with chunk info), and the subsequent steps. It does not cover error conditions or rate limits, but is adequate for a multi-step upload initiation.

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 concise: one sentence stating purpose, followed by bullet points for return handling. No redundant information, and the key 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?

The description explains the overall workflow as step 1 of 3 and references upload_chunk and upload_complete. With an output schema available, the agent can get return field details. It does not cover error handling or session expiry, but provides sufficient context for a multi-step process.

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 83%, so the baseline is 3. The description does not add additional meaning to parameters beyond what the schema already provides; it focuses on usage flow rather than parameter details.

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 '发起分片上传会话 (第 1 步 / 共 3 步)' (initiate a chunked upload session as step 1 of 3), specifying the verb and resource. It distinguishes from siblings like upload_chunk, upload_complete, and upload_file by framing it as the first step of a multi-step process.

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 (as the first step of chunked upload) and what to do based on the instant flag. It also implicitly differentiates from a direct upload (upload_file) by describing the chunked flow, but lacks explicit when-not-to-use or alternative tool mentions.

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