Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@napcat-mcp Send a message to QQ group 123456789 saying: 你好，世界"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
把 NapCat / OneBot v11 的接口暴露成 MCP 工具，并附带一个 LLM 驱动的智能 QQ 机器人（SmartBot）。
MCP Server：把 45 个 OneBot 动作注册为 MCP 工具，供任意 MCP 客户端调用。
SmartBot：常驻 QQ 机器人。支持多群/私聊、长期记忆、知识库、工具调用、 原生联网搜索、多模态识图、主动插话、权限（主人/管理）分级、审批加群/加好友、 群文件操作、联通云盘（沃盘）集成等。
Node.js ≥ 21（依赖内置 node:sqlite；开发使用 Node 24 验证）
一个可用的 NapCat（或其它 OneBot v11 实现），开放 WebSocket 服务
（可选）DeepSeek 或任意 OpenAI / Anthropic 兼容的 LLM API
Related MCP server: NapCat MCP Server
npm install
# 配置
cp config.example.json config.json
# 编辑 config.json：填 wsUrl / token、bot.owner、bot.admins、bot.llm.apiKey 等
# 人设：复制 persona.example.txt 为 persona.txt 并改写，config.json 用 bot.personaFile 指向它
npm run build
# 只跑 MCP server（stdio）
npm run start
# 跑 QQ 机器人
npm run start:bot:bg # 后台启动（pid → .bot.pid，日志 → logs/bot.out.log）
npm run status:bot
npm run stop:botsrc/
index.ts MCP server 入口
config.ts log.ts onebot.ts download.ts types.ts
tools/ MCP 工具（definitions / common / index）
integrations/wopan/ 联通云盘纯 TS 实现（crypto / client / fs）
bot/
index.ts SmartBot
prompt.ts 系统提示词组装
tools.ts 工具聚合入口
tools/ 支撑模块（requests / risk / own / images / catalog）
toolsets/ 按域拆分的工具集（admin/social/web/... + extended + wopan）
brain.ts memory.ts kb.ts search.ts web.ts ssrf.ts fsaccess.ts fileserver.ts ...
docs/ 接口覆盖情况等文档
scripts/bot-bg.mjs 后台启停脚本工具系统：bot 侧工具按风险分级（low / manage / high），执行前在代码里强制校验；
工具较多时启用「工具字典」懒加载——模型用 list_tools 查目录、describe_tool 查用法，
避免每轮把全部工具 schema 塞进上下文（见 bot.lazyTools）。
记忆 / 知识库：SQLite（memory.db / kb.db），全局时间线 + 摘要压缩 + 用户画像。
联通云盘：src/integrations/wopan 为纯 TypeScript 实现（协议参考见 docs/wopan/）。
配置在 config.json 的 bot.wopan：
"wopan": { "enabled": true, "tokenFile": "vendor/wo_cnpan/tokens.json", "space": "personal" }tokenFile 也可用环境变量 WOPAN_TOKENS 指定；space 可选 personal/family（家庭云再配 familyId）。
相关工具全部 risk=high（仅主人可用）；enabled:false 则不注册这些工具。
隐私：config.json、persona.txt、*.db、logs/、downloads/、sandbox/、
.private/ 均已在 .gitignore 中，不会入库。
本项目仅供个人学习与技术研究使用。
联通云盘（沃盘）部分基于对公开 Web 端的协议分析，请遵守对应服务条款，不要用于批量抓取、
规避限速或其它违规用途；其中的 CLIENT_ID / CLIENT_SECRET 为官方客户端常量。
使用本机器人时请遵守所在平台规则，并注意不要泄露他人隐私数据。
按 message_id 撤回一条自己发送的或具有管理权限的消息。
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | 消息ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false; the description supplements this by identifying exactly what is affected (the recalled message) and the authorization precondition. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, information-dense sentence that leads with the action and resource and then gives the eligibility condition. There is no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive action, the description covers what is deleted, the key needed, and the permission boundary. The absence of an output schema is not a gap here because the operation's effect and precondition are fully specified.
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 message_id is already described as 消息ID. The description only repeats that the operation is keyed by message_id, adding no additional format, type, or constraint information.
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 concrete action (撤回) applied to a specific resource (a message identified by message_id) and adds a scope/eligibility condition (own message or admin permission). This is immediately distinguishable from sibling get/send/set tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states precisely when the tool can be used: only for messages sent by the caller or messages the caller has permission to manage. This implies the main exclusion (other users' messages without admin rights), though it does not name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取机器人QQ收藏（自定义）的表情包图片URL列表，可用于再发送。
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | 获取数量，默认48 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
注解已声明readOnlyHint=true和destructiveHint=false，描述与其一致，无矛盾。描述说明了返回URL列表，但未提及可能的错误或限制。由于注解覆盖了安全特性，描述添加的价值有限，但提供了基本行为信息。
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?
描述为单句，简洁且直接，无冗余内容。虽未包含使用场景细节，但整体结构清晰，适合简短工具。
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?
工具简单（一个可选参数），注解提供了安全信息，描述说明了返回内容和用途。没有输出模式，但描述已指出返回URL列表，基本完整。缺少对返回格式或分页的说明，但考虑其简单性，评为4分。
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?
输入模式对参数count有完整描述（获取数量，默认48），覆盖率100%。描述本身未额外解释参数，但模式已充分说明，因此维持基线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?
描述明确指出获取机器人QQ收藏的表情包图片URL列表，动词和资源清晰。虽未显式与兄弟工具区分，但兄弟列表中无类似获取收藏表情的工具，因此自然区分。评为4分，因为缺少对使用场景的进一步说明。
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?
描述未提供任何关于何时使用此工具或何时不使用此工具的指导，也没有提及替代工具。仅说明用途，缺乏上下文和排除条件。
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取指定群的全部精华消息列表。
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | 群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is not required to restate safety. The description adds the scope '全部' (all), which implies a full collection, but it does not mention return format, ordering, pagination, or behavior when no essence messages exist. With annotations covering the safety profile, this is acceptable but not rich.
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 one short, front-loaded sentence that precisely conveys the operation and scope. There is no filler, repetition, or unnecessary detail.
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 one-parameter tool with readOnlyHint=true, the description is largely sufficient. It names the resource, the scope, and the fact that it returns a list. However, since there is no output schema, a bit more detail about the returned message items could make it fully self-contained.
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%: the single required parameter group_id is already documented as '群号'. The description only echoes '指定群' without adding format, constraints, or examples, so it adds no meaningful meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: '获取指定群的全部精华消息列表' ('get the list of all essence messages of the specified group'). This clearly distinguishes it from siblings like set_essence_msg (which adds messages) and get_group_msg_history (which fetches regular history), so an agent can tell them apart.
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 intended use is implied by the tool name and description: use it when you need all essence messages for a specific group. However, there is no explicit guidance on when to choose this over related tools such as get_group_msg_history or set_essence_msg, so the agent must infer the differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取一般文件消息的详细信息及本地/下载路径。
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | 文件 file 值 | |
| file_id | No | 文件ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safe read-only nature is established. The description adds the useful detail that the result includes local/download path, but it does not disclose failure behavior or any permission requirements, so it adds only modest context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently communicates the resource, the action, and the key output aspect without redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one required parameter and strong annotations, the description is minimally viable. However, there is no output schema and '详细信息' is vague about the actual return shape, and the description provides no usage context to distinguish it from related siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the input schema. The description does not add extra semantics, such as whether 'file' and 'file_id' are alternatives or how they relate, so it remains at the baseline for schema-covered 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 states a specific verb ('获取') and resource ('一般文件消息'), and adds what the caller gets: detailed info plus local/download path. It is clearly distinct from generic 'get message' or 'get image' tools, though it does not explicitly contrast with sibling tools like get_file_url or get_image.
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 given for when to use this tool versus alternatives such as get_file_url or get_msg. The description does not mention prerequisites, exclusions, or situations where a sibling tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取合并转发（聊天记录）的具体内容。
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | 合并转发消息ID | |
| message_id | No | 消息ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with that. However, it adds no behavioral context beyond the annotation, such as what happens with invalid IDs, whether both id and message_id are needed, or any 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 one short, front-loaded sentence with no filler, repetition, or unrelated details. It is appropriately sized for a simple read-only getter.
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 getter with one required parameter and read-only annotations, the basic call is inferable. However, there is no output schema and the description does not explain the return format or the distinction between id and message_id, leaving some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters, giving a baseline of 3. The description does not clarify the relationship between id and message_id or explain when the optional message_id should be used.
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 clear verb ('获取'/'get') and names a specific resource: the content of merged forward/chat-record messages. It is immediately distinguishable as a retrieval tool, though it does not explicitly contrast itself with the sibling get_msg.
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?
There is no guidance on when to use this tool versus alternatives such as get_msg or get_group_msg_history. The only usage signal is the tool name and the one-line purpose, leaving the agent to infer selection without explicit exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取机器人好友列表（好友QQ号、昵称等）。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a small amount of output context by mentioning friend QQ numbers and nicknames. It does not disclose traits like pagination, list order, or absence behavior, but this is a low-risk read-only operation, so the missing detail is not critical.
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 short sentence that front-loads the core action and resource, then appends only the most useful clarifying detail. There is no filler, repetition, or tangential 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 zero-parameter, read-only tool, the description is largely complete: it names the resource and the expected information returned. The absence of an output schema and the lack of any mention of list limits or ordering are minor gaps, but they do 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?
The tool accepts zero parameters, so there is nothing for the description to explain at the parameter level. The schema is already complete with an empty properties object, and the description correctly focuses on the returned friend-list fields instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: “获取机器人好友列表” (get robot friend list), and adds concrete output content (QQ号、昵称等). This clearly distinguishes it from sibling tools like get_group_member_list or get_stranger_info, so there is no ambiguity about what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance about when to use this tool versus alternatives. It does not name sibling tools, prerequisites, or conditions for choosing it; an agent can only infer usage from the tool's name and resource. This is a clear gap, especially in a large sibling list with many list/query operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取与指定好友/临时会话的历史消息。
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | 获取数量 | |
| user_id | Yes | 好友QQ号 | |
| message_seq | No | 起始消息序号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only that the data is historical and scoped to a friend/temp chat; it does not disclose ordering, count defaults, or return behavior, which is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that efficiently captures the tool's purpose and scope. There is no redundant restatement of the title or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only history tool, the description plus schema and annotations is mostly complete. The lack of an output schema and any detail on count/message_seq defaults or ordering leaves a small gap, but not one that prevents 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%, so the schema already documents user_id, count, and message_seq. The description adds no additional parameter meaning, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete verb and resource: retrieving historical messages for a specified friend or temporary session. This clearly differentiates it from sibling tools like get_group_msg_history (group history) and get_msg (single message).
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 usage context ('friend/temporary session'), which implies it is not for group histories. However, it does not explicitly name get_group_msg_history as the alternative or state when not to use this tool, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取群指定文件夹下的文件与子文件夹列表。
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | 群号 | |
| folder_id | Yes | 文件夹ID | |
| file_count | No | 文件数量限制 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds the concrete return content (both files and subfolders), but does not discuss pagination, the effect of file_count, or error cases. This is acceptable for a simple read-only listing but not a strong behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that expresses the full purpose without filler. It is appropriately concise for the simplicity of the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing with fully documented parameters and safety annotations, the description covers the essentials. It could be slightly more complete by mentioning how file_count behaves or that the result is only for a specific folder, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description adds no additional meaning about what values to pass for group_id, folder_id, or file_count, 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 states a clear action ('获取') and resource: files and subfolders under a specified group folder, which is more specific than the title. It does not explicitly name or contrast a sibling such as get_group_root_files, though the '指定文件夹' scope hints at the difference.
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 only restates the operation; it gives no context about when to choose this tool over get_group_root_files, get_group_file_url, or other file-system tools. No exclusions, prerequisites, or decision criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取群文件空间大小与使用情况。
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | 群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe-read nature is covered. The description adds no new behavioral details beyond the purpose, such as whether the reported usage is live, estimated, or requires special permissions; it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that states exactly what the tool returns with no filler or repetition. It is appropriately 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?
For a simple one-parameter read-only tool with no output schema, the description adequately explains what will be retrieved: file space size and usage. It does not specify the return format/units, but the tool's complexity is low and annotations cover safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter group_id is already fully described in the schema with type and '群号'. The description adds no additional meaning about the parameter, so it stays at the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb-resource pair: '获取群文件空间大小与使用情况' (get group file space size and usage). This distinguishes it from sibling file tools like get_group_root_files, get_group_files_by_folder, and get_group_file_url, which concern file listing or URLs rather than capacity/usage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool when you need the group file system's space usage. It does not explicitly name alternatives or exclusions, but the use case is specific enough that no sibling tool covers the same purpose, so no exclusions are necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
根据 file_id 获取群文件的下载URL。
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | 文件ID | |
| group_id | Yes | 群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. However, the description adds no behavioral context beyond that—such as whether the returned URL is temporary, requires group membership, or may fail when the file does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to stating the operation and target resource.
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 getter with complete parameter schema, the description is mostly adequate. However, with no output schema, it does not specify the return shape, and it omits any mention of URL expiration or when the operation would fail.
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 only reuses file_id and does not enrich the meaning of group_id or explain how the two parameters relate to producing the URL.
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 '获取' and the resource '群文件的下载URL', so an agent knows it returns a download URL for a group file. It is specific enough to be distinguished from file-listing siblings, but it does not explicitly differentiate itself from tools like get_file or get_group_files_by_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?
There is no guidance about when to use this tool instead of alternatives, nor any mention of prerequisites such as needing a group_id. The intended usage is only implied by the tool name and description, not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取群荣誉（龙王、群聊之火等）信息。
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | 荣誉类型 | |
| group_id | Yes | 群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety profile is covered. The description adds only examples of honor types, not deeper behavioral context like response structure or permissions, but it does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with no filler or redundancy. It communicates the core purpose immediately and efficiently, earning 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 tool with two parameters and no output schema, the description gives the basic purpose but does not explain what the returned honor information looks like. A brief note about the return structure would improve completeness, but the tool is simple enough that an agent can likely infer 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?
The input schema fully describes both group_id and type, including an enum, so schema coverage is 100%. The description adds a slight semantic hint by giving Chinese examples of honor types, but this mostly restates what the enum already implies. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves group honor information ('获取群荣誉信息') and gives concrete examples of honor types (龙王, 群聊之火). It is specific about the resource, though it does not explicitly differentiate from sibling get_group_* tools, relying on the unique resource name.
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 about when to use this tool versus the many other group-related getters (e.g., get_group_info, get_group_member_info). The intended use is only implied by the tool name and description; there are no explicit alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取指定群的详细信息（群名、人数、群主、公告等）。
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | 群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with those. The description adds the expected return fields (group name, member count, owner, announcement), but it does not disclose additional behavior such as error handling or permission requirements. No contradiction 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 a single short sentence that front-loads the action and then gives concrete examples of the returned information. It contains no filler or redundant repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter, read-only tool with complete schema coverage and safety annotations, this description gives enough orientation to invoke it correctly. It omits only optional details like exact return formatting or error behavior, which are not essential at 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?
The input schema fully documents group_id as 群号, so the description adds no parameter semantics beyond the schema. The phrase 指定群 simply reinforces that group_id identifies the target group, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb (获取) and resource (指定群的详细信息) and lists concrete fields such as 群名、人数、群主、公告等, so an agent can tell it is a per-group detail fetch rather than a list operation. It does not explicitly name or contrast sibling tools, so it falls just short of a top score.
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 about when to choose this tool over siblings like get_group_list or get_group_member_info. The only usage cue is the phrase 指定群, which implies a single-group lookup but gives no explicit when-to-use or 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.
获取机器人加入的全部群聊列表（群号、群名等）。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with that by using '获取'. It adds useful scope and return-content context ('全部群聊', '群号、群名等') beyond the structured annotations, though it does not mention pagination or response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence, with a parenthetical listing the expected fields. Every word contributes; there is no padding or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool with strong annotations, the description provides the scope and expected content sufficiently. No prerequisites, outputs, or error conditions need to be described for 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?
The tool takes zero parameters, so there is no parameter-semantics burden; the baseline of 4 applies. The description's mention of returned fields ('群号、群名等') adds a little value beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact operation ('获取机器人加入的全部群聊列表') with a specific resource and scope. It clearly differentiates from sibling tools such as get_group_info, which targets a single group, and get_group_member_list, which targets members.
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 intended use is implied by the purpose: call this when you need all groups the bot has joined. However, the description gives no explicit when/when-not guidance or alternatives, so an agent must infer routing from the tool name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取指定群内某成员的详细信息（昵称、群名片、角色、等级等）。
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | 成员QQ号 | |
| group_id | Yes | 群号 | |
| no_cache | No | 是否不使用缓存 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by listing the kind of data returned ('昵称、群名片、角色、等级等'), which helps the agent understand the output shape despite the absence of an output schema. It does not mention caching behavior or error conditions, but with annotations present this is a reasonable level of disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tight sentence that front-loads the core action and resource, with parenthetical examples of output fields. No wasted words; completely appropriate for this 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?
For a simple read-only lookup tool with 3 parameters and no output schema, the description provides the essential purpose and a hint at the return fields. It does not fully specify the return structure or edge cases, but given the annotations and simple schema, it is sufficient for correct invocation in most contexts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter meaning ('成员QQ号', '群号', '是否不使用缓存'). The description maps '指定群内某成员' to group_id and user_id but adds no new semantics beyond the schema. The no_cache parameter is only described in the schema, not expanded here. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('获取' / get), the resource ('指定群内某成员' / a certain member in a specified group), and the content ('详细信息' with examples: nickname, group card, role, level). This distinguishes it from sibling tools like get_group_member_list (list of members) and get_stranger_info (non-group member info).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: when you need detailed information of a single member within a specific group. It does not explicitly compare with alternatives or state when not to use it, but the purpose is clear enough that an agent can infer the context. However, no exclusions or alternative routing is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取指定群的全部成员列表（成员较多时返回会较大）。
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | 群号 | |
| no_cache | No | 是否不使用缓存 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds a useful behavioral warning that the response may be larger when the group has many members, but it does not mention caching behavior, pagination, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the main action and adds a relevant caveat in parentheses. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with only one required parameter, the description is mostly adequate. However, with no output schema, it does not clarify what fields the returned member list contains, nor does it explain the behavior of the no_cache flag beyond the schema description.
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 group_id and no_cache both described in the schema. The description does not add any additional meaning to the parameters, 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 uses a specific verb and resource: '获取指定群的全部成员列表' (get the full member list of the specified group). It distinguishes itself from the sibling get_group_member_info by emphasizing '全部' (all), making the scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_group_member_info. No exclusions, prerequisites, or conditions are given; the usage context is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取指定群的聊天记录（从 message_seq 起始，最多 count 条）。
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | 获取数量，默认20 | |
| group_id | Yes | 群号 | |
| message_seq | No | 起始消息序号，缺省为最新 | |
| reverse_order | No | 是否按时间倒序 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety is covered. The description adds the 'from message_seq, max count' boundary but does not disclose response shape or edge-case behavior; with annotations present this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence states the resource, the starting position, and the limit with no filler. All 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?
With 4 parameters fully documented in the schema, one required, and read-only annotations, the description is complete enough for correct invocation. No output schema exists, but the return concept (chat history) is self-evident; a more advanced description could add response details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents group_id, count, message_seq, and reverse_order. The description summarizes message_seq and count but adds no new parameter meaning beyond what the schema 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 states a specific action and resource: '获取指定群的聊天记录' (retrieve chat history for a specified group), and adds starting point and limit semantics. This clearly distinguishes it from get_friend_msg_history and get_msg.
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 context is clear: use this tool when a group's historical messages are needed, and the group scope implicitly separates it from friend-message and other siblings. However, it never names alternatives or states when not to use it, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取群内被禁言成员的列表（NapCat 专用动作 get_group_shut_list）。
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | 群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the NapCat-specific action name as behavioral context, but doesn't disclose return structure or potential limitations. 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 a single efficient sentence that front-loads the main purpose and appends the compatibility note. Every part earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only tool, the description is sufficiently complete for an agent to invoke it correctly. Annotations cover safety, and the absence of an output schema is acceptable since the return type is implied by the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single group_id parameter with its Chinese description '群号'. The tool description adds no additional parameter-level meaning, so the baseline of 3 applies given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: '获取群内被禁言成员的列表' (get the list of muted members in the group). It also names the underlying NapCat action, which distinguishes it from similar tools like get_group_member_list or set_group_ban.
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 purpose implies when to use it (retrieving muted members), but there is no explicit guidance on when not to use it or which alternatives exist. The NapCat-specific note hints at compatibility constraints without elaborating.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取指定群的公告列表（NapCat 专用动作 _get_group_notice）。
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | 群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the NapCat-specific implementation note, which could signal environment requirements, but does not describe return format, pagination, or any side effects beyond what annotations already convey. It neither contradicts annotations nor adds 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 a single concise sentence that front-loads the purpose and includes a parenthetical note about the NapCat-specific action. It is efficient and wastes no words, though it could benefit from a bit more context without becoming verbose.
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 tool with one parameter and no output schema, the description provides enough to understand the basic action, but it omits any details about the expected return format, potential errors, or prerequisites beyond the NapCat environment. Given its simplicity and annotation coverage, a 3 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents group_id as '群号' (group number). The description adds no additional meaning or constraints for the parameter, staying at the baseline 3 as the schema carries the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb '获取' (get) and the resource '指定群的公告列表' (announcement list of the specified group), making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like get_essence_msg_list or send_group_notice, though the NapCat-specific note offers some distinction.
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. It only states what it does and mentions it is NapCat-specific, but does not explain when an agent should choose it over other group-related tools or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取群文件根目录下的文件和文件夹列表。
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | 群号 | |
| file_count | No | 文件数量限制 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no extra behavioral details beyond the obvious read operation, such as pagination, auth requirements, or rate limits. Since the annotations carry the burden and the description is consistent, this is adequate but not enriched.
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 front-loads the action and resource. It has no wasted words and is immediately scannable, earning a top score for efficiency.
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 2 parameters and no output schema, the description is functionally sufficient but lacks explicit mention of return format or how file_count affects results. It does not offer guidance on distinguishing from sibling tools, leaving some gaps for an agent to infer. Given the simplicity, a 3 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (group_id and file_count) are already documented. The description does not add any additional meaning about the parameters, such as format constraints or edge cases. This aligns with the baseline 3 for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('获取' = get) and resource ('群文件根目录' = group file root directory) with a specific result ('文件和文件夹列表' = list of files and folders). It differentiates from the sibling tool get_group_files_by_folder by specifying the root directory, though it doesn't explicitly name that alternative.
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?
There is no guidance on when to use this tool versus alternatives like get_group_files_by_folder or get_group_file_system_info. The description simply states what it does without any context on selection criteria, prerequisites, or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取入群申请/邀请等群系统通知。
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | 获取数量 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and destructiveHint annotations already cover the safety profile, and the description adds useful context about the message categories included (group join requests/invitations). However, it does not reveal additional behaviors such as whether the returned messages are marked as read, limited by count, or ordered chronologically.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and subject without filler or redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and strong annotations, this is nearly complete: the resource is identified and count is optional. Minor gaps remain around count semantics/default behavior and the return shape, but neither prevents a competent agent from invoking 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%: the only parameter 'count' is documented as '获取数量'. The description adds no parameter-level detail beyond that, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('获取') and a specific resource: group system notifications, with concrete examples (入群申请/邀请) that narrow the scope. It is coherent with the name and title but does not explicitly contrast itself with the similar sibling get_group_notice_list, so differentiation is implicit rather than stated.
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?
There is no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description only defines what it does, so an agent must infer the appropriate context from the name and examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
根据图片 file 标识获取图片详细信息（含下载URL/路径）。
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | 收到的图片 file 值或 file:/// 路径 | |
| file_id | No | 文件ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the result includes a download URL/path, which is useful, but it does not discuss failure behavior or other return characteristics. 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?
One dense sentence that front-loads the action and resource, with the key return information in parentheses. 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 read-only single-required-parameter lookup with annotations and full schema parameter coverage, the description is sufficient for selection. Since there is no output schema, it appropriately mentions the main return content (download URL/path); the optional file_id remains only in the schema, 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?
Schema coverage is 100%, so parameters are already documented; the description merely reinforces file as the identifier. It adds no detail about the optional file_id role, so a baseline 3 is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a clear action and resource: get detailed information about an image by its file identifier, including a download URL/path. It is image-specific, which separates it from generic get_file/get_record, though it never explicitly contrasts with those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: use it when you have an image file value or file:/// path and need image details. There is no explicit when-not-to-use guidance or named alternative, so the agent must infer the boundary against get_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取机器人（当前登录QQ）的信息。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral context beyond that—it does not describe what information is returned, whether the result is cached, or any side effects. Since it adds no value beyond the annotations, it scores low.
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 with the core purpose and is appropriately concise for a tool with no parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter getter with no output schema, the description is minimally adequate—it tells what the tool does. However, it does not specify what fields or structure the returned 'information' includes, which could be important for an agent to know when interpreting results. Given the simplicity, a 3 is fair.
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 schema already fully documents everything. Per the rubric, a baseline of 4 is appropriate for tools with no parameters. The description does not need to explain parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: to get information about the bot (the currently logged-in QQ). The verb '获取' (get) and the resource '机器人（当前登录QQ）的信息' are specific, and it is clearly distinguishable from sibling getters like get_version_info and get_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or conditions. It is a simple getter, but the description does not help the agent decide when this tool is appropriate compared to other info-retrieval tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
根据 message_id 获取单条消息的详细信息。
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | 消息ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds little behavioral context beyond the operation itself, such as error behavior or return shape, but it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It states the resource, the parameter key, and the operation clearly and efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required, fully documented parameter and read-only/non-destructive annotations, the tool is almost fully specified for selection and invocation. Since there is no output schema, the phrase 详细信息 is slightly vague about the exact return shape, but this does not block correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes message_id as 消息ID with 100% coverage. The description only repeats the by-message_id lookup mechanic and adds no extra format, provenance, or edge-case guidance, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly names the verb (获取), the target resource (单条消息的详细信息), and the lookup key (message_id). It is distinguishable from sibling list/history/forward tools, even though it does not explicitly name them.
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 intended use case is implied: when you have a message_id and need one message's details. However, it does not explicitly contrast this with get_group_msg_history, get_friend_msg_history, or get_forward_msg, nor does it state 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.
获取当前登录QQ的在线客户端列表。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context beyond the literal action, such as what constitutes an online client or potential empty results. It is consistent with annotations but adds no extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the action and resource. It is front-loaded and contains no unnecessary 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 simple read-only tool with no parameters and no output schema, the description is adequate. It tells the agent what the tool does, though it could optionally describe the expected list content or format, but that is not strictly required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the schema coverage is 100% (trivially). The description clarifies the purpose of the tool, which is sufficient given zero parameters. No additional parameter documentation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the list of online clients for the currently logged-in QQ account. It is specific and distinct from sibling tools like get_login_info or get_status, which focus on account or status information.
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. It does not mention any exclusions or scenarios where another tool would be more appropriate, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
根据语音 file 标识获取语音文件信息，可转换格式。
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | 语音 file 值 | |
| out_format | No | 输出格式，如 mp3/silk |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and destructiveHint=false, so no mutation safety disclosure is needed. The description adds the behavioral detail that the returned voice file information can be converted to a different format (e.g., via out_format), which is genuinely useful beyond the schema. No contradiction with annotations was found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is one efficient sentence that front-loads the main action and appends the conversion capability. No filler words or redundant restatements of the title/name are present.
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 low-complexity read tool with only two parameters, full schema coverage, and read-only annotations, the description supplies the core purpose and the conversion behavior. It does not spell out alternatives or return details, but the output schema is absent and the operation is simple enough that the current information is largely 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 documentation covers 100% of the parameters, so the baseline is 3. The description adds a small layer by explaining that the file parameter is a voice-file identifier and that output format conversion is possible, but it does not substantially extend the schema's own descriptions of file and out_format.
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 uses a specific verb (获取) and resource (语音文件信息), and clarifies the operation is keyed by a voice file identifier, with optional format conversion. This clearly differentiates it from generic file/image retrieval siblings such as get_file or get_image. The generic English name is compensated by the precise Chinese title and description.
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 given about when to choose this over sibling tools like get_file or get_image, nor any exclusions or prerequisites. The use case is only implied by the resource type (voice file), so an agent must infer context. Thus it lacks explicit routing to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查机器人运行状态（是否在线/正常）。若要查 NapCat 版本用 get_version_info；查自身登录QQ用 get_login_info。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare the tool read-only and non-destructive, so the description's job is lighter. It adds that the tool reports online/normal status, but it does not describe the response shape, possible status values, or error behavior. With no output schema, a little more behavioral detail would be useful.
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 entire description is one concise sentence that front-loads the purpose and adds two useful sibling redirects. There is no filler, restatement of the title, or redundant detail.
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 parameterless, annotation-safe status check, the description plus annotations cover selecting and invoking the tool correctly. It could be slightly more complete by stating the exact return fields, but '是否在线/正常' gives adequate outcome semantics.
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 zero properties, so there are no parameters to document or disambiguate. Per the baseline rule for parameterless tools, this receives a 4 because invocation is unambiguous.
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 ('机器人运行状态'), and states the exact outcome: whether the bot is online/normal. It also differentiates itself from the closest siblings by naming get_version_info and get_login_info as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit routing guidance: use get_version_info for NapCat version, use get_login_info for the logged-in QQ, and implicitly use get_status for the bot's running state. This is clear when-to-use vs. when-not-to-use instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取指定QQ用户的信息（无需为好友）。
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | QQ号 | |
| no_cache | No | 是否不使用缓存 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the friendship-requirement context but does not disclose caching behavior, rate limits, or return format; with annotations present, the burden is lower, making this adequate but not rich.
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 that front-loads the operation and includes the key differentiator. There is no filler, redundant restatement, or unnecessary detail.
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 two-parameter read-only lookup with annotations covering safety, the definition is largely complete. The only notable gap is that '信息' does not enumerate what fields will be returned, and no_cache behavior is left entirely to the schema, but an agent can still invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%: user_id is documented as 'QQ号' and no_cache as '是否不使用缓存'. The description only restates the idea of a specified QQ user and adds no semantic detail beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (获取) and resource (指定QQ用户的信息), and adds '无需为好友' which distinguishes it from friend- or group-member-scoped info tools among the siblings. It is not a mere restatement of the name/title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase '无需为好友' clearly signals the primary use case: retrieving info for a QQ user who is not necessarily a friend. It does not explicitly name an alternative tool or state when not to use it, but the usage context is clear and excludes no relevant cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取NapCat/OneBot版本信息。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only that the resource is NapCat/OneBot version info; it does not describe the response shape or whether any request-specific behavior applies, which is acceptable for a zero-parameter read but not a value-add.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence contains the complete meaning without any filler. Every word contributes to identifying the resource.
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?
This is a trivial, no-parameter, read-only operation with annotations covering safety. The description tells the agent exactly what information to expect. No output schema is present, but for a version-info getter the description is sufficient for correct 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 tool has zero parameters and the schema coverage is 100%, so there are no parameter semantics for the description to clarify. Baseline for a no-parameter tool is 4 and no compensation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('获取' / get) and a precise resource ('NapCat/OneBot版本信息'), which immediately distinguishes this tool from sibling getters such as get_status, get_login_info, and get_online_clients. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage whenever the agent needs NapCat/OneBot version information, but it does not explicitly state when to choose this over related tools or mention any exclusions. For a simple no-parameter getter this is adequate, yet it leaves routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
以合并转发（聊天记录）形式向群发送若干条由 send_forward_node 构建的节点消息。nodes 为 node 消息段数组，每节点 {type:'node',data:{uin,nickname,content}}。
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | node 消息段数组 | |
| group_id | Yes | 目标群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating, non-idempotent operation, and the description does not contradict them. It adds useful context about the merged-forward format and node structure, but it does not disclose permission requirements, failure behavior, or side effects beyond sending.
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 compact sentences deliver the operation, the mode, and the essential payload structure without filler. The core action is front-loaded, and the parameter detail is logically placed second.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, the description covers the essential call shape and the non-obvious node structure well. Minor omissions, such as explicitly tying message to the send_forward_node workflow or noting group membership requirements, are not critical 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 coverage is 100%, so a baseline of 3 applies. The description adds real value by specifying the exact node shape {type:'node',data:{uin,nickname,content}}, which the schema's generic array items do not provide. This materially helps an agent construct the message parameter correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action (send merged-forward messages to a group), identifies the payload type (node messages built by send_forward_node), and makes the tool's purpose distinct from ordinary group message sending. The resource and operation are both clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The workflow is implied: build node messages with send_forward_node, then send them as a merged forward. However, the description does not explicitly contrast this with send_group_msg or send_msg, nor does it state when this tool should be preferred over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
向指定群发送一条消息。message 可以是纯文本字符串，或 OneBot 消息段数组。要发图片用 [{type:'image',data:{file:'<本地路径或http(s)链接>'}}]；QQ表情用 {type:'face',data:{id:'<表情id>'}}；@人用 {type:'at',data:{qq:'<qq或all>'}}。
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | 消息内容：纯文本或消息段数组 | |
| group_id | Yes | 目标群号 | |
| auto_escape | No | 消息内容是否作为纯文本发送（不解析CQ码） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is not read-only, not idempotent, and not destructive. The description adds useful message-format behavior and syntax examples, but it does not disclose expected return values, failure modes, or how auto_escape affects sending beyond what the schema already states.
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 opens with the core action and then packs three useful syntax examples into a compact paragraph. Every sentence earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a direct send tool with a fully documented schema and no output schema, the description covers the required target, the message content forms, and common special message types. It is slightly incomplete in not differentiating from send_msg and not mentioning return values, but the essential call is well specified.
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 real value by showing exact message-segment syntax for image, face, and at, which is not present in the schema. It does not add details about auto_escape, but the schema already documents that parameter 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 states a specific verb and resource ('向指定群发送一条消息') and clarifies that message can be plain text or a OneBot segment array. It is clearly distinct from send_private_msg, though it does not explicitly contrast with generic send_msg or send_group_forward_msg.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for sending a one-off group message and concrete examples for image, face, and @ mentions. However, it never states when to prefer this tool over siblings like send_msg or send_group_forward_msg, nor provides exclusions; the usage guidance is mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
在群内发布公告。需要机器人具有发公告权限（NapCat 专用动作 _send_group_notice）。
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | 公告类型 | |
| image | No | 公告附带图片URL | |
| pinned | No | 是否置顶 | |
| content | Yes | 公告内容 | |
| group_id | Yes | 群号 | |
| confirm_required | No | 成员是否需要确认 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds that the bot must hold a specific permission and that this wraps a NapCat-specific action. This is useful behavioral context for an agent deciding whether the current environment supports the call. 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 a single, tightly written sentence that front-loads the core action and then adds the essential prerequisite. No filler or redundant phrasing; every clause 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 mutating tool with 6 parameters and no output schema, the description covers the key non-obvious context: permission requirements and NapCat specificity. The remaining details (such as optional params' runtime effects) are fully documented in the schema, so nothing critical is missing for a 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 coverage is 100%, and each parameter has a description in the schema. The tool description itself does not add parameter-level meaning, so a baseline 3 is appropriate; the schema carries the burden and does so adequately.
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: '在群内发布公告' (publish an announcement in the group). It clearly distinguishes from sibling tools like send_group_msg by targeting the announcement-specific action rather than normal messaging, and even names the underlying NapCat action for 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 clear prerequisite (permission to post announcements) and hints at environment specificity (NapCat-dedicated action), but it does not explicitly compare with alternatives like send_group_msg or state when not to use this tool. The usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
机器人以签到卡片形式在群内打卡。
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | 群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent action; the description adds the card-form detail. However, it does not clarify whether a visible message is sent, whether repeated calls create repeated check-ins, or whether rate limits or permissions apply.
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 one short sentence with no filler and states the action directly. It is efficient, though it could earn a higher score by embedding usage context without adding length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with annotations and full schema coverage, the description is minimally acceptable. Still, the exact visible effect and the boundary between this tool and sibling group actions remain ambiguous.
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 100% of the single parameter with a clear '群号' description. The tool description adds no parameter-level detail, but the baseline of 3 is appropriate because the schema already carries the semantic weight.
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 concrete action (打卡/check-in) and a resource (群内/in group), and specifies the delivery form as a sign-in card. It distinguishes the intent from message-sending siblings, though it could be more explicit about what 'sign' means.
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 given on when to use this tool versus send_group_msg, send_group_notice, or send_poke. There is also no mention of prerequisites such as whether the bot must be a group member or whether this replaces a manual check-in.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
给指定QQ点赞（次数建议1-10）。
| Name | Required | Description | Default |
|---|---|---|---|
| times | No | 点赞次数 | |
| user_id | Yes | 目标QQ号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a non-read, non-idempotent, non-destructive operation. The description adds a useful behavioral constraint by recommending 1-10 like counts, but it does not disclose possible rate limits, side effects, or error behavior beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the recommended count placed in parentheses. Every word contributes, and there is no unnecessary repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description combined with annotations and full schema coverage is mostly sufficient. It lacks only minor details such as expected return value or failure behavior, but nothing essential blocks 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 coverage is 100%, with both user_id and times already described in the schema. The description adds only the recommended range for times, which is mild extra value but does not significantly expand parameter 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 '给指定QQ点赞' clearly states the action (sending a like) and the targeted resource (a specific QQ account). This is specific enough to distinguish it from similar sibling tools like send_poke, which performs a different gesture.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: liking a specified QQ user. However, it does not explicitly state when to prefer this tool over alternatives, nor does it mention any exclusions or competing sibling actions such as send_poke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
通用发送消息。需通过 message_type 指定 private/group，再提供对应的 user_id 或 group_id。message 可为纯文本或消息段数组。
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | 消息内容：纯文本或消息段数组 | |
| user_id | No | 私聊目标QQ号 | |
| group_id | No | 群聊目标群号 | |
| auto_escape | No | 是否作为纯文本发送 | |
| message_type | Yes | 消息类型 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only, not idempotent, and not destructive, but the description adds little behavioral context beyond that. It does not mention delivery semantics, authorization requirements, rate limits, or whether the message is actually dispatched immediately, so an agent gets minimal insight into side effects beyond the word 'send'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences contain only essential information: the tool's generic purpose, the type/id pairing rule, and the message format options. There is no repetition, filler, or unnecessary detail.
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 what an agent needs to construct a valid call: required message_type and message, plus the conditional ID choice. It does not explain the return value, but no output schema exists, and it could be stronger by pointing to sibling tools for dedicated private/group sending.
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 valuable cross-parameter semantics by explaining that message_type selects between user_id and group_id, and by clarifying that message can be plain text or a segment array. This relationship is not fully explicit in the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('send message') and explicitly scopes it as a generic/universal sender that handles both private and group targets. It is clear, though it does not name or differentiate itself from the dedicated siblings send_private_msg and send_group_msg.
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 guidance: choose message_type and provide the matching user_id or group_id. However, it offers no guidance about when to prefer this generic send_msg over the dedicated send_private_msg or send_group_msg siblings, and no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
在群聊或私聊中发送戳一戳。群聊需同时给 group_id 和 user_id。
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | 被戳用户QQ号 | |
| group_id | No | 群号（群聊戳一戳必填） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that this is a non-read-only, non-idempotent action, and the description does not contradict them. It adds the two-mode scope but does not explain behavioral nuances such as permission requirements, failure modes, or side effects beyond the poke itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The operation and context are front-loaded, and the key group-chat requirement is stated immediately.
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 send action, the description plus schema gives an agent everything needed to invoke it correctly. It could mention permission or failure details, but the annotations cover the safety profile and no output schema is expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters, so the baseline is 3. The description adds meaningful mode-dependent meaning: group chat requires both IDs, implying that private chat works with user_id alone. This is genuinely helpful 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 a specific action, '发送戳一戳' (send a poke), and the target contexts, group chat or private chat. This is enough to distinguish it from message-sending siblings like send_group_msg and send_private_msg.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context on where the tool applies (group or private chat) and a concrete usage rule: group poke requires both group_id and user_id. It does not explicitly say when not to use it versus alternatives, but the action is self-explanatory enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
向指定QQ好友发送一条私聊消息。message 可为纯文本字符串或 OneBot 消息段数组（详见 send_group_msg）。
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | 消息内容：纯文本或消息段数组 | |
| user_id | Yes | 目标用户QQ号 | |
| auto_escape | No | 是否作为纯文本发送 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (mutation), destructiveHint=false, and idempotentHint=false, which signals a non-idempotent write operation. The description adds that the message can be text or an array of message segments, and references send_group_msg for format details. However, it does not disclose potential side effects like rate limits, delivery failure behaviors, or whether sending is asynchronous. Without additional behavioral context, it is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core action ('send a private message to a specified QQ friend'), followed by message format clarification. Every word earns its place; no fluff or repetition. It efficiently communicates the essential purpose and format flexibility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-recipient send tool with a rich schema (two required parameters, high coverage) and no output schema, the description covers the purpose and message format. However, it could mention the auto_escape parameter, which controls plain-text sending and might be essential for certain use cases, but the schema already describes it. There is no mention of sending behavior or failure handling, but with no output schema and sibling context, it is reasonably complete. Slight gap: does not specify that the message can include mentions or other message types, but the reference to send_group_msg covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for all three parameters, including types and descriptions for message and user_id, and a description for auto_escape. The description adds minimal additional meaning: it confirms the message can be a string or array and points to send_group_msg for format specifics. Since schema coverage is high, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('send'), resource ('private message to a specified QQ friend'), and content type ('text or OneBot message segments'). It clearly distinguishes itself from sibling send_group_msg by targeting a single user rather than a group. The Chinese title and description are consistent and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when sending a private message to an individual, as opposed to send_group_msg which is for group messages. It references send_group_msg for message format details, providing a clear cross-reference. However, it does not explicitly mention when not to use it (e.g., could use generic send_msg) but the sibling context makes the distinction evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
将群内一条消息设为精华消息。需要群管理权限。
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | 消息ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds the admin-permission requirement, which is a meaningful behavioral gate not covered by annotations. No further side effects are disclosed, but none are necessary for this simple operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core verb and object front-loaded, followed by the permission requirement. No filler or redundant restatement.
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 low-complexity tool with one required parameter and no output schema, the description plus schema and annotations cover what an agent needs. The permission requirement is stated, and the only minor omission is return-value behavior, which is typically an acknowledgement for such setters.
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% – the one parameter message_id already has a description ('消息ID'). The tool description adds no extra format, sourcing, or type guidance, 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 action – marking a group message as an essence message ('将群内一条消息设为精华消息') – with a clear verb and resource. This distinguishes it from the read-only sibling get_essence_msg_list and other group-management 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 explicitly states a key prerequisite: group admin permission ('需要群管理权限'), which tells an agent when invocation is valid. It does not explicitly rule out alternatives, but the sibling set makes the use case obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
设置或取消指定群成员的管理员权限。
| Name | Required | Description | Default |
|---|---|---|---|
| enable | No | true=设为管理员 false=取消 | |
| user_id | Yes | 成员QQ号 | |
| group_id | Yes | 群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows it's a non-destructive write. However, the description adds no extra behavioral context, such as whether the operation requires specific permissions (e.g., only group owner), whether it is reversible, or what happens on failure. It merely restates the action without disclosing side effects or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that front-loads the action. No wasted words, clearly communicates the purpose and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with full schema coverage and no output schema, the description is minimally sufficient, but it lacks any usage context such as prerequisites, return behavior, or limitations. Given the openWorldHint and lack of idempotency, an agent might need more context to understand the effect of repeated calls or potential error conditions. Overall, it is adequate but not rich.
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 descriptions for all three parameters (enable, user_id, group_id). The tool description does not add any further meaning about the parameters; it only implies the operation. Therefore, baseline 3 is appropriate since the schema handles 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 a specific action: setting or canceling administrator permissions for a group member, using explicit verbs '设置' (set) and '取消' (cancel) with the resource '群成员的管理员权限' (group member's admin permission). It distinguishes from sibling tools like set_group_kick or set_group_ban by focusing on admin role management.
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. It does not mention conditions, prerequisites, or alternatives. For example, it does not indicate when one should use this instead of other group management tools. The description is purely a statement of function without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
禁言群内指定成员，duration 单位为秒。
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | 成员QQ号 | |
| duration | Yes | 禁言时长（秒） | |
| group_id | Yes | 群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly=false, so the description does not need to state that mutating occurs, but it adds little beyond that. It fails to mention that a duration of 0 unmutes the member, whether a re-ban resets the timer, or any permission requirements. The only added fact—duration in seconds—duplicates the schema's property description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and target, then clarifies the duration unit. There is no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and all required parameters are documented, so the description is minimally viable. However, it omits a practically important behavior—using duration=0 to remove a ban—and provides no guidance on permissions or edge cases, which leaves a visible gap for a mutating action without an 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?
The input schema has 100% description coverage for all three parameters, so the baseline is 3. The description's mention that duration is in seconds adds no new information beyond the schema's existing '禁言时长（秒）' 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 uses a specific verb '禁言' (mute) and a clear resource '群内指定成员' (specified group member), which distinguishes it from siblings like set_group_whole_ban that target the entire group. The title and description align on the operation being performed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase '指定成员' implies this tool is for muting an individual member rather than the whole group, which offers some context. However, it does not explicitly name alternatives such as set_group_whole_ban or state when not to use this tool, leaving usage guidance mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
设置指定群成员在本群的群名片（昵称）。
| Name | Required | Description | Default |
|---|---|---|---|
| card | No | 新群名片；传空字符串清除 | |
| user_id | Yes | 成员QQ号 | |
| group_id | Yes | 群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds that an empty string clears the card (via the 'card' parameter description, not the main description). The main description does not disclose behavioral traits like permission requirements, whether the change is reversible, or what happens on failure. With annotations covering the basic safety profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that states the action and target. It is front-loaded with the verb and resource. It earns a 4 because it is efficient and clear, though it could add a brief usage note without becoming bloated.
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 mutation tool with 3 parameters, full schema coverage, and no output schema, the description is adequate. However, it lacks context about permission requirements (bot needs to be admin to set group cards) and the effect of the 'card' parameter being optional. An agent could call it correctly based on schema, but richer context would improve reliability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description itself adds no parameter-level meaning beyond what the schema provides. The 'card' parameter description ('传空字符串清除' = pass empty string to clear) is valuable but lives in the schema, not the description. Baseline 3 is correct.
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 ('设置' = set) and resource ('指定群成员在本群的群名片' = the group card/nickname of a specified group member in this group). It clearly distinguishes from sibling tools like set_group_name (group name) and set_group_remark (group remark), though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for setting a member's group card, which is distinct from the many sibling tools. However, it provides no explicit when-to-use guidance, no exclusions, and no mention of prerequisites (e.g., bot permissions to modify group cards). The context is clear enough for an agent to select it among siblings, but alternatives are not named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
将指定成员移出群聊（踢人）。需要机器人在该群且有群管理权限。
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | 成员QQ号 | |
| group_id | Yes | 群号 | |
| reject_add_request | No | 是否拒绝此人再次加群请求 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the destructive nature by saying the member is removed from the group and adds the authorization requirement, which goes beyond the annotations. It does not mention the optional reject_add_request behavior, but that is already documented in the schema; no contradiction with annotations 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?
Two short sentences deliver the action and the key prerequisite with no filler. The main behavior is front-loaded, and the permission requirement is stated immediately after.
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 destructive group-action tool with fully described parameters and clear annotations, the description is largely complete. It could have mentioned what happens on failure or how reject_add_request affects the member's ability to rejoin, but the schema already covers the latter.
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 parameter descriptions already document group_id, user_id, and reject_add_request. The tool description itself adds little beyond '指定成员', so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('移出群聊' / kick) and names the resource ('指定成员' in a group), which clearly distinguishes it from sibling tools like set_group_ban or set_group_leave. An agent can immediately tell this is about removing a member, not muting, renaming, or leaving.
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 by stating the action and a prerequisite: the bot must be in the group and have admin permissions. It does not explicitly contrast with alternatives such as set_group_ban, but the context is sufficient for an agent to understand when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
让机器人主动退出指定群。不可逆，确认后再调用。
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | 群号 | |
| is_dismiss | No | 群主解散群时是否解散群 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds an explicit warning that the action is irreversible and advises confirmation before calling, which goes beyond the destructiveHint annotation. It also specifies the bot is the actor ('让机器人主动退出'). 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 a single, focused sentence with no redundancy, front-loading the purpose and including a critical warning. It is appropriately concise for the tool's simplicity.
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 action and its irreversibility, but does not explain the optional is_dismiss parameter or any side effects beyond leaving. Given the schema covers parameters and annotations cover destructiveness, it is mostly complete, though it could mention that the bot will no longer be in the group.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for both parameters (group_id and is_dismiss) with 100% coverage. The description does not add any additional meaning or examples, so it adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb '主动退出' (actively leave) and resource '指定群' (specified group), clearly distinguishing it from sibling tools like set_group_kick which target other members. The title also clarifies it's about leaving the group chat.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (when the bot should leave a group) but provides no explicit guidance on when to use this tool versus alternatives like set_group_kick or when not to use it. There is no mention of prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
修改指定群的群名称。需要机器人在该群且有相应权限（通常群主/管理）；只影响目标群。
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | Yes | 目标群号 | |
| group_name | Yes | 新群名称 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds useful behavioral context: it requires the bot to be in the group and have permissions (usually group owner/admin), and it only affects the target group. This goes beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and includes the key prerequisite and scope. Every word earns its place; no 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 two-parameter mutation tool with no output schema, the description covers the essential context: what it does, prerequisites, and scope. It could mention idempotency or error cases, but annotations already cover the safety profile, and the schema covers 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 the schema already documents both parameters (group_id and group_name). The description doesn't add much beyond what the schema provides, but it does confirm the purpose of the parameters implicitly. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('修改指定群的群名称' - modify the group name of a specified group) with a specific verb and resource. It distinguishes itself from siblings like set_group_card and set_group_remark by focusing on the group name specifically.
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: when needing to change a group's name, and notes the prerequisite that the bot must be in the group with appropriate permissions. It doesn't explicitly name alternatives, but the sibling list makes the distinction clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
为指定群设置「我」在本群的备注名（只改机器人自己看到的群名，不改真实群名）。
| Name | Required | Description | Default |
|---|---|---|---|
| remark | Yes | 群备注 | |
| group_id | Yes | 目标群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal mutation (readOnlyHint=false) and non-destructiveness, and the description adds a meaningful behavioral boundary: the real group name is not changed, only the remark visible to the bot. This is valuable beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, and the key scoping constraint is front-loaded. Every element 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 two-parameter setter with annotations and no output schema, the description adequately explains the action and its side-effect boundary. It does not cover failure or error behavior, but that is not essential for this straightforward mutation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description adds semantic weight to 'remark' by clarifying it is the bot's own remark name in that group and that the change is local-only, which is not obvious from the schema's terse '群备注'.
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 (设置/set) and resource (群备注/group remark) and explicitly defines the scope: it only changes the bot's locally viewed group name, not the real group name. This clearly distinguishes it from sibling tools like set_group_name and other set_* 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 provides clear context by stating that this tool affects only the bot's own view of the group name. This implies when to use it versus set_group_name, though it does not explicitly name the alternative or list when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
开启或关闭指定群的全员禁言（enable=true 开、false 关）。需要群管理权限。
| Name | Required | Description | Default |
|---|---|---|---|
| enable | No | true=开启全员禁言 false=关闭 | |
| group_id | Yes | 群号 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that this is a mutating operation and adds the permission requirement ('需要群管理权限'), which goes beyond the annotations. It does not describe side effects on existing individual mutes or error cases, but the annotations already clarify read-only and destructive hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that packs the action, scope, parameter meaning, and permission requirement without unnecessary filler. It is well-structured and immediately understandable.
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 two-parameter mutation tool with no output schema, the description together with the schema covers purpose, parameter semantics, and required permissions. It lacks explicit return-value or error details, but those are not essential given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both 'enable' and 'group_id'. The description largely restates the enable semantics already present in the schema, adding no significant new parameter detail, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (开启或关闭), the resource (指定群的全员禁言), and the exact meaning of the enable parameter. The word '全员' distinguishes it from the member-level mute operations among 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?
It provides clear context: use this tool to toggle whole-group mute, and it explicitly requires group management permissions. However, it does not explicitly reference alternatives or state when not to use it, though the '全员' scope makes the intended use fairly obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0delete_msgfetch_custom_faceget_essence_msg_listget_fileget_forward_msgget_friend_listget_friend_msg_historyget_group_file_system_infoget_group_file_urlget_group_files_by_folderget_group_honor_infoget_group_infoget_group_listget_group_member_infoget_group_member_listget_group_msg_historyget_group_mute_listget_group_notice_listget_group_root_filesget_group_system_msgget_imageget_login_infoget_msgget_online_clientsget_recordget_statusget_stranger_infoget_version_infosend_group_forward_msgsend_group_msgsend_group_noticesend_group_signsend_likesend_msgsend_pokesend_private_msgset_essence_msgset_group_adminset_group_banset_group_cardset_group_kickset_group_leaveset_group_nameset_group_remarkset_group_whole_banScored across 45 tools
Most tools map to a distinct resource and action, with clear descriptions separating group management, messaging, and file operations. The main overlap is send_msg versus send_group_msg/send_private_msg, but the descriptions explicitly clarify the difference.
Tool names follow a consistent verb_noun pattern: set_group_*, get_group_*, send_*, get_*. Minor deviations like fetch_custom_face do not break the overall predictability.
45 tools is a very large surface for an MCP server. While the domain is broad, the number will create significant selection overhead for agents, and many related operations could be consolidated or grouped.
Core messaging, group management, member info, and file retrieval are well covered. Notable gaps include no way to approve/reject group requests fetched via get_group_system_msg and no file upload capability, but these are not fatal for typical bot workflows.
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server for GLM chat completions using Zhipu AI models via AceDataCloud
Synap (pool.linkrra.com/v1), Linkrra's OpenAI-compatible LLM API, as an MCP server.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
