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

Beyond the destructiveHint annotation, the description discloses a critical behavioral trait: agreeing at the final step triggers SQL execution, and it explicitly labels agree as high-risk. This adds important consequences that annotations alone do not convey.

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, well-structured sentence packed with essential operational details. It uses punctuation effectively to separate actions and conditions, with no wasted words.

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 covers the key behavioral aspects needed to use the tool correctly: actions, prerequisites, risk, and confirm requirement. Since there is no output schema, return values are not explained, but the description is sufficient for safe and 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?

Although the schema already describes all parameters (100% coverage), the description enriches the flag parameter with cross-tool usage (use yearning_order_timeline to confirm) and clarifies that reject requires a reason. This adds meaning beyond the raw 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 tool audits work orders with three specific actions (agree, reject, undo) and even mentions the corresponding API endpoint. It distinguishes itself from list-oriented siblings like yearning_audit_orders by focusing on state-changing operations for a single order.

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 concrete guidance: use yearning_order_timeline to confirm the current step (flag), provide a reason when rejecting, and set confirm=true for agree. It gives clear context for when to use the tool, though it does not explicitly contrast with alternative tools like yearning_undo_order.

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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the current-user scoping and auditor perspective, but doesn't disclose pagination behavior or response format, which is acceptable given the annotation coverage.

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?

Two short sentences, front-loaded with purpose, includes the endpoint for traceability. No redundant 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?

For a simple list tool with 6 optional params and no output schema, the description gives core purpose and scope but doesn't clarify that the status filter allows non-pending statuses despite saying '待审核'. It also doesn't mention response format, though the response_format param exists.

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 50%, with text/status/work_id described. The description itself doesn't add parameter semantics, but page and page_size are self-evident from the '分页列出' verb. No critical parameter info is missing.

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 '分页列出' (paginated list) and names the resource '待审核工单' (pending audit orders), with an explicit auditor perspective and current-user scope. This clearly distinguishes it from siblings like yearning_my_orders and yearning_audit_order.

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 clear context: auditor perspective, current-user related, paginated. However, it doesn't explicitly name alternative tools or exclusion criteria, but the '审核人视角' implies when to use it over other order lists.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond the endpoint (GET), such as pagination, output behavior, or handling of hidden databases, so it adds no value beyond 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?

A single sentence efficiently states the tool's purpose and endpoint. There is no wasted content, making it highly concise.

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 list tool with good annotations and schema, the description is adequate but misses usage guidelines and any note about return values or output format. Since there is no output schema, a bit more context would have made it more 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?

The schema describes source_id and hide, covering 67% of parameters. The description does not add any parameter semantics; it only repeats the concept of 'specified data source' which is already in the schema, so the baseline score 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 uses the verb '列表' (list) with the resource '数据库列表' and specifies '指定数据源下' (under a specified data source), clearly distinguishing it from sibling tools like yearning_list_sources and yearning_list_tables. The API endpoint reference further confirms the operation.

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?

No guidance is provided on when to use this tool versus alternatives. The description only states what it does and the endpoint, without exclusions, prerequisites, or references to sibling tools.

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?

注释已提供 readOnlyHint=true, idempotentHint=true, destructiveHint=false，安全行为已被覆盖。描述额外补充了权限范围过滤（query/dml/ddl/idc），提供了授权和筛选方面的有用上下文，但未涉及返回格式或分页等行为。

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?

描述仅一句话，以动词'列出'开头，包含核心功能、过滤能力及 API 端点，信息密度高且无冗余内容。

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?

工具本身简单且注释覆盖安全属性，但描述未说明 response_format 参数，也没有输出 schema，导致返回格式不明确；仅凭描述无法知晓如何请求 JSON 输出。整体上对于列表类工具已算基本完整，但仍有明显缺口。

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?

描述对 tp 参数进行了扩展（'可按 query/dml/ddl/idc 过滤'），但未提及 response_format 参数。Schema 中 tp 描述为'数据源范围'，response_format 无描述，整体 schema 描述覆盖率约 50%，描述未能弥补这一缺口。

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?

描述明确为'列出当前账号有权限的数据源'，包含清晰动词、资源对象和权限范围。虽未显式对比 sibling 工具中的 list_databases/list_tables，但'数据源'这一概念足以区分主要用途，API 端点也增强了明确性。

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?

描述隐含了使用场景（发现当前账号有权限的数据源），但未明确说明何时使用此工具而非 list_databases 或 list_tables，也没有提供任何排除条件或替代工具指引。

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 already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false, so the safety profile is covered. The description adds that this corresponds to a GET endpoint, reinforcing read-only behavior, but adds no additional traits such as required permissions, rate limits, or response format behavior. With annotations present, a score of 3 is appropriate.

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, focused sentence that front-loads the primary purpose and adds the relevant API endpoint for traceability. No wasted words, perfectly sized.

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 list tool with only 3 parameters and no output schema, the description plus annotations provide enough context for an agent to invoke it correctly. It does not describe the response format or pagination, but given the simplicity and the presence of openWorldHint, this is not a critical gap. Sibling names and schema details fill in remaining context.

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 descriptions cover database (库名) and source_id (数据源 ID), with response_format having enum and default values. The description simply restates '指定数据源、指定库' without adding syntax or format details beyond the schema. Since schema coverage is 67%, the description provides marginal added value, so baseline 3 is suitable.

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 '列出指定数据源、指定库下的表' (list tables under specified data source and database), using a specific verb and resource. It unambiguously distinguishes this from sibling tools like list_sources and list_databases by scoping to tables within a given source/database, and also references the API endpoint GET /api/v2/fetch/table.

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 when to use it (when needing to list tables for a specific data source and database) but does not explicitly mention alternatives or exclusions. Context of sibling tools and the clear scope provide adequate guidance, though not as explicit as naming when not to use 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. Description adds value by enumerating status code meanings (8=全部, 2=待审核, etc.) and the backend WS endpoint, giving context beyond annotations without contradicting them.

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 concise, with the core purpose in the first sentence, followed by essential status codes and endpoint mapping. Every sentence earns its place with no unnecessary detail.

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 list tool with no output schema, the description provides enough context: purpose, pagination, status filter values, and the target API. It doesn't describe return format, but response_format parameter exists, making this adequate.

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 covers 5/6 parameters (83%), but the description enriches parameter semantics by providing a full mapping of status codes, which the schema only partially covers. It does not explain response_format, but the status mapping is significant value added.

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 '分页列出当前用户提交的工单' (paginated list of current user's submitted orders), specifying verb, resource, and scope. This distinguishes it from siblings like order_detail (single order) and audit_orders (auditing).

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 context that this is the current user's order list, but does not explicitly state when to use this vs alternatives or mention exclusions. It identifies the underlying API endpoint, which hints at usage, but lacks explicit guidance like 'for a single order use order_detail'.

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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds the behavioral detail that it reads ALL comments for a specified work order, which is useful. It also provides the corresponding WS endpoint. However, it does not disclose additional traits such as pagination, permissions, or response format behavior beyond what annotations cover.

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 extremely concise, consisting of two short sentences. The first sentence clearly states the purpose, and the second provides a technical endpoint reference. Every word earns its place, with no redundant content. It is front-loaded and easy to parse.

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 simple nature (read-only, two parameters, no output schema), the description is mostly complete. It clearly states the action and resource, and annotations cover safety profile. However, it does not mention the response_format parameter's effect on the output (markdown vs json), nor does it describe the structure of the returned comments. These gaps are minor for a straightforward read operation, but a slightly richer description would improve completeness.

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% (work_id has a description, response_format does not). The description does not compensate for this gap by explaining either parameter. It does not mention that work_id is the work order number or that response_format controls the output format (markdown/json). The endpoint reference is not parameter-related. Overall, the description adds no semantic value beyond what the schema already provides.

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: '读取指定工单的全部评论' (read all comments for a specified work order). It uses a specific verb ('读取' - read) and identifies the resource ('工单' - work order) and the scope ('全部评论' - all comments). This distinguishes it from sibling tools like yearning_post_comment (which posts comments) and yearning_order_detail (which likely fetches order details).

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 the tool should be used when a work order's full comment list is needed, but it does not explicitly state when to use it versus alternatives. There is no mention of exclusions or comparison with sibling tools such as yearning_order_timeline. The endpoint reference 'WS /api/v2/fetch/comment' provides technical context but no 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?

Annotations already mark readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it maps to two GET endpoints (/fetch/detail + /fetch/sql) and specifies the output scope (SQL details and complete SQL), but does not disclose pagination or response format behavior. No contradiction with 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?

One short sentence with clear subject and endpoints; no filler or repetition. Front-loaded in Chinese and every word 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?

As a read-only detail retrieval tool with no output schema, the description provides a basic return summary (SQL details and full SQL) and endpoint mapping but lacks guidance on pagination behavior, response format options, and when to use this tool versus siblings. This leaves meaningful gaps for an agent but remains adequate for basic 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 work_id has a description ('工单号'). The description does not explain page, page_size, or response_format meanings and does not compensate for the low schema coverage. The tool's title implies work_id refers to an order, but no detailed parameter semantics are provided.

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 '查看工单详情：SQL 明细与完整 SQL' (view order details: SQL details and full SQL), specifying the exact resource and scope. It also names the corresponding endpoints, which distinguishes it from siblings like yearning_order_timeline and yearning_rollback_sql.

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 no usage guidance: no when-to-use conditions, exclusions, or references to alternative tools for different order-related needs. It only states the function, so agents cannot determine when to prefer this over yearning_order_timeline or yearning_my_orders.

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 already declare readOnly, idempotent, and non-destructive. The description adds value by mapping to GET endpoints (confirming read-only semantics) and explaining that the flag for audits originates here, which is useful behavioral context beyond the 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 three short sentences, each contributing unique information: what the tool does (view timeline/steps), why it matters (audit flag source), and API mapping. No wasted words.

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 good annotations and a clear purpose. It explains the audit-flag context and the underlying endpoints. Although there is no output schema, the description gives enough for a read-only timeline tool, though the exact return structure is left unspecified.

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 67%: work_id and source_id have descriptions, response_format has an enum/default but no explicit description. The tool description itself does not add parameter details, but the schema already covers most parameters adequately. Overall, the description neither compensates nor detracts.

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 ('查看' meaning view) and names the exact resource (工单审核时间线 with 流程步骤). It also adds a distinct use case (审核时 flag 取自此处) that differentiates it from sibling tools like order_detail and audit_orders.

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 clearly states when to use the tool ('审核时 flag 取自此处' — when reviewing, the flag is taken here). It does not explicitly mention alternatives or exclusions, but the 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?

Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds no additional behavioral context—it only restates the action and the corresponding HTTP method. It does not disclose side effects, auth requirements, or response behavior. The description neither contradicts the annotations nor enriches them.

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 extremely concise, consisting of two short sentences: one stating the purpose and one mapping to the API. No redundant information is included. Every word serves a purpose, making it easy to read and process.

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 no output schema and the annotations are minimal. The description lacks information about return values, success/failure indicators, or any side effects beyond 'posting a comment.' Given the simplicity of the tool, some guidance on expected response or error handling would be valuable but is entirely absent. The description is not complete enough to fully inform an agent unfamiliar with the system.

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 descriptions for both required parameters (comment content and work order number), achieving 100% schema coverage. The description does not add any further meaning or examples beyond what the schema already states. Given the high schema coverage, 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 (发表/post) and resource (工单/comment under a work order), and includes the API endpoint for reference. However, it does not explicitly differentiate from sibling tools like yearning_order_comments, which likely lists comments rather than creating them. The specificity is high, but the lack of explicit sibling distinction keeps it from 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?

No guidance is provided about when to use this tool versus alternatives, prerequisites, or exclusions. The API mapping (POST /api/v2/fetch/comment) hints at a write operation, but does not tell the agent when to choose this over similar tools like yearning_submit_order or yearning_order_comments. There is no mention of required permissions or typical use cases.

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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the specific endpoints and the two status items being checked, but fails to explain response behavior or any limitations, such as what happens if the audit switch is off.

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 that front-loads the core functionality and includes the endpoint mapping. No unnecessary words or repetition.

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 is simple with rich annotations, but the description omits parameter semantics and usage context. While the core purpose is clear, the lack of guidance on when to use it and how response_format affects the output leaves gaps that the agent must fill elsewhere.

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 only parameter, response_format, is not mentioned in the description, and the schema has no property descriptions (0% coverage). The description does not compensate by explaining how choosing 'markdown' vs 'json' affects the output or what the default is.

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: checking the query audit switch and whether the current user's query work order is valid, with reference to the two specific GET endpoints. This distinguishes it from sibling tools like yearning_sql_check or yearning_my_orders.

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 no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It only states what it does, leaving the agent to infer when it should be called.

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 already declare read-only/idempotent; description adds only the API endpoint mapping, no further behavioral details.

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?

Single sentence, front-loaded with the key action and endpoint, no wasted words.

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?

Simple tool with rich annotations and schema enum; description provides the core purpose, though it omits response format details absent 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?

Description adds no meaning beyond schema; response_format lacks explanation, and only work_id is described in schema (50% 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?

States specific verb '获取' (get) and resource '工单的回滚 SQL' (work order rollback SQL), clearly distinguishing from sibling order 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?

No explicit when-to-use or alternative guidance; usage is implied by the purpose alone.

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 already declare readOnlyHint and destructiveHint, and the description adds that query permission is required and that audit may require a prior submission order, which is valuable behavioral context. It also notes the msgpack transport, disclosing the response format underlying the tool. No contradiction with 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 a single compact sentence that front-loads the core action, then tacks on constraints and the endpoint reference. Every clause earns its place, 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?

For a read-only query tool with good annotations and schema, the description includes permissions, audit workflow, and the underlying protocol. It could mention how to handle long-running queries or the relationship to `yearning_sql_check`, but it's otherwise complete for the tool's purpose.

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 covers 4 of 5 parameters with descriptions (80% coverage), so the baseline is 3. The description adds no additional parameter-level semantics beyond reinforcing that SQL must be SELECT, which is already in the schema. Therefore, no extra value 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 uses a specific verb ('执行') and resource ('指定数据源') with a clear read-only SELECT scope, and distinguishes from siblings like `yearning_sql_check` and `yearning_submit_query_order` by indicating this executes the query directly. It also references the underlying WS endpoint, further clarifying its role.

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 a prerequisite (query permission) and a conditional alternative: if audit is on, first use `yearning_submit_query_order`. This gives clear when-to-use guidance, though it doesn't compare with other sibling query-related tools like `yearning_sql_check`, so not 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?

Annotations already convey read-only and idempotent behavior. The description adds useful context: it's a pre-submission check, maps to a specific API endpoint, and rejects SELECT statements. This goes beyond the annotations without contradicting them.

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 concise sentences, each providing essential information: purpose, usage order, and a key exclusion. No redundant content; front-loaded with the primary function.

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 output schema, the description explains purpose, usage, and constraints, which is mostly sufficient. It lacks detail on the return value/audit result, but the 'response_format' parameter hints there is a formatted output. Overall, it covers the key contextual needs.

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 descriptions cover 80% of parameters. The description adds a critical semantic constraint on the 'sql' parameter by explicitly stating SELECT is not accepted, clarifying it should be DDL/DML. This provides meaning beyond the schema's field descriptions.

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 performs SQL review before submission with a specific verb and resource ('对 SQL 做审核检测'). It distinguishes itself from siblings by mentioning the intended sequence with yearning_submit_order and explicitly excluding SELECT (delegating to yearning_run_query).

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 when-to-use guidance ('建议先调用本工具，再 yearning_submit_order') and an alternative for SELECT queries ('请用 yearning_run_query'). This is concrete and distinguishes from sibling tools.

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?

Adds context beyond annotations: mentions the API endpoint POST /api/v2/common/post and requires confirm=true to truly submit, implying a confirmation guard. It doesn't contradict readOnlyHint=false or destructiveHint=false, and adds the pre-check recommendation.

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?

Four short sentences each add value: purpose, pre-check recommendation, API mapping, and confirm requirement. No redundant text, and it is front-loaded with the core 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?

The description plus schema provides enough to invoke: confirm requirement and all parameters are documented. It omits return value but no output schema exists; still, for a mutation tool with 11 params, it is reasonably 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 covers all 11 parameters with descriptions (100% coverage). Description only highlights confirm=true, which is already in the schema, adding no new parameter 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?

Description clearly states it submits SQL work orders for DDL/DML, using the verb '提交' (submit) and resource 'SQL工单'. It distinguishes from sibling yearning_submit_query_order by specifying DDL/DML, making its 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?

Explicitly recommends running yearning_sql_check before submission and mandates confirm=true for actual submission. This gives clear when-to-use guidance, though it doesn't explicitly list alternatives like yearning_submit_query_order.

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 annotations indicating readOnlyHint=false (write operation), the description adds value by disclosing the approval workflow (approval needed before run_query) and the HTTP endpoint (POST /api/v2/query/post). It does not contradict annotations and provides behavioral context beyond the structured fields.

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 concise sentences: the first states the primary purpose, the second adds workflow context and the API endpoint. Every sentence earns its place, with no redundant or extraneous 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 description covers the purpose and approval workflow, but since there is no output schema, it does not mention what the response looks like (e.g., order ID). Given the tool's mutation nature and the need for further steps (like querying order status), this is a notable omission that affects completeness.

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%, with all three parameters (export, remark, source_id) having individual descriptions. The tool description does not add additional semantic meaning beyond what the schema already provides, so the baseline score 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 action and resource: '提交数据查询申请' (submit a data query application). It distinguishes from siblings by explicitly referencing 'yearning_run_query' and the query submission context, differentiating it from generic submit tools like 'yearning_submit_order'.

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: use this to submit a query application, and mentions that if audit is enabled, approval is required before running the query with 'yearning_run_query'. However, it does not explicitly state when not to use this tool or name alternative tools, leaving a slight gap.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds the return content (fields and indexes) and the HTTP endpoint. However, it does not disclose behaviors like pagination, result limits, or whether indexes are nested or flattened, so it only modestly expands beyond the 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 a single, compact sentence that front-loads the purpose, then lists the exact returned components and API mapping. Every clause adds value and there is zero redundancy, making it highly efficient.

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 low-complexity read-only operation, strong annotations, and schema that documents most parameters, the description is nearly complete. It specifies the return payload structure (fields with attributes and indexes) and the API endpoint. It lacks only minor context (e.g., whether response_format changes the structure), but overall it is sufficient for an agent to invoke 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?

Schema description coverage is 75% (three of four parameters have Chinese descriptions). The description does not add additional semantics beyond the schema; for instance, it does not clarify the format of source_id or how response_format affects output. Since coverage is high, a 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 what the tool does: '查看表结构' (view table structure) and enumerates the exact content: field list (type/nullable/key/default/comment) and indexes. It also names the specific API endpoint, making the operation unambiguous and distinguishing it from sibling tools like list_tables.

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 for inspecting table schema, but it does not explicitly state when to prefer it over alternatives (e.g., list_tables for only table names) or mention any prerequisites. The API endpoint provides a minor cue, but no explicit when/when-not 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?

Annotations provide readOnlyHint=false and destructiveHint=false, signaling a mutation but not a destructive one. The description adds the crucial behavioral fact that confirm=true is mandatory and maps to GET /api/v2/fetch/undo. However, it does not detail what happens if the order is already executed or the exact status change, but given annotations 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?

Two sentences with zero waste: the first states the action and condition, the second gives the endpoint and confirmation requirement. The most important information 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 2-parameter tool with no output schema, the description covers the core purpose, the user scope, the execution state, and the mandatory confirm parameter. It could potentially mention the effect on order status, but the description is adequate given the tool's simplicity and the existing annotations.

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 restates the confirm=true requirement already encoded in the schema's const:true, adding no new meaning beyond what the schema provides. It does not add details about work_id format or behavior beyond '工单号'.

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+resource: '撤回自己提交、尚未执行的工单' (withdraw your own submitted, not-yet-executed order), and also provides the corresponding API endpoint. This distinguishes it from sibling tools like submit_order and audit_order by specifying the action and scope.

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 clear context: only for own submitted orders that have not yet been executed, with mandatory confirm=true. It does not explicitly name alternative tools, but the scope ('自己提交、尚未执行') is a clear guideline. It lacks explicit exclusions such as 'do not use for orders already executed', but these are implied.

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 already declare readOnly, idempotent, non-destructive, and openWorld. The description adds the API endpoint and return fields (department, email, data source list), but does not disclose authentication needs or response format behavior. 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?

A single concise sentence in Chinese states the purpose and API endpoint with no filler. Information is front-loaded and every phrase 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?

For a simple read-only tool with no output schema, the description covers the main returned content (user info, department, email, data source list) and the API endpoint. It omits error and permission details, but these are less critical for a low-complexity info 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 single optional response_format parameter has a clear enum (markdown/json) and default value, making it self-explanatory in the schema. The description does not mention it, but the enum values provide enough meaning for correct invocation.

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 names the specific verb '查看' and resource: current logged-in user's info, department, email, and accessible data source list. This clearly distinguishes it from sibling tools like list_sources by focusing on identity plus permission-scoped sources.

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?

No guidance on when to use this tool versus alternatives such as list_sources or other user-related tools. The API endpoint mapping is useful but does not provide context, prerequisites, or exclusion criteria.

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