Skip to main content
Glama
OmniQQ-MCP

OmniQQ-MCP

by haoan33

send_group_msg

Sends a single message to a specified QQ group for notifications, @mentions, or rich media; use CQ codes or message segments when real @ alerts are required.

Instructions

向指定 QQ 群发送单条群聊消息 (OneBot 11: send_group_msg)。 适用场景:在已加入的 QQ 群内发布通知、@成员或发送富媒体消息。不适用与替代:若目标是个人好友私聊,请改用 send_private_msg;若需向群内上传文档或压缩包附件,请改用 upload_group_file。 参数约束与交互:如需产生真实的 @全体成员 或 @指定成员 提醒,必须在 message 中使用 CQ 码 [CQ:at,qq=all] / [CQ:at,qq=123456](且保持 auto_escape=False)或传入 at 类型消息段,手写纯文本“@全体成员”不会触发群提醒。 行为与返回:非幂等群广播操作;前置要求当前 QQ 已加入目标群且未被禁言(@全体成员需群主或管理员权限且受每日次数限制),成功返回 status='ok' 及 data.message_id,无权限或被禁言时返回非 0 retcode。

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "group_id": "<group_id>",
      "message": "<message>"
    },
    "name": "send_group_msg"
  }
}

Input Schema

NameRequiredDescriptionDefault
messageYes群消息内容;支持普通文本、含 `[CQ:at,qq=all]` 的 CQ 码字符串或 OneBot 11 消息段数组
group_idYes目标 QQ 群号(正整数,可通过 `get_group_list` 查询已加入的群号)
auto_escapeNo为 True 时不解析 CQ 码而按纯文本字面量发送;需要触发 @提醒或表情时必须保持 False,默认 False

Output Schema

NameRequiredDescriptionDefault
dataNo接口返回的业务负载数据(对象或数组,具体字段依工具而定)
statusNo执行状态标识,成功为 'ok'(或特定生命周期状态),失败为 'failed' 或 'error'
messageNo状态说明或错误诊断详情
retcodeNoOneBot 11 响应状态码,0 表示成功,非 0 表示协议端或网络错误

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.2.2
    • changedInput schema / properties / auto_escape / description
      Previous value: -"是否作为纯文本发送 (不解析 CQ 码),默认 False"New value: +"为 True 时不解析 CQ 码而按纯文本字面量发送;需要触发 @提醒或表情时必须保持 False,默认 False"
    • changedInput schema / properties / group_id / description
      Previous value: -"目标 QQ 群号"New value: +"目标 QQ 群号(正整数,可通过 `get_group_list` 查询已加入的群号)"
    • changedInput schema / properties / message / description
      Previous value: -"要发送的群消息内容"New value: +"群消息内容;支持普通文本、含 `[CQ:at,qq=all]` 的 CQ 码字符串或 OneBot 11 消息段数组"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "properties": {
      +    "data": {
      +      "description": "接口返回的业务负载数据(对象或数组,具体字段依工具而定)"
      +    },
      +    "message": {
      +      "description": "状态说明或错误诊断详情",
      +      "type": "string"
      +    },
      +    "retcode": {
      +      "description": "OneBot 11 响应状态码,0 表示成功,非 0 表示协议端或网络错误",
      +      "type": "integer"
      +    },
      +    "status": {
      +      "description": "执行状态标识,成功为 'ok'(或特定生命周期状态),失败为 'failed' 或 'error'",
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Changed3 schema fields changedv1.1.0
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / message / anyOf
      Added value: +[
      +  {
      +    "type": "string"
      +  },
      +  {
      +    "items": {
      +      "type": "object"
      +    },
      +    "type": "array"
      +  }
      +]
    • removedInput schema / properties / message / type
      Removed value: -"string"
  3. First observedv1.0.0

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing real preconditions: the account must already be in the target group and not muted, @all requires owner/admin rights and is subject to daily limits, and non-zero retcode is returned on failure. It also explains the non-obvious CQ-code mechanism for triggering real @-notifications, which the annotations could never convey.

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

Conciseness4/5

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

Dense but front-loaded and sectioned into purpose, alternatives, parameter constraints and behavior/returns, so an agent can scan for what it needs. It runs long, and some of the return-value detail duplicates the output schema, but there is little pure filler.

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

Completeness5/5

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

For a non-idempotent, open-world broadcast with side effects, the description covers privileges, mute constraints, rate limits, failure signaling and the alternative tools. Return values are technically redundant given the output schema, but their presence does not leave any gap an agent would need to resolve before calling.

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

Parameters4/5

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

Schema coverage is already 100%, so the schema documents each parameter, but the description adds a genuinely useful cross-parameter constraint: CQ codes only fire real @-mentions when `auto_escape=False`, or via an `at` message segment in the array form. That interaction is not derivable from the field-level descriptions alone.

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

Purpose5/5

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

States a specific verb and resource (send a single message to a specified QQ group) and names the underlying OneBot 11 action `send_group_msg`, which makes it unambiguous. It explicitly differentiates itself from the two closest siblings, `send_private_msg` and `upload_group_file`.

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

Usage Guidelines5/5

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

Has an explicit 适用场景 section (posting notices, @-mentioning members, rich media in a joined group) and an explicit 不适用与替代 section that routes the agent to `send_private_msg` for private chats and `upload_group_file` for file attachments. The when/when-not/alternative triad is fully covered.

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