Skip to main content
Glama

知你AI助手|多平台客户与客服数据 MCP

搜索历史会话

zhini_search_sessions

搜索历史会话,用于按客户名、消息关键词、消息发送时间范围、客服、渠道、明确标签、联系人类型召回包括已结束、已关闭会话在内的历史会话候选。用户只要求查询当天或某个时间范围内的对话、咨询记录时,默认查询当前授权账号关联的所有渠道范围,不代表当前调用客服本人接待或回复过;除非用户明确说“我处理过、我接待过、我回复过、归属于我”或指定某客服/渠道,否则不要自动传 kfid 或 channel_id。用户要求查询某天或某段时间内的全部接待、完整会话或已结束会话时,应使用本工具分页查询,不能只调用 zhini_list_active_sessions。自然语言中的“XXX 用户/客户”默认是业务语义;当 XXX 必须根据聊天判断时,使用 msg 按相关表达召回候选,再用 msg_stime 限定消息发送时间范围,最后用 zhini_fetch_messages 读取完整上下文并由模型分类,不要先把 XXX 当成标签名。只有用户明确提到标签或已有 tag_id 时,标签才作为筛选条件或补充信号。关键词命中只是召回信号,不等于最终分类。条件性限制:仅当 msg 非空时,关键词历史检索只支持最近半年内的记录;msg 未传或为空、仅使用其他筛选条件(包括 msg_stime)时不受这条关键词专属限制。重要时间语义:msg_stime 表示消息发送时间范围,用于筛选时间段内包含消息的会话,不表示对话开启时间;旧字段 stime 已移除,不要传入。禁止空条件拉全量;page 从 0 开始;本工具不接收数量参数,底层查询默认每次返回 30 条,MCP 可全部展示给模型。

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
msgNo消息内容关键词。适合搜索订单号、手机号片段、产品名、错误提示、投诉词、活动词等。仅当本字段非空时触发关键词历史检索限制:只支持最近半年内的记录。
kfidNo客服 ID 列表。仅在用户明确指定某客服,或明确说查询当前调用者本人处理过/接待过/回复过/归属于本人的会话时传;第一人称场景可先用 zhini_get_current_kefu 获取 kfid。通用时间范围查询不要自动传当前 kfid。
nameNo客户名称关键词。
pageNo页码,从 0 开始。
tag_idNo标签 ID 列表。用户给标签名时应先调用 zhini_search_tags 解析 tag_id。
msg_stimeNo消息发送时间范围,秒级时间戳;按该范围内包含消息的会话筛选,不表示对话开启时间。与非空 msg 组合时,关键词检索只支持最近半年。
channel_idNo渠道 ID 列表。仅在用户明确指定渠道时传;用户未指定渠道时默认覆盖当前授权账号关联的所有渠道。用户给渠道名时应先调用 zhini_list_channels 解析 channel_id。
wx_contact_typeNo联系人类型数组:0 联系人,1 群组。

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. First observed

TDQS

A5/5.0
Behavior5/5

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

Although no annotations are provided, the description fully discloses operational constraints: keyword retrieval limited to the last six months, msg_stime being message time not session opening time, the removal of the old stime field, and default return size of 30 per page. This gives agents a complete behavioral model.

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

Conciseness5/5

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

The description is dense but each sentence adds a necessary operational nuance or boundary condition. Given the high parameter count and the need to avoid common misuses, the length is well justified and remains tightly structured.

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?

In the absence of an output schema, the description adequately covers the expected behavior, default page size, pagination semantics, and what the MCP will expose. It also covers fallback resolution flows and keyword-specific restrictions, leaving no critical gap for correct invocation.

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

Parameters5/5

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

Every parameter is meaningfully elaborated beyond the schema descriptions: msg is a recall signal rather than a final classification, kfid/channel_id carry explicit auto-injection rules, tag_id requires resolution, msg_stime has precise temporal meaning, and wx_contact_type is clarified. The description even warns against deprecated fields.

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?

The description clearly states that the tool searches historical sessions by customer name, message keyword, time range, agent, channel, tag, and contact type, including closed sessions. It also explicitly distinguishes this from active-session listing, making the purpose unambiguous.

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?

It provides precise conditions on when to pass kfid/channel_id, when to resolve names/IDs via companion tools, and how to interpret time semantics and keyword-only limitations. It also states to avoid empty queries, page start at 0, and that no count parameter is accepted.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.