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

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

No annotations exist, so the description carries full responsibility. It discloses key behavioral constraints (required id at least one, size cap, time filter meaning) but does not mention potential side effects (none expected for a read), response format, or error behavior. Given it's a read-only operation, this is adequate but not exhaustive.

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 dense but well-organized: purpose, use cases, then constraints. It front-loads the core function and immediately gives practical context. Minor redundancy in listing use cases, but every sentence adds value.

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?

Given the tool's complexity (3 modes, 8 params) and no output schema, the description covers all major usage paths and constraints. It lacks an explicit statement about return format, but given the read nature and sibling tools' patterns, this is a minor gap. Overall it provides sufficient context 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?

Schema already covers all parameters (100% coverage), but description adds critical relational meaning: sid for first load, mid for cursor pagination, uid for customer scope, and the semantic clarification that start_time/end_time filter message time, not session start. This goes 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?

Description clearly states the tool reads chat messages and enumerates three distinct access modes (by sid, mid, uid) with concrete use cases like viewing session context or summarizing complaints. It also differentiates from sibling search tools by saying 'call directly, don't search first'.

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?

Provides explicit usage guidance: when to use each parameter mode (sid for first load, mid for pagination, uid for customer queries), when to use directly vs searching (known ids), and constraints like 'at least one of sid/mid/uid' and 'mid with direction'. Also clarifies time semantics to avoid misuse.

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

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

With no annotations, the description fully discloses behavior: it uses the API key from the current request, standardizes the return fields (total, remaining, used), and enforces a security boundary by not allowing passthrough of apikey parameters and not returning the full key. This gives clear expectations of side effects and constraints.

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 concise, consisting of two clear sentences that cover purpose, input constraint, behavior, output format, and security. It is well-structured and free of unnecessary details.

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?

Even without an output schema, the description specifies the standardized return fields (total, remaining, used) and explains the security boundary. This provides sufficient information for an agent to understand what the tool returns and how to use it 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?

The schema has zero parameters, and the description explicitly states 'no business input parameters', clarifying that the tool relies on the request's API key. This goes beyond the empty schema and prevents any confusion about expected inputs.

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's purpose: to query the total quota, used amount, and remaining amount of the API Key for the current request. This is distinct from all sibling tools, which focus on customers, sessions, tags, and messages.

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

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

The description explains that the tool has no business input parameters and uses the current request's API key, but it does not explicitly mention when to use this tool versus alternatives, or provide any comparison to sibling tools. The usage context is implied but not directly stated.

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

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

The description discloses that the tool only outputs kfid and explicitly excludes identity information such as phone, name, team, enterprise, or responsible channel. It does not explicitly state side effects or read-only behavior, but as a parameterless getter with a detailed output constraint, it carries the transparency burden adequately. A short 'read-only' note would make it fully transparent.

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 concise and well-structured: a clear main purpose, followed by two use-case examples, and an important boundary note. Each sentence serves a purpose without redundancy, and the structure guides the reader from general function to specific usage constraints.

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?

Given the tool has no parameters and no output schema, the description sufficiently covers the output (kfid only) and provides essential context about when to use and when to avoid the tool. It also clarifies the default account/channel scope for time-range queries, leaving no critical gaps 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 has no parameters, and the schema accordingly defines an empty properties object. There is no parameter information to add; the description does not contain any misleading or absent parameter semantics. A perfect score is appropriate given there is nothing to explain.

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 current caller's kefu ID and explains two specific use cases: identifying sessions the caller is handling before calling zhini_list_active_sessions, and constructing kfid filters when the user expresses first-person attribution. It effectively distinguishes itself from sibling tools by implying its role in session filtering.

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 explicit when-to-use guidance (before listing active sessions or when user mentions first-person attribution) and a critical when-not-to-use rule (do not call or auto-append kfid for time-range-only queries). This is a clear, actionable usage policy.

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

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

由于没有提供注解，描述承担了揭示行为特征的全部责任。描述明确指出这是只读查询，不会修改客户资料、备注、负责人或标签，这界定了工具的副作用范围。虽然没有详细说明权限要求或失败模式，但对只读性质的说明已经足够清晰。

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?

描述在现有上下文中已经较为完整：明确了输入参数、使用场景和后续工具。虽然没有提供输出格式细节，但考虑到没有输出 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?

唯一的参数 uid 在描述中得到了充分解释，说明了其含义（知你侧客户 UID）和常见来源（zhini_search_customers 返回或会话数据提供），帮助代理理解如何获取该参数。参数描述与 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?

描述明确说明了工具用途：按客户 UID 获取客户资料和标签，并列举了包含的信息类型（身份、来源、负责人、联系方式等）。还提供了典型使用场景，帮助代理理解何时调用此工具。

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?

描述给出了明确的使用前置条件：当只有姓名/手机号/微信号时，应先用 zhini_search_customers 查找 uid，这有助于代理正确选择工具。还提到了后续可调用 zhini_fetch_messages 获取聊天上下文，形成了完整的使用流程。虽然没有明确列出不适用场景，但结合兄弟工具列表，已能指导代理做出选择。

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels: it discloses the snapshot nature (not historical), the scope restriction (only current account's channels, not whole enterprise), the truncation limits (250 colleague, 100 waiting, with a hint when truncated), and the kfid dependency for queue-type classification. Nothing about the tool's operational behavior is left to inference.

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 long but every sentence carries operational value—there is no filler. It follows a logical flow: purpose → boundary → alternatives → scope/truncation limits → prerequisite. For a tool with this many caveats, the length is justified, though it could be tightened slightly without losing 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?

Given the tool's complexity (snapshot vs. history distinction, truncation limits, prerequisite dependencies, sibling routing) and the absence of annotations and output schema, the description covers everything an agent needs to call it correctly and interpret results. It even discloses the truncation hint behavior. Nothing essential 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 coverage is 100%, so the kfid parameter is already fully documented in the schema (including how to obtain it and its effect on queue_type classification). The description reinforces this in the prerequisite but adds little meaning beyond what the schema already provides. Baseline 3 is appropriate given the high 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 states a specific verb+resource ('获取...当前会话队列' - queries the current session queue of not-closed sessions under the current account's channels) and immediately distinguishes it from siblings by clarifying this is a live snapshot, not a historical query. The boundaries are explicit, making it unambiguous which tool is which.

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?

Explicit when-to-use (viewing pending/mine/colleague/AI states, selecting a session to read messages) and explicit when-not-to-use with named alternatives: zhini_search_customers for full user scope and zhini_search_sessions for ended/closed/historical sessions. Also states the prerequisite of calling zhini_get_current_kefu when distinguishing mine/colleague sessions. This is textbook-level routing guidance.

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

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

No annotations are provided, so the description must carry the behavioral burden. It discloses that deprecated channels are not exposed, which is useful, but it does not state whether the operation is read-only, describe the response format, or mention pagination or rate limits. Given the absence of annotations, this is a notable gap for a listing tool.

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 well-structured, front-loading purpose, then usage scenarios, supported types, exclusions, prerequisites, and follow-ups. Each sentence carries value, and the length is justified by the amount of contextual information packed into it.

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 no output schema, the description should explain what the tool returns. It states it returns a channel list and mentions resolving channel_id, but it does not describe the response structure (e.g., whether results are grouped when group_by_type is true, what fields each channel object has, or pagination behavior). This leaves the agent guessing about the output format.

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 (type and group_by_type) adequately. The description does not add extra meaning beyond what the schema provides; it merely repeats the list of supported types, which is redundant. 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 verb (获取) and resource (渠道列表), and explains its purpose: resolving channel names to channel_id and interpreting channel types. It differentiates from sibling search tools by positioning itself as a prerequisite, making its role 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 explicitly provides when to use it ('适用于用户说...时') with concrete examples, states no prerequisites, and names the follow-up tools (zhini_search_customers, zhini_search_sessions). This leaves no ambiguity about when to invoke it versus alternatives.

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

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

With no annotations provided, the description carries the full burden and discloses authorization scope, only_active filtering behavior, and output name normalization ('name 为空时可标准化为未命名'). The mention of 'name' is slightly ambiguous since it is not an input parameter, and the return format is only implied rather than stated.

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 core purpose is front-loaded in the first clause, followed by compact 前置/后续 sections. The three scenario examples add value for an agent deciding when to call the tool, though the description is slightly long for a 2-parameter list 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 low-complexity tool (2 optional params, no output schema, no annotations), the description covers purpose, scenarios, parameter behavior, prerequisites, and downstream workflow. The return shape (kfid + name) is implied but not explicitly stated, which is a minor gap 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?

Schema description coverage is 100%, so the baseline is 3. The description reinforces only_active semantics ('only_active=true 时只返回可用客服') but adds little beyond the schema's own parameter descriptions, particularly for scene.

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 the core purpose ('把客服姓名解析成 kfid'). This clearly differentiates it from sibling list tools like zhini_list_active_sessions, zhini_list_channels, and zhini_list_tags, which target different resources.

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 three concrete usage scenarios ('客服A负责哪些客户', '抽查某客服历史接待', '队列统计时把 kfid 转成人名'), states prerequisites explicitly ('前置：无'), and names downstream tools (zhini_search_customers, zhini_search_sessions, zhini_list_active_sessions). This is explicit when-to-use guidance with workflow context.

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

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

With no annotations provided, the description carries the full burden. It explicitly declares the tool is read-only and does not add, modify, or delete tag groups, which is crucial for an agent to understand its safety. It also labels it a dictionary tool. It does not mention output format or edge cases, but for a simple list operation this is sufficient.

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 compact yet information-dense. It opens with the core purpose, then delineates boundaries, prerequisites, and follow-ups in a clear structured flow. Every sentence adds value 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?

Given no output schema, the description covers the essential context: what the tool does, when to use it, its read-only nature, and relationships to sibling tools. It omits a description of the return format, but for a zero-parameter list tool, this is 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?

The tool has zero parameters, so the description has no need to explain them. Baseline 4 is appropriate; the description adds no parameter-specific detail but none is required.

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 tag groups ('获取标签分组') and gives specific use cases (understanding the tag system, explaining tag ownership, obtaining tag_group_id before listing tags). It is distinct from siblings like zhini_list_tags and zhini_search_tags by focusing on groups rather than tags or searching.

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?

Explicitly states when to use (to understand tag system, explain ownership, get group ID), notes no prerequisites, and provides follow-up actions (call zhini_list_tags after getting group ID) and an alternative (prefer zhini_search_tags when user gives a tag name). This is exemplary guidance.

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

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

虽然没有任何注解，但描述开头的“分页获取标签列表”明确表明这是一个只读的查询操作，不涉及数据修改或破坏性行为。描述还通过“前置”“后续”等词语说明了操作上下文，没有隐藏副作用。

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?

虽然缺少输出 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?

共有 3 个参数，schema 中均提供了详细的中文描述：page 从 1 开始，page_size 最大 20，tag_group_id 可由 zhini_list_tag_groups 返回且不传时查询默认范围。描述中也重复了这些关键约束，并补充了 tag_group_id 的实际来源，参数含义清晰完整，schema 覆盖率达到 100%。

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?

描述明确说明该工具用于分页获取标签列表，并具体指出用途是在已知标签分组 ID 时列出该分组下的标签，以及为后续的客户搜索或历史会话搜索提供 tag_id。这清晰区分了与兄弟工具（如 zhini_search_tags、zhini_search_customers）的不同角色。

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?

描述提供了明确的使用场景（当已知标签分组 ID 时），并给出了前置步骤（调用 zhini_list_tag_groups 获取分组），还说明了替代方案（如果只提供标签中文名，应优先调用 zhini_search_tags）。此外，还指出了后续可调用的工具（zhini_search_customers 或 zhini_search_sessions），形成了完整的工作流指引。

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

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

No annotations are provided, so the description carries the full disclosure burden, and it does so well. It discloses the default query scope (authorized account's channels rather than the current kefu's own), the boundary that tag_id only covers labeled customers, the prohibition on empty-condition full pulls, pagination constraints (page from 0, page_size max 20), and that the return is customer UIDs for downstream calls. It loses one point only for not describing the response shape or error behavior, which for a no-annotation tool could have been richer.

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 long but every sentence carries decision-relevant information—no filler or tautology. It is front-loaded with purpose and default-scope behavior before the routing rules. The length is justified by the tool's complexity (13 parameters, many boundary conditions, multiple sibling relationships). It loses one point because the density could have been organized into clearer sections, but there is no wasted prose.

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 13-parameter tool with no annotations and no output schema, the description is remarkably complete. It covers core purpose, sibling routing (zhini_list_active_sessions, zhini_search_sessions + zhini_fetch_messages), default-scope semantics, ID-resolution prerequisites, natural-language tag boundaries, pagination constraints, and the downstream workflow (zhini_get_customer_profile or zhini_fetch_messages after obtaining UIDs). The return value (customer UIDs) is stated in the first sentence, compensating for the missing 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?

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by adding contextual usage semantics: it explicitly warns not to pass kfid/pic_kfids/channel_id unless the user states personal involvement or specifies a kefu/channel, and it documents the ID-resolution dependency (call zhini_search_tags/zhini_list_channels/zhini_list_kefu first) that the schema only hints at. This adds decision-relevant meaning the schema alone does not convey.

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 opens with a precise verb+resource statement: 搜索客户通讯录 (search customer address book) and enumerates every searchable criterion (name, phone, WeChat ID, kefu, responsible person, tag, channel, gender, contact type, time range) plus the output (customer UIDs). It actively distinguishes itself from siblings, explicitly stating it cannot be replaced by zhini_list_active_sessions for time-range all-user queries, so an agent can select it correctly.

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?

Exceptional when/when-not guidance. It specifies default scope behavior (all channels of the authorized account, not just the current kefu's handled customers), the exact conditions under which kfid/pic_kfids/channel_id should NOT be auto-passed, the natural-language tag boundary (don't auto-convert 用户/客户 to tag_id), routing to zhini_search_sessions + zhini_fetch_messages for chat-content conditions, ID-resolution prerequisites (zhini_search_tags, zhini_list_channels, zhini_list_kefu), multi-match confirmation, and pagination limits. This leaves no ambiguity about when to invoke it.

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

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the burden. It discloses error behavior for empty keywords, explains the aggregation option, and implies a read-only search operation. It does not explicitly state that it is side-effect free, but this is strongly implied by the search nature. The lack of explicit return format is a minor gap but not critical for a search action.

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 somewhat verbose but every sentence adds value: it explains the purpose, gives typical scenarios, and clarifies boundaries. It is well-structured and not redundant, though it could be shortened slightly without losing meaning.

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?

Given the absence of an output schema, the description does not detail the return structure, but the purpose is clear and the tool is simple. It covers error conditions and grouping behavior, so the agent has enough context to call it effectively. A return format description would improve completeness, but it is not essential for this simple search.

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 complete descriptions for both parameters, including examples and the default value for include_grouped. The tool description only restates what is in the schema without adding additional semantic meaning, 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 clearly states the verb 'search' and the resource 'tags', and explains the core purpose: resolving tag names to stable tag_id. It also distinguishes this tool from sibling search tools like zhini_search_customers and zhini_search_sessions.

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 explicit when-to-use guidance: only when the user explicitly mentions tags or tag-related filtering, and explicitly cautions against using it for general customer semantics. It also names alternative tools for those other cases, leaving no ambiguity.

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