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

无注解；描述未说明权限、URL 拼接细节、是否只读/审计操作，也未有输出表单。

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 或返回字段；9 个可选参数未描述其生成的 URL，未说明是否需要先列举数据源/project。

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 覆盖仅 11%；除 range 默认 15m 外全部参数无说明，无法理解 datasourceUid、keyword、level 如何参与生成 URL。

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?

描述明确指定“生成 Grafana Explore 深链”，动词+资源清晰，但与同级日志查询类工具的区别未显式说明。

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?

未说明使用时机（AI 结论后一键核对）也未提及备选工具，缺乏排除性指引。

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, and the description does not mention permissions, side effects, read-only or non-destructive guarantees. It conveys that the tool compares/analyzes windows and highlights deviations, but stops short of safety/authorization context.

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?

Description is dense but compact, conveying multiple signals (missing templates, new templates, numeric drift, distribution change) in two sentences without 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?

No output schema exists, and the tool has 8 parameters and various window/config options but no return-type clarification or operation scope. The description packs meaningful logic signals but omits technical details like how results are returned and required access.

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?

Parameter coverage is low (2/8 properties have descriptions). The description adds meaning for 'range' and 'baselineOffset' (e.g., '1h', 'yesterday same time', 'prev window'), but names like 'project', 'datasourceUid', 'labels' are under-specified.

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 states a specific action ('compare with baseline window') and identifies the trigger ('go-to when logs all normal but results wrong'), plus the artifacts detected (missing templates, new templates, value deviations, field distribution changes). It lacks explicit differentiation from sibling tools but is otherwise precise.

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 recommends as the first choice for the condition 'logs normal but results incorrect', and clarifies the default baseline window ('previous day same time'). It does not give exclusion or 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 describes the analysis flow and that it returns a diagnostic report with codeHints, but does not explicitly state side effects (e.g., read-only, permissions, rate limits). Given the tool name implies diagnostics, it's likely read-only, but the description doesn't state this. It adds value with the pipeline detail and output, but safety aspects are unaddressed.

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 a single, dense sentence with a clear pipeline using arrows and parentheses. It's front-loaded with the primary use case. Every phrase adds information, though it's a bit long. No fluff, but could be slightly more concise by trimming redundant details. Structure is logical.

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 and no output schema, the description explains the return values (diagnostic report with evidence chain and codeHints). It covers the workflow and cross-project behavior. However, it doesn't specify the exact structure of the report or how 'codeHints' are used, but that's acceptable given no output schema. Siblings exist for more granular actions, but this tool seems self-contained. It's fairly complete for a complex 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 coverage is 67%, and the description adds meaning by explaining the behavior when 'project' is omitted (cross-datasource scan). It also mentions defaults for 'range' and 'baselineOffset' in the schema, but the description reinforces these. The 'symptom' parameter's purpose is explained. For the undocumented 'start'/'end', no extra info, but the description's time-range context helps infer usage. Overall, it adds valuable parameter context, especially for 'project'.

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: a comprehensive root-cause analysis tool for diagnosing issues. It lists the analysis pipeline (trend detection, anomaly localization, dual-path probing, scoring) and distinguishes it from siblings by being the 'first choice for troubleshooting' (排障首选). It's specific about the verb (diagnose) and resource (issues).

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 usage context: it's the preferred tool for troubleshooting, and it specifies that omitting 'project' triggers a cross-datasource scan. However, it doesn't explicitly mention when to use alternatives like query_logs or compare_baseline, though the pipeline implicitly suggests it's a higher-level tool. This is clear but lacks explicit exclusions.

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 it does disclose the core behavior: it fetches full untruncated lines and uses timestamp+keyword for locating. Yet it omits details like return format, behavior when the line is not found, tolerance/edge cases, or auth/precondition requirements. It 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 a single front-loaded sentence that leads with the main action and contains no filler. The conditional workflow is dense but readable; it could be split into clearer steps, but it is still appropriately sized for the 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?

This is a 9-parameter tool with no output schema and no annotations. The description covers the central use case but does not explain four undocumented parameters (labels, project, requestId, datasourceUid) nor the return value shape or failure behavior. For the tool's complexity, the description is noticeably incomplete.

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 56%, so the description must add some parameter meaning. It does add value for timestamp (must come from the time field of query_logs/trace_context) and keyword (used for precise positioning, recommend a unique feature like order number). However, it leaves labels, project, requestId, and datasourceUid unexplained, so it only partially compensates for the schema 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?

Description clearly states the action: retrieve the complete raw log line without truncation. It further distinguishes itself from siblings by specifying the exact trigger—when query_logs/trace_context returns a line with a '(截断 N 字符)' marker—and the required input (time as timestamp plus keyword). This is a specific verb+resource with clear 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?

Provides explicit when-to-use context: call this tool only when query_logs/trace_context indicates truncation. It also tells the agent how to construct the call (use the row's time as timestamp and pair with keyword). However, it does not explicitly state when not to use this tool or name alternatives for non-truncated cases, so it stops short of a 5.

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?

该工具的参数较多（8个），且没有输出模式，但描述未提供返回值细节（无论是聚合计数还是样本列表）或其他调用约束。描述很简短，未涵盖在昂贵数据集上运行分析所需的深入信息。对于不熟悉该工具的人来说，缺乏重要上下文，得分较低。

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?

输入模式覆盖率为 25%，虽然描述涵盖了“fields”参数（即检查哪些字段），但未解释其他参数（例如 start、end、labels、project）。描述确实为 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?

描述以清晰的动词“统计”开头，并指定了范围：字段空值率和针对“默认/未配置/回退”日志样本。它明确提到“变量未设置”场景作为首选，将其与查询日志等通用工具区分开来。目的具体且可操作。

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?

该描述表明它是“变量未设置”时的首选工具，为使用提供了明确背景。但它没有明确排除其他场景或提及替代方案，如 query_logs 或 diagnose_issue。上下文清晰，但缺乏何时不使用或选择其他工具的说明。

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 accurately describes the listing behavior and the data returned (uid/name/default/project count) which implies a read-only operation, but it does not disclose potential edge cases, performance implications, or any side effects. For a simple list operation, this is adequate but not exceptional.

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, front-loaded with the main verb ('list'), and uses two sentences to cover purpose and usage context without redundancy. Every word earns its place, and the structure is easy to scan.

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 no parameters, no output schema, and a straightforward listing operation, the description fully covers what the tool does and returns. It also provides relevant context about when to use it (multi-datasource environments). No additional information is needed for an agent to correctly select and invoke it.

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 schema description coverage is 100% (vacuously). The description does not need to explain parameters, and the baseline of 4 is appropriate since there are no parameters to clarify.

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 function: listing all Loki log data sources on the Grafana instance, along with specific attributes (uid, name, default status) and the count of registered projects per datasource. This is a specific verb+resource combination that distinguishes it from sibling tools focused on logs, labels, and queries.

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 'In a multi-data-source environment, use it first to confirm which data source to query,' providing clear context on when to use this tool. However, it does not mention any alternatives or when not to use it, so it falls short of a full 5, but gives solid usage 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?

工具具有 4 个参数和嵌套对象，但无输出 schema 也无注解，描述未说明返回的数据结构或错误处理方式。考虑到兄弟工具众多，描述未提供任何使用上下文或与其他工具的关联，如何时需要先使用 list_datasources 或 list_projects。对于此复杂度的工具，描述明显不完整。

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 对 4 个参数均有描述，覆盖率达 100%，因此基线为 3。描述中提到了'时间窗'对应 range 参数，但未提供超出 schema 的额外信息，如参数的互斥关系或默认行为。描述未详细解释 labels 和 project 的使用差异，但 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?

描述明确说明工具列出指定数据源或项目在时间窗内可用的日志标签名（如 app/group/host/level），使用动词'列出'和具体资源'日志标签名'。但未明确与兄弟工具如 list_label_values（列出标签值）的区别，不过从名称和描述可推断是列出标签键，整体清晰但未强化区分。

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?

描述仅说明功能，没有提供何时使用此工具 vs 替代方案的指导。未提及何时使用 project 参数 vs labels 参数，也未提及当需要特定标签的取值时应该使用 list_label_values。缺少使用场景和排除条件。

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?

没有 annotations，但描述中未说明读取行为、权限、速率限制、返回格式或副作用；仅从“列出所有取值”推断为只读操作，缺少对数据来源或缺失标签时行为的说明。

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、错误行为、权限/副作用信息，也未说明此工具与 query_logs / list_labels 等相近工具的关系。 label 取值可能受数据源选择影响，但未说明。

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 描述覆盖率为100%（5/5 个参数），描述确实为 range（含格式与默认值）、labels（对未登记标签传参）、labelName（示例）提供了额外含义，但未完全说明每个字段的边界和要求。

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?

描述使用了具体动词+资源结构：“列出指定标签在时间窗内的全部取值”，并带有示例（labelName=app 列出所有服务名），能清晰区别于同类工具，但未与相似工具（如 list_labels）明确区分。

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?

没有说明何时用此工具而非其他替代工具（如查询日志、完整行查询），也没有排除条件或使用前提。仅凭“列出标签值”这一上下文隐式暗示用途。

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 that it queries all Loki data sources in real-time, defaults to last 24h, and returns data source attribution and registration status. This is useful behavioral information, though it doesn't mention potential limitations or side effects (e.g., performance, read-only nature). Could be more explicit, but given no annotations, it's decent.

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 a single, dense sentence that conveys purpose, scope, default behavior, and usage context. No fluff, all relevant info.

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?

The description provides key context: it aggregates registered and discovered projects, defaults to a 24h window, and includes data source and status attribution. However, there is no output schema, so the exact return structure (fields, counts) is not specified, which could be important for an agent to plan further steps. But given it's a discovery tool, the level of detail is acceptable.

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 clearly shows zero properties, so there is nothing ambiguous. The description doesn't need to explain any parameters, and the 100% schema coverage ensures the agent knows there are none.

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 'list all queryable projects' and specifies two sources (registered projects with Chinese aliases, and real-time discovered app/group combinations from Loki data sources). It explicitly differentiates from siblings like list_datasources, which focuses on data sources themselves, and list_label_values, which deals with label keys. The verb 'list' and resource 'projects' are specific.

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 explicitly says to call this when you don't know the project name ('不知道项目叫什么时先调这个'), providing clear contextual guidance. It doesn't mention when not to use it, but the positive directive is strong. Alternatives are implied through sibling tools like list_datasources, but not explicitly excluded.

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 full disclosure burden. It does reveal behavioral mechanics (bucketed counting, spike multiplier relative to a baseline, abnormal start-time detection), which adds value. However, it omits output shape, how the baseline is derived, pagination, and data limits — notable gaps given the absence of both annotations and an output schema.

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 packed in two sentences — one defining the algorithm components (bucket count, baseline multiplier, abnormal start time) and one framing the diagnostic question answered. It is front-loaded and free of filler, though its brevity trades away useful detail that would help the agent.

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 8 parameters, no annotations, and no output schema, the description is comparatively thin. It conveys the core purpose and algorithm but leaves unclear how the baseline is established, what the result structure looks like, whether returned timestamps are relative to the input range, and how filter parameters influence detection. More elaboration is warranted for this complexity level.

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 only 25% (2 of 8 params described). The description implicitly connects the interval param to bucketed counting and range to trend viewing, but leaves labels, keyword, project, datasourceUid, start, and end unexplained. The description does not compensate adequately for the missing schema documentation on six parameters.

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 detects log volume trends and spikes via bucketed counting, baseline multiplier ratios, and abnormal start times, ending with the question it answers ('when did the problem start'). This distinguishes it from raw query (query_logs), baseline comparison (compare_baseline), and error summarization (summarize_errors) siblings, though the verb is implied rather than explicit.

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 implies use for temporal diagnosis ('回答什么时候开始出问题') but provides no explicit when-to-use or when-not-to-use guidance. With 14 siblings including closely related tools like compare_baseline and query_logs, there is no direction on which to prefer for trend visualization vs. raw retrieval, nor any exclusion criteria.

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 zero annotations, the description carries the full burden and largely delivers: it discloses hard caps on rows/line length/total response, indicates truncation markers ('超出会标注省略'), and reveals the platform's protective limits. Slight gap: doesn't explicitly state read-only safety, rate limits, or failure 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?

Three sentences, each earning its place: purpose, volume-control strategy, and when-to-use vs alternative. Front-loaded and telegraphic, no fluff. The semicolon-delimited hard-cap list packs maximum information density per character.

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 high-complexity tool (13 params, no output schema, no annotations), the description covers the critical operational concern (data volume) thoroughly, including defaults and caps, and points to how to avoid hitting limits. Could add error/auth comments or output format hints, but the volume story—the main pitfall for log queries—is well told.

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 92%, so per rubric the baseline is 3 and the schema already documents per-parameter meaning well (e.g., requestId 'strongly recommended', range default, maxPages formula). The description adds cross-parameter strategy (combine requestId + narrow time window) which is genuinely useful but mostly reinforces rather than extends schema semantics.

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?

Starts with a specific verb+resource ('Query raw logs') and immediately distinguishes scope. The closing sentence explicitly contrasts with diagnose_issue ('automatic aggregate analysis' vs 'precise evidence following clues'), which disambiguates from siblings and reinforces purpose.

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 names diagnose_issue as the preferred tool for production troubleshooting, and positions this tool ('suitable for...') for clue-based evidence collection. Also gives concrete operational guidance (use requestId, pair with narrow time windows, default 15m) that tells the agent when and how to invoke 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?

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: automatic pairing of slow SQL statements by connection-order, aggregation when >30 rows, and that only the slowest samples are kept in detail. This goes beyond a simple 'retrieve slow logs' and is honest about non-obvious behavior. Does not contradict any annotations.

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 core functionality. However, it packs multiple behavioral details into one long sentence, which could be slightly reorganized. Still, each sentence earns its place by covering distinct aspects: threshold, dimensions, auto-pairing, and aggregation.

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 (14 params, no output schema, no annotations), the description covers the main behaviors well but leaves gaps: no mention of default values for many parameters, no explanation of the return structure, and no guidance on how parameters like 'start'/'end' interplay with 'range'. It's adequate for basic use but not complete for advanced configurations.

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 only 29%, meaning 10 of 14 parameters lack descriptions. The description adds meaning to 'kind' (dimensions), 'minMs' (threshold), 'withSql' (statement retrieval), but does not explain other parameters like 'end', 'level', 'limit', 'range', 'start', 'labels', 'keyword', 'project', 'maxPages', 'requestId', 'datasourceUid'. With a low coverage, the description should compensate more, but it leaves many parameters ambiguous.

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 explicitly states the tool fetches slow logs by duration threshold, gives an example (SQL >30s), and enumerates three dimensions (sql/request/connection). This distinguishes it clearly from sibling tools like query_logs (general log querying) and trace_flow (tracing).

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 specific contexts for use: threshold-based slow log retrieval, dimensional variety, and aggregation behavior for >30 hits. It does not explicitly mention when not to use this tool vs alternatives, but the detailed context is clear enough for an agent to select it appropriately.

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 full behavioral burden. It discloses what the tool does (compresses errors, distinguishes first occurrences vs cascades, provides fault type, stack, requestId) but does not mention limitations, side effects, or edge cases. The disclosure is substantial and goes beyond mere verb repetition.

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 a single, information-dense sentence with a colon introducing a list of outputs. It is concise and front-loaded with the primary purpose, containing no filler words. Slight length is justified by the rich content.

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?

The tool has 8 parameters, no output schema, and no annotations. The description provides a good overview of outputs and distinguishes itself from log browsing, but lacks parameter details and does not specify return structure, limits, or error handling. It is adequate for a high-level understanding but incomplete for precise 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 description coverage is only 25% (only topN and range have descriptions). The description does not explain the parameters beyond implying a time window, nor does it detail labels, keyword, project, etc. Given the low coverage, the description fails to compensate, leaving most parameters ambiguous.

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: it aggregates and merges errors into patterns, distinguishes root causes from cascading noise, and provides fault classification, stack frames, and high-frequency requestIds. It also contrasts with direct error log browsing, distinguishing it from sibling tools like query_logs.

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 implies usage context by stating it is more efficient than flipping through error logs, suggesting it should be used when a summarized error analysis is needed. However, it does not explicitly state when NOT to use it or mention alternative tools, leaving some 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 provided, so the description carries the full burden. It discloses core behaviors: reconstructing the complete log chain for one request, sorting results in chronological order, and keeping the return set small and complete. However, it does not explain precedence when both requestId and traceId are supplied, time-window defaults, or empty/failure 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 is one compact, front-loaded sentence that conveys the operation, the use case, and the output characteristics. There is no filler, repetition, or redundant restatement 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?

With 8 optional parameters, no annotations, and no output schema, the description is usable but thin. It covers the main purpose, ordering, and return size, but omits parameter precedence, default time-window behavior, and how optional filters affect the reconstructed trace.

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 only 50%, and the description adds little beyond restating requestId/traceId as lookup keys. Parameters like start, end, labels, and datasourceUid lack meaningful explanation even in the schema, and the description does not clarify their role or how they interact with the time range.

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 uses a specific verb ('还原') with a clear resource ('完整日志链路'), scoped to a single request via requestId/traceId, and specifies chronological ordering. It also positions the tool for failed-request investigation, distinguishing it from broader log-query siblings.

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 explicitly states when to use the tool: '定位具体一次失败请求时用它' (use when locating a specific failed request), and notes the return volume is small and complete. It does not name alternatives or state when not to use it, so it stops short of a full 5.

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 is the main source of behavioral disclosure. It explains the core algorithm—take a template sequence, compare it with successful samples, locate the interruption—but does not disclose whether the operation is read-only, how the successful sample is selected, or what the return value looks like.

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 a single, front-loaded sentence with a clear purpose and a useful scoped scenario. Every part contributes meaning, and there is no redundant or filler content.

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 7 parameters, no annotations, and no output schema, the description carries substantial operational burden. It explains the comparison logic well but omits how to specify the target chain, what a successful sample is, and what the response will contain, making it adequate but incomplete for direct 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 description coverage is only 43%, and the tool description does not compensate by explaining which parameters are needed or how they map to the described flow. Terms like '链路' and '成功样本' are not connected to traceId, requestId, entityId, or labels, leaving the agent to infer parameter usage from the schema alone.

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 operation: flow completeness check, comparing a chain's log template sequence against successful samples to locate where the flow broke. It also distinguishes itself by positioning as the first choice for the 'flow disappears halfway without error' scenario, unlike sibling 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 description explicitly identifies the triggering condition ('流程走一半没了但不报错') and marks itself as the preferred tool for that case. However, it does not name alternatives or explain when not to use it, so only the when-to-use half is fully explicit.

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