Send a local file to a specified QQ group with a custom display name, and optionally place it in a target group folder.
向指定 QQ 群上传群文件 (NapCat OneBot 11: upload_group_file)。 :param group_id: 目标 QQ 群号 :param file_path: 本地文件的绝对路径 :param file_name: 群文件中显示的文件名 :param folder: 目标群文件夹 ID (可选，不填则上传至群文件根目录)
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | 目标群文件夹 ID (可选，不填则上传至群文件根目录) | |
| group_id | Yes | 目标 QQ 群号 | |
| file_name | Yes | 群文件中显示的文件名 | |
| file_path | Yes | 本地文件的绝对路径 |
Changes observed during successful MCP inspections.
v1.1.0Input schema / additionalPropertiesAdded value: +falsev1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses only the folder default (root directory when omitted); it says nothing about required bot permissions, file size limits, overwrite behavior for duplicate names, or what the call returns. For an upload/mutation tool with zero annotation coverage this is a significant gap.
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?
Purpose is front-loaded in one line, followed by a compact parameter list. It is efficient, though the parameter block duplicates the schema and therefore does not earn its space fully.
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?
A 4-parameter mutation tool with no annotations and no output schema should state permissions, size/type constraints, and error conditions. Only the optional folder default is covered, leaving an agent unable to predict failure modes when calling 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?
Schema description coverage is 100%, and the description's :param block merely restates the same text verbatim, adding no format, validation, or example detail. Baseline 3 is correct when the schema already documents every parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
State a specific verb and resource ('向指定 QQ 群上传群文件') with the scope qualifier '群' that separates it from private-file operations. It also anchors the tool to the NapCat OneBot 11 action name, but it never names a sibling tool explicitly the way a 5 would.
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 required vs optional parameters but gives no guidance on when to use this versus alternatives such as upload_private_file, nor any prerequisites (bot permissions, group membership, file size limits). Usage must be inferred entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.