Skip to main content
Glama
OmniQQ-MCP

OmniQQ-MCP

by haoan33

send_private_msg

Send a single immediate private QQ message to a specified friend or user, supporting text, CQ codes, or rich media message segments; use group messaging tools for group chats.

Instructions

向指定 QQ 好友或私聊用户发送单条即时私聊消息 (OneBot 11: send_private_msg)。 适用场景:向个人 QQ 账号发送文本、CQ 码或富媒体消息段。不适用与替代:若目标是 QQ 群聊,请改用 send_group_msg;若需发送本地文件附件,请改用 upload_private_file。 参数约束与交互:message 支持含 CQ 码的字符串或 OneBot 标准消息段数组(如 [{"type":"face","data":{"id":"14"}}]);仅当希望将 [CQ:...] 原样作为纯文本输出时才将 auto_escape 设为 True。 行为与返回:非幂等外部发送操作(调用即真实发出消息);前置要求当前账号已在线且与目标存在好友或临时会话关系,成功返回 status='ok' 及 data.message_id(可用于后续 delete_msg 撤回),被风控或非好友时返回非 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": {
      "user_id": "<user_id>",
      "message": "<message>"
    },
    "name": "send_private_msg"
  }
}

Input Schema

NameRequiredDescriptionDefault
messageYes消息正文;可传普通字符串、内嵌 CQ 码字符串或 OneBot 11 消息段对象数组
user_idYes接收方个人 QQ 号(5~11 位正整数)
auto_escapeNo为 True 时忽略文本中的 CQ 码语法并按纯文本字面量发送;为 False 时解析 CQ 码,默认 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 时解析 CQ 码,默认 False"
    • changedInput schema / properties / message / description
      Previous value: -"要发送的消息内容 (文本或 CQ 码字符串)"New value: +"消息正文;可传普通字符串、内嵌 CQ 码字符串或 OneBot 11 消息段对象数组"
    • changedInput schema / properties / user_id / description
      Previous value: -"对方 QQ 号"New value: +"接收方个人 QQ 号(5~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?

Annotations already flag readOnly=false, openWorld=true, idempotent=false, destructive=false; the description adds substantial context beyond them: it is a real external send (non-idempotent, message actually delivered), requires the account to be online and a friend/temp-session relationship to exist, returns status='ok' with data.message_id usable for later delete_msg, and returns non-zero retcode when risk-controlled or not a friend.

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?

Purpose is front-loaded and the labeled sections (scenario/alternatives, parameter constraints, behavior/return) make it scannable. It is dense and slightly long, but nearly every sentence carries load; minor redundancy with schema parameter text keeps it from a 5.

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 3-param mutation tool with an output schema, the description covers prerequisites (online account, friend relationship), failure modes (risk control, non-friend retcode), and the actionable return value (message_id for delete_msg). Nothing an agent needs to invoke correctly is missing.

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 100%, so baseline is 3, but the description adds meaningful meaning: message accepts CQ-code strings or OneBot segment arrays (with a concrete example) and auto_escape=True only when raw [CQ:...] should be literal text. That is genuine semantic value above the schema, though it largely mirrors the schema's own descriptions.

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 private instant message to a specified QQ friend/private chat user) and cites the underlying OneBot action. It explicitly names the sibling tools it is not (send_group_msg, upload_private_file), so an agent can distinguish it without opening a schema.

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?

The '适用场景 / 不适用与替代' section gives explicit when-to-use and when-to-use-something-else routing: group targets go to send_group_msg, local file attachments go to upload_private_file. Alternatives and their selecting conditions are spelled out.

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