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

No annotations are provided, so the description carries the full burden. It discloses computation windows, metric definitions, and warns against fabricating internal docs, but it does not explicitly state that the scan is read-only, nor describe permissions, side effects, or output 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?

The description uses compact labeled sections and front-loads the core purpose before metric details and usage guidance. Every sentence adds distinct information 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?

With an output schema present, return values need not be described. Metric semantics, date windows, and cross-tool guidance make the tool callable; the only meaningful gap is the under-specified optional end_date parameter.

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 0%, but the description meaningfully defines the three metric values with exact comparison windows. However, it does not explicitly explain the end_date parameter's format, default meaning, or how it interacts with the metric windows, so it stops short of a 5.

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 first line states it performs period-over-period anomaly scans across GMV, refund rate, and ad conversion. This gives a specific verb, resource, and clear scope that distinguishes it from sibling data-query 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 【何时用】 section explicitly lists triggering user intents like '有什么异常' and '退货率是不是高了'. It lacks explicitly named alternatives or when-not-to-use conditions, but the context is clear enough for routing.

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 burden. It discloses an authorization restriction (interns rejected), an anti-abuse constraint (must come from query results, no enumeration), and signals a read-like retrieval rather than a mutation. It does not describe response details, but an output schema is present.

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 two short labeled sections with no filler. Purpose is front-loaded, and operational constraints are separated into a clear 'where the parameter comes from' block.

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 single-parameter read tool with an output schema, the description covers the action, authorization, parameter format, and provenance. It could explicitly point to biz_query_sales as the source of order_id, but the 'query results' constraint and sibling context make this 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?

The schema only defines order_id as a string with 0% description coverage. The description compensates by specifying the expected format (ORD-100123) and constraining the value to come from query results, explicitly forbidding enumeration. This gives the agent essential semantics the schema lacks.

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 【订单详情】 and states '按 order_id 取一单', a specific fetch action on a specific resource (a single order). This clearly distinguishes it from sibling tools like biz_get_sku or kb_get_doc.

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 direct preconditions: order_id must be shaped like ORD-100123, must come from query results, and enumeration is forbidden. It also states a hard exclusion ('intern 角色会被拒绝'). It does not explicitly name an alternative tool, but the usage context is clear enough for an agent.

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 burden. It characterizes the operation as a fetch ('取') and adds an input-provenance constraint, but it does not explicitly state read-only behavior, side effects, authorization needs, or error behavior. This is adequate for a simple getter but not richly 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 compact: two short labeled sections, purpose first, then parameter provenance. Every sentence contributes essential information with zero 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 single-parameter lookup tool with an output schema, the description covers purpose and parameter provenance well. The only minor gaps are explicit read-only/safety disclosure and a 'use this when' statement, both somewhat implied by the tool's nature and name.

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 0%, so the description must compensate. It does add meaningful parameter semantics by saying sku_id must originate from biz_query_sales / biz_anomaly_scan and forbidding guessing. However, it does not explain the ID format, domain meaning, or how it relates to other business keys, leaving some semantic gap.

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: '按 sku_id 取商品维表' (get product dimension table by sku_id). The tool name and resource also distinguish it from siblings like biz_get_order and biz_query_sales. It does not explicitly contrast with those siblings, so it stops short of a 5.

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 an explicit usage rule: sku_id must come from biz_query_sales / biz_anomaly_scan and must not be guessed. This is strong directive guidance. It does not articulate when to prefer this tool over alternatives, but for a simple lookup the provenance constraint largely fulfills the usage-guideline role.

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 present, the description carries the full behavioral burden. It discloses a key limit: '本工具不执行任意 SQL，也不返回底层表结构以外的口径说明', clarifying it is a listing/metadata tool, not a query executor. It could go further by stating whether the list is dynamic or cached, but it does disclose the main boundary and the safety-relevant fact that it won't run arbitrary SQL.

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 tightly structured into four labeled blocks: definition, when to use, when not to use, prohibition. Every sentence adds distinct information with no filler, and the most important purpose statement 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?

Given its zero-parameter interface and the presence of an output schema, the description covers what it returns (metrics, 口径, granularity, sensitivity), when to use it, when not to, and a behavioral limitation. Nothing needed to invoke the tool correctly 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?

The tool takes zero parameters, so there is nothing for the schema to document and no parameter-level detail expected. The baseline for a no-parameter tool is 4, and the description appropriately focuses on the output rather than inputs, since no input semantics exist.

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 opens with '【指标字典】列出业务层可查询指标、口径、粒度和敏感级', naming a specific verb ('列出'), resource ('业务层可查询指标'), and the attributes it exposes (口径, 粒度, 敏感级). This clearly differentiates it from sibling query tools like biz_query_sales and biz_anomaly_scan, which retrieve actual data rather than a dictionary of metric definitions.

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 '【何时用】' section explicitly tells an agent to use this tool when unsure what data exists and to avoid guessing table names, while '【何时不用】' explicitly routes known lookups (GMV/退款/花费) to biz_query_sales or biz_anomaly_scan. This is the most direct possible guidance, naming both conditions and 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, the description carries the burden and does well: it states the hard constraint '禁止拼接 SQL', explains that gmv_cent is in cents and must be divided by 100, and clarifies which ID sources are valid. It does not cover date-range defaults or pagination behavior, but the disclosed constraints and unit handling are substantial.

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 scannable and organized into labeled sections, with the core purpose first followed by constraints, ID guidance, and routing rules. Every section communicates a distinct operational fact, and there is no filler or redundant restating of the tool name.

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 tool with 8 optional parameters rate and an output schema present, the description covers purpose, usage boundaries, ID namespaces, grouping options, and unit conversion. It stops short of specifying date formats and category values, which are relevant to correct invocation, so it is not fully complete.

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 0%, so the description must compensate. It explains group_by allowed values, shop_id formats, channel_id values, and sku_id sourcing. However, it does not clarify date format for start_date/end_date, valid category values, or limit semantics, leaving meaningful gaps for an agent invoking the tool.

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 clear verb and resource: '按结构化过滤汇总 GMV / 订单 / 退款率' (aggregate GMV/orders/refund rate by structured filters). It further differentiates itself from siblings by explicitly stating when to use biz_anomaly_scan or biz_get_order instead, so an agent can reliably select it.

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 '【何时用】' examples and '【何时不用】' alternatives, naming sibling tools. It also gives hard constraints like prohibiting raw SQL and instructing where to source IDs, which tells the agent not only when but how to use the tool correctly.

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?

「查看」隐式表达这是一个只读查询行为，且描述补充了 asset_id 的来源以及资产外部的「源头文件→表/文档→工具」链路范围；但在无 annotation 的情况下，并没有进一步说明是否存在副作用、权限依赖、返回边界或失败行为，故只有中等透明度。

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?

对于只有一个必填 string 参数的工具，描述已覆盖用途、参数来源、使用场景，且有 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 中 asset_id 没有任何描述，覆盖率 0%，而 description 明确说明「asset_id 必须来自 catalog_list_assets.items[i].asset_id」，为调用者补上了关键的取值来源语义；但没有给出格式示例或错误举例，离 5 分还差一点。

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?

描述以「查看某一资产从源文件到表/文档再到工具的链路」明确表达了具体动词、对象和遍历路径；与 catalog_list_assets 等兄弟工具的资产查看能力有明显区分，调用者无需打开 schema 即可知道这个工具专门负责血缘链路。

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?

「面试或排障时解释这份 Excel 怎么变成可查询指标」给出了明确的使用时机，但未说明何时不该用、也没有与 catalog_list_assets 等兄弟工具做条件对比，达不到 5 分要求的明确 when-not/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?

No annotations are provided, so the description carries the burden. It discloses the tool's scope (current connected assets) and output fields, but does not mention whether the listing is cached, whether it scans live systems, or whether it requires any special permissions. For a read-only listing tool, 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?

The description is compact and front-loaded: the purpose is stated in the first line, followed by clear usage sections. Every sentence earns its place, and the formatting with section markers improves scannability.

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 listing tool with an output schema present, the description is nearly complete. It covers what the tool does, when to use it, and when not to use it. The only minor gap is the lack of any note about performance, caching, or permission requirements, but these are not critical for a catalog listing tool.

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 there is no schema burden to compensate for. The description adds value by explaining what the returned asset catalog contains (format, row count, sensitivity level, location), which is the closest thing to parameter semantics for a no-arg tool.

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 ('列出' / list) and resource ('当前接入的数据/知识资产'), and enumerates the exact fields returned (格式、行数、敏感级、位置). It is clearly distinguishable from siblings like kb_search or biz_query_sales.

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 examples ('现在接了哪些数据', '磁盘上有什么', '有没有订单表') and when-not-to-use guidance with named alternatives (biz_* for data queries, kb_* for document search). This is exemplary 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?

无注释，描述承担全部责任。它披露了分页行为（默认4000字、truncated时传入next_offset继续读），以及飞书空洞场景（readable=false、body仅导语）等行为细节，比单纯说“读取文档”更透明。但未提及权限或错误处理，留有一定空间。

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?

有输出模式，但描述补充了关键行为（分页、空洞），以及使用前提（doc_id来源）。对于中等复杂度工具，描述已覆盖主要场景，但未提及错误处理或特殊返回值，略有不足。

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描述覆盖率为0%，描述必须补偿。它解释了doc_id的来源（必须来自搜索，禁止猜）、max_chars默认值及行为，并通过“分页”和“next_offset”暗示offset用法。虽然未全面覆盖所有参数，但关键语义已补充。

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?

描述开头即明确核心功能：“按 doc_id 读取单篇正文（分页）”，动词“读取”+资源“正文”+分页行为清晰，与兄弟姐妹（搜索、大纲、节选）有明显区别。后续补充解释使目的更加明确，没有歧义。

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?

【何时用】部分明确指出“已经拿到 doc_id，用户要看原文/摘要/引用”，并强调 doc_id 必须来自搜索，不得用标题猜，这提供了明确的使用条件和参数来源。虽然未列出替代工具的排除条件，但已足够指导何时使用。

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 burden. It reveals that short documents may have a single '全文' node and suggests kb_get_doc in that case, adding behavioral context. However, it doesn't explicitly state read-only nature, error handling, or return format details, though the output schema likely covers the latter.

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 and well-structured with labeled sections: purpose, usage, parameter source, and short-doc note. Every sentence adds value, and the key purpose 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?

For a simple tool with one parameter and an existing output schema, the description covers purpose, usage, parameter source, and an edge case. Nothing essential is missing for an agent to call 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 input schema provides only a bare 'doc_id' with no description (0% coverage). The description compensates by stating that doc_id comes from kb_search, giving clear provenance and 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 clearly states the verb '返回' (return) and the resource '章节树' (chapter tree) with its contents (标题 + offset + section_id), and distinguishes it from sibling tools like kb_get_doc and kb_read_section by explicitly labeling it as the outline step.

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 an explicit '何时用' section specifying when to use (long SOPs needing chapter-wise reading or before kb_read_section) and gives an alternative for short documents (use kb_get_doc instead). It also notes that doc_id comes from kb_search and that section_id/offset are passed to kb_read_section.

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 behavioral burden. It discloses the sort order (按文档数倒序), the returned fields (tag_id / name), and a key behavioral limitation (not for reading content). For a zero-parameter list operation, this is sufficient context, though it could explicitly state that the operation is read-only.

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 and front-loaded with the purpose, followed by a clear when-to-use section and an explicit don't-do-this warning. Every sentence earns its place; there is 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?

Given the tool's low complexity (no parameters, output schema present), the description is complete. It states what the tool returns, the ordering, the intended workflow with kb_search, and a clear exclusion. Nothing essential is missing for an agent to invoke 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 tool has zero parameters and 100% schema coverage, so the baseline is 4. The description adds no parameter details, but none are needed because the input schema already shows an empty parameter set.

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 operation and resource: 列出知识库当前标签, with an explicit sort order (按文档数倒序). It also differentiates itself from content-reading tools by warning 不要用本工具读正文, so an agent can distinguish it from siblings like kb_get_doc and kb_search.

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: use this tool when wanting to search by tags but unsure which tags exist, then pass the name to kb_search.tag_names. It also gives an explicit exclusion: do not use this tool to read content. This is strong 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 carries the behavioral disclosure burden. It discloses the required precondition, the valid input source, and the failure mode for invalid section_id values. It could additionally state read-only behavior or max_chars truncation, but '读' plus the output schema cover the most important behavioral expectations.

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 two compact labeled paragraphs, front-loading the purpose before the critical usage constraints. Every sentence adds information about prerequisites, valid inputs, or failure modes, with no 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?

Given no annotations and a 4-parameter schema, the description is nearly complete: it provides workflow step, prerequisite, parameter semantics, and failure behavior, while the output schema covers return shape. The only minor omission is explicit max_chars truncation behavior, which is a small gap for a read-a-section tool.

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 0%, and the description compensates by explaining the two ambiguous parameters: section_id must come from the same outline, and offset can be taken from sections[i].offset. doc_id is self-evident from its name and required status, and max_chars is self-explanatory, though it is not explicitly described.

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 '第 2 步·读某一章' and states '按 section_id 或 outline 返回的 offset 读取一节', giving a specific verb (read), resource (one section), and input modes. It differentiates from the sibling tools by naming kb_get_outline as its required precursor and by focusing on a section rather than the whole document or outline.

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 says '必须先调 kb_get_outline', restricts section_id to 'from the same outline's sections[i].section_id', allows passing sections[i].offset as offset, and warns that cross-document section_id will fail. This provides clear when-to-use and when-not-to-use guidance with no ambiguity.

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 present, so the description carries the full burden. It discloses the hard MISSING_FILTER constraint, that results are truncated summaries rather than full text, that feishu_stub_only/has_fulltext=false does not mean the document is missing, and that kb_get_doc will explicitly refuse to return full text. This goes well beyond what the schema conveys.

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 structured as short labelled blocks, each adding a distinct operational fact: hard constraint, sibling distinction, parameter sourcing, display modes, collection values, and Feishu stub handling. It is dense but every sentence earns its place and it is front-loaded with purpose.

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 search tool with no annotations, the description covers the essential invocation context: minimum filter requirements, error behavior, how to obtain tag names/doc_ids, display truncation, collection enum, and the Feishu stub edge case. Output schema exists, so describing return shape is not needed. Minor omissions like tag_mode and date format prevent it from being perfect, but it is operationally complete.

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 0%, so the description must add semantics. It explains the at-least-one-filter hard constraint, display_mode character counts (compact=80/brief=220/full=400), and collection allowed values (sop/replay/training/talk/internal). However, it leaves tag_mode, date format for created_from/created_to, and pagination semantics undocumented, so compensation is strong but not complete.

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 opens with '知识检索·万能口' and states it filters catalogued documents by keyword/tag/collection/time/quality. It explicitly distinguishes itself from kb_get_doc by noting this tool only returns lists and truncated summaries, not full text. This is a specific verb+resource with clear sibling differentiation.

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 an explicit 'when not to use' rule: if a specific section or full body is needed, use kb_get_outline / kb_get_doc. It also frames the difference from kb_get_doc and tells agents to call kb_get_doc when actual full text is needed. This is explicit condition-based routing.

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