Server Quality Checklist

Tool Scores

• revoke_privilegeC
  2.6/5.0
  Behavior2/5

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

  Annotations already declare the tool as destructive (destructiveHint: true) and idempotent (idempotentHint: true). The description adds no behavioral context beyond the name – it does not mention consequences of revocation, failure modes, or whether the action is reversible. Since annotations already cover the safety profile, the description contributes minimal additional behavioral transparency.

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

  Conciseness4/5

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

  The description is extremely concise (two short sentences) and front-loaded with the core purpose. It avoids redundancy and is easy to parse. However, it is slightly too terse – it could include a bit more context without becoming bloated, but the conciseness itself is appropriate.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness1/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description is severely incomplete for a destructive tool with two required parameters. It fails to explain what 'grantee' means, what privileges can be revoked, any side effects, or what happens if the privilege does not exist. Given the destructive nature, essential context is missing, making it difficult for an agent to use the tool correctly.

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

  Parameters2/5

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

  With 0% schema description coverage, the description must compensate for parameter meaning. It only mentions that the privilege format is the same as grant_privilege, which gives a hint for the 'privilege' parameter but leaves 'grantee' undefined. No details on allowed values, syntax, or examples are provided, so parameter semantics are largely unexplained.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: '回收权限' (revoke privilege). It names a specific action and resource, and the reference to grant_privilege for format helps distinguish it as the inverse operation. However, it does not explicitly state that it removes a previously granted privilege from a grantee, leaving some ambiguity for less familiar users.

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

  Usage Guidelines2/5

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

  There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites or exclusions. The only hint is that the privilege format matches grant_privilege, which is a format reference, not usage guidance. It does not explain when a privilege should be revoked or what conditions apply.

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

• grant_privilegeB
  3/5.0
  Behavior1/5

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

  The description provides no information about side effects, required permissions, or the mutating nature of the operation. While the tool name implies modification, the description does not disclose potential risks or consequences, leaving the agent without awareness of the impact.

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

  Conciseness5/5

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

  The description is concise and well-structured, using a single sentence followed by examples. There is no redundant information, and the examples directly illustrate the parameter format, making it easy to parse.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given that this is a mutating operation with no output schema, the description could be considered complete in terms of not needing to explain returns. However, it lacks any mention of usage context, such as typical use cases, prerequisites, or relationship to other tools, making it incomplete for an agent to fully understand its role in a larger workflow.

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

  Parameters3/5

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

  The description explains the 'privilege' parameter with examples, adding value beyond the schema's generic description. However, the 'grantee' parameter is not elaborated; the schema's description ('被授权的用户名') is minimal, and the tool description does not clarify what constitutes a valid grantee or any constraints.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: granting privileges. It provides concrete examples (e.g., 'SELECT ON TABLE t', 'ALL PRIVILEGES ON DATABASE d') that illustrate the expected format, making the intent unambiguous.

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

  Usage Guidelines2/5

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

  The description does not mention when to use this tool versus alternatives (e.g., revoke_privilege). It lacks guidance on scenarios where granting privileges is appropriate, prerequisites, or any conditional context that would help the agent decide when to invoke it.

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

• create_userB
  3.2/5.0
  Behavior2/5

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

  Annotations already indicate a write operation (readOnlyHint: false) and that it is not destructive. However, the description adds no behavioral context beyond that, such as whether the user is created with no privileges, error handling for existing users, or authentication requirements.

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

  Conciseness4/5

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

  The description is a single, concise sentence that is front-loaded and directly conveys the core purpose. However, it is extremely sparse and could convey more useful context without becoming verbose, so it does not earn a 5.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool is simple with few parameters and an output schema absent. The description plus schema is adequate for a basic understanding, but it falls short by not mentioning crucial contextual details like the user being created without privileges or any prerequisites, which is important given the sibling tools for privileges exist.

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

  Parameters3/5

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

  Schema description coverage is 100% for both parameters (username and password), so the schema already documents their meaning. The description adds no additional parameter insight, but it does not need to compensate since the schema is complete.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the action: 'create a database user that can log in'. It uses a specific verb and resource, and it is distinguishable from sibling tools like grant_privilege or list_users. No ambiguity exists.

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

  Usage Guidelines2/5

  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, such as whether privileges need to be granted separately or if prerequisites exist. It simply states the action without context.

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

• list_sequencesB
  3.3/5.0
  Behavior3/5

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

  The readOnlyHint annotation already indicates a read-only operation. The description adds no conflicting or extra behavioral details, so it neither enhances nor contradicts the annotation. Transparency is adequate but not enriched.

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

  Conciseness5/5

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

  The description is extremely concise, using only two short clauses with no redundancy. Every word serves a purpose, fitting the ideal for a simple list operation.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the simplicity of the operation and lack of output schema, the description is reasonably complete. However, it omits any mention of output format, possible errors, or whether all sequences are returned when no schema filter is applied. Acceptable but not thorough.

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

  Parameters3/5

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

  The single optional parameter 'schema' is mentioned as a filter, but the description lacks details on how the schema value should be formatted or what the default behavior is when omitted. Minimal added value beyond the schema's type.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool lists sequences, using the verb 'list' and a specific resource. It distinguishes from sibling tools like list_tables or list_views, though 'sequence' could be more explicit in a database context.

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

  Usage Guidelines2/5

  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 says optional filtering by schema, but doesn't clarify typical use cases.

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

• transaction_rollbackB
  3.3/5.0
  Behavior4/5

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

  Annotations indicate destructiveHint=true, which signals a destructive operation; the description does not contradict this. The description adds value by stating the requirement of a valid handle from transaction_begin, which is critical context beyond the annotations. It does not describe side effects like discarding changes, but annotations cover safety. With annotations present, the description provides useful context, justifying a 4.

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

  Conciseness4/5

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

  The description is a single sentence, concise and front-loaded. It conveys the action and the required input. It is slightly terse but efficient, with no unnecessary words. This is close to a 5 but the brevity means it lacks some detail, so a 4 is appropriate.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the simplicity (single parameter, no output schema), the description covers the core action and the source of the handle. It does not explain side effects or what happens after rollback, but with destructive annotations and sibling tools, it is minimally complete. However, it could mention that it ends the transaction, but it is adequate for the complexity.

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

  Parameters3/5

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

  Schema coverage is 0%, so the description must compensate for the parameter 'tx_handle'. The description mentions the handle from transaction_begin, which adds meaning to the parameter (it's a handle type). However, it does not explain format or constraints, but for a single string parameter, this is minimal. Baseline for low coverage would be lower, but the description does provide some context.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose3/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states '回滚事务' (rollback transaction) which clearly identifies a rollback operation on a transaction. However, it does not specify the resource (the transaction handle) beyond the schema, and while it is distinct from transaction_begin and transaction_commit, it lacks explicit differentiation. The purpose is clear but not elaborated for sibling distinction.

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

  Usage Guidelines3/5

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

  The description implies usage requires a handle from transaction_begin ('需提供 transaction_begin 返回的句柄'), which gives context on when to use the tool. However, it does not explicitly mention when not to use it or alternatives. It states the prerequisite but lacks exclusions or alternative recommendations, so it's clear but not explicit.

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

• executeB
  3.4/5.0
  Behavior1/5

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

  The description contradicts the idempotentHint annotation: it describes executing arbitrary SQL that includes non-idempotent operations like INSERT/DELETE, while the annotation declares idempotentHint true. This is a direct contradiction, so the transparency score must be 1 per rubric.

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

  Conciseness5/5

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

  The description is two short sentences, front-loaded with the core purpose, and includes critical warnings and transaction usage without any filler. Every sentence earns its place, making it highly efficient.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no output schema and two simple parameters, the description adequately covers the action, return type, transaction handling, and safety warnings. However, the contradiction with idempotency annotation and the lack of clarity about SELECT handling (though 'arbitrary SQL' might imply it) leave minor gaps, preventing a perfect score.

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

  Parameters3/5

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

  Schema coverage is 100% for both parameters (sql and tx_handle) with clear descriptions. The tool description adds only transactional context for tx_handle and mentions the return format, but does not enrich parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states it executes arbitrary SQL (INSERT/UPDATE/DELETE/DDL) and returns affected row count, distinguishing it from siblings like query (for SELECT) and dedicated mutation tools (insert_rows, update_rows, delete_rows). The verb+resource is specific and unambiguous.

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

  Usage Guidelines3/5

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

  The description mentions optional tx_handle for transaction execution and warns about dangerous operations, but does not explicitly state when to prefer this over dedicated tools or when not to use it. Usage context is implied rather than explicitly contrasted with alternatives.

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

• list_sessionsB
  3.4/5.0
  Behavior3/5

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

  The annotations already indicate readOnlyHint=true, so the read-only nature is covered. The description does not add any additional behavioral details (e.g., no side effects, permissions needed), but since the operation is simple and annotations cover the main trait, this is adequate.

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

  Conciseness5/5

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

  The description is a single, clear sentence that immediately conveys the tool's purpose. It is concise, front-loaded, and contains no extraneous information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple, parameterless, read-only tool, the description sufficiently explains what it does. It does not elaborate on the output format, but given the low complexity and the annotations covering read-only behavior, it is reasonably complete.

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

  Parameters3/5

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

  The schema has no parameters, so schema coverage is 100%. Per the rubric, this yields a baseline score of 3 even though the description provides no parameter-specific information, as there are none to describe.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: viewing current active sessions via pg_stat_activity. It is specific and distinguishes this tool from sibling tools that list tables, views, or other database objects.

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

  Usage Guidelines1/5

  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. It only states what it does, without any context about prerequisites, conditions, or when other tools might be more appropriate.

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

• list_usersA
  3.5/5.0
  Behavior3/5

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

  The description is consistent with the readOnlyHint annotation but adds no additional behavioral context beyond what the annotation already conveys. It does not disclose return format, pagination, or any specific attributes—an opportunity for enrichment is missed, but no contradiction exists.

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

  Conciseness5/5

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

  The description is a single, complete sentence in Chinese, directly stating the action and subject. It is economical and front-loaded, with no redundant content.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with no parameters and no output schema, the description is mostly adequate—it names the resource and the action. However, it could explicitly mention that it returns all users or list the attributes to be returned, which would enhance completeness. Despite this, the tool's simplicity and readOnlyHint keep the description sufficient.

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

  Parameters4/5

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

  With zero parameters, the schema provides complete coverage (100%) and the description adds nothing—which is acceptable. Baseline of 4 applies because the tool's simplicity means no param explanations are needed.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool lists database users and their attributes, which is a specific verb and resource. It distinguishes from sibling tools like list_tables and list_views by targeting 'users', but does not explicitly mention scope or filtering, so it doesn't fully differentiate all siblings.

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

  Usage Guidelines2/5

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

  There is no guidance on when to use this tool versus alternatives. The description provides no context about prerequisites, typical use cases, or when not to use it. The agent must infer from the name alone, which is minimal.

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

• list_viewsA
  3.6/5.0
  Behavior3/5

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

  注解已声明readOnlyHint=true，描述未添加额外行为信息，如返回格式或限制，但未与注解冲突，注解已覆盖主要安全特性，因此评分3。

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

  Conciseness5/5

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

  描述仅一句话，简洁清晰，没有冗余内容，信息密度高。

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  对于简单只读列出工具，描述足够，但未提及返回内容或限制，不过缺少输出schema，且工具复杂度低，可接受。

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

  Parameters3/5

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

  尽管schema描述覆盖率为0%，描述提到'可选按schema过滤'为schema参数提供了基本语义，但未说明格式或允许的值，对于简单字符串参数来说信息有限。

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  描述'列出视图'明确指出了动作和对象，与兄弟工具list_tables、list_schemas形成区分，清晰指出列出视图，并说明可选按schema过滤。

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

  Usage Guidelines2/5

  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.

• database_statsA
  3.7/5.0
  Behavior3/5

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

  The annotation readOnlyHint=true already declares this as a safe read operation, so the description doesn't need to repeat that. The description adds value by listing the specific statistics returned (version, size, connections, etc.), which is useful context beyond the annotation. However, it doesn't disclose any potential side effects or performance implications, though for a read-only stats tool this is less critical.

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

  Conciseness5/5

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

  The description is a single, concise sentence that lists the key statistics in a compact, front-loaded manner. Every word earns its place, and it avoids unnecessary elaboration. This is an example of efficient, well-structured description.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's simplicity (no parameters, no output schema, read-only annotation), the description is complete enough. It covers the main purpose and the specific data points returned. It could potentially mention that the output is a summary or snapshot, but that's a minor gap. The description is adequate for an agent to understand what to expect.

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

  Parameters4/5

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

  The tool has zero parameters, and the schema coverage is 100% (vacuously). The description adds meaning by explaining what the tool returns, which is the main value for a parameterless tool. Since there are no parameters to document, the description's role is to clarify the output, which it does effectively.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: viewing database statistics including version, size, connections, current user, server address, and time. It uses a specific verb ('查看' meaning 'view') and resource ('数据库统计' meaning 'database statistics'), which distinguishes it from sibling tools like list_tables or list_sessions. However, it could be more explicit about the read-only nature, though the annotation already covers that.

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

  Usage Guidelines3/5

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

  The description implies usage for checking general database health and environment info, but it does not explicitly state when to use this tool versus alternatives like list_sessions or list_databases. It provides a clear context (viewing stats) but lacks explicit exclusions or alternative guidance.

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

• describe_tableA
  3.8/5.0
  Behavior4/5

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

  The annotation readOnlyHint: true already marks this as a safe read operation, and the description complements it by detailing the exact output structure (column name, type, length, etc.). While it doesn't discuss error cases or authorization, the read-only nature is transparent and nothing contradicts 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.

  Conciseness5/5

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

  The description is a single, focused sentence that immediately conveys the tool's function and output, with no wasted words or unnecessary detail.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a read-only describe operation with no output schema and a well-understood purpose, the description is complete and self-sufficient. The listed attributes fully define the return value, making the tool adequate for its intended use even without additional context.

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

  Parameters3/5

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

  Schema description coverage is 100%, with both 'table' and 'schema' parameters clearly described inline. The tool description adds no additional parameter-level insight beyond what the schema already provides, so the baseline score of 3 applies.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: '查看表结构' (view table structure) and enumerates the exact attributes returned (column name, data type, length, nullable, default value, primary key). This specific verb+resource combination distinguishes it from sibling tools like list_tables and list_indexes, and it is not a tautology.

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

  Usage Guidelines2/5

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

  No explicit guidance is given on when to use this tool compared to alternatives such as list_tables or list_views. There is no mention of when not to use it or any preconditions, leaving the agent to infer usage solely from the name and description.

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

• list_tablesA
  3.8/5.0
  Behavior3/5

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

  注解已提供readOnlyHint=true，描述未增加额外行为透明度，如返回大小格式、是否包含临时表等。描述本身是无害的读取操作，符合注解，未矛盾。但没有提供注解之外的行为信息。

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

  Conciseness5/5

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

  描述仅一句话，信息密度高，无冗余，直接点明功能。

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  工具简单，一个可选参数，无输出schema，描述足以让代理理解功能。考虑到仅一个参数且覆盖良好，描述完整。

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

  Parameters3/5

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

  schema描述覆盖100%，schema属性schema有描述“可选,只列出该 schema 下的表”。描述本身也提及按schema过滤，与schema信息一致，但未增加更多语义，如schema名称格式、默认行为等。

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  描述清楚说明了动词“列出”和资源“数据库的所有表及大小”，并提到可选按schema过滤。虽然未显式区分兄弟工具，但功能独特（列出表及大小），与list_views、list_indexes等区分明显。

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

  Usage Guidelines4/5

  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.

• list_indexesA
  3.9/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds the schema filtering capability. No contradictions. It doesn't detail output format but that's acceptable given the simple nature and annotations.

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

  Conciseness5/5

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

  One short sentence, front-loaded, no extra words.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple list operation with read-only annotations and no output schema, the description provides sufficient context: what it lists and the optional filter. It could mention return fields but not critical.

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

  Parameters4/5

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

  The only parameter 'schema' is explained in the description as an optional filter, which covers its purpose despite lack of schema description. This adds meaning beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states it lists indexes and their tables, with optional schema filtering. It is distinct from sibling list tools like list_tables and list_views, but doesn't explicitly name alternatives, so 4.

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

  Usage Guidelines3/5

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

  The description implies usage for listing indexes, but doesn't explicitly state when to prefer this over other list tools. No alternatives or exclusions mentioned, so only implied usage.

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

• insert_rowsA
  4/5.0
  Behavior4/5

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

  Annotations indicate `readOnlyHint: false` and `destructiveHint: false`, meaning the tool mutates but is not destructive. The description clearly states 'insert' which implies mutation, aligning with annotations. It also explains that rows are a parameterized object array and schema defaults to public, adding context 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.

  Conciseness4/5

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

  The description is one sentence, but it's dense and front-loaded with the action and key details. It's slightly unclear due to the '参数化批量插入' phrasing, which could be more explicit. However, it is concise and contains necessary info for mutation.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given there's no output schema, the description need not cover return values. It covers the main inputs and behavior. However, it lacks detail on error handling or constraints (e.g., row structure consistency noted in schema but not described). It's mostly complete for a mutation tool with helpful schema and annotations.

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

  Parameters5/5

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

  The schema covers 100% of parameters with descriptions. The description adds value by defining rows as an object array with keys as column names, and clarifies the default schema behavior. The schema alone lacks the semantic of mapping row objects to table columns, which the description provides.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description specifies a clear verb ('insert') and resource ('rows'), and mentions the key parameter `rows` with column semantics. It distinguishes from siblings like `update_rows` and `delete_rows` by the action verb, though it doesn't explicitly contrast with them.

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

  Usage Guidelines3/5

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

  The description implies usage when inserting rows, but doesn't explicitly state when to use it vs alternatives like `update_rows` or `execute`. No when-not-to-use conditions or alternatives are mentioned, which is a gap.

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

• update_rowsA
  4/5.0
  Behavior3/5

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

  Annotations indicate it is not read-only and not destructive. The description adds the behavioral safety constraint that WHERE is mandatory to prevent accidental full-table updates, which is valuable beyond annotations. However, it does not disclose return behavior or transaction semantics, so it adds some but not extensive context.

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

  Conciseness5/5

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

  The description is a single, tightly crafted sentence that conveys the operation type, required clauses, safety note, and optional schema. It is front-loaded, with no redundant words, making it highly concise and well-structured.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with 4 parameters and no output schema, the description covers the core semantics: table, set, where, schema, and the safety rationale. It lacks details on return values or error conditions, but it is sufficient for an agent to select and invoke the tool correctly in most scenarios.

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

  Parameters4/5

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

  With 75% schema coverage, the description enriches parameter meaning by explaining SET and WHERE and emphasizing that WHERE is required for safety—this is not present in the schema. It also clarifies the default schema behavior, adding useful semantics beyond the raw property definitions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states it performs a parameterized UPDATE on a specified table, with SET and WHERE clauses. It distinguishes from siblings by explicitly naming it as an update operation and highlights the mandatory WHERE to prevent full-table errors, making its purpose specific and actionable.

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

  Usage Guidelines3/5

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

  It provides a safety guideline (WHERE required to avoid full-table update) but does not explicitly contrast with alternatives like insert_rows, delete_rows, or execute. The context implies usage for modifying existing rows, but there is no explicit 'when not to use' or alternative selection guidance.

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

• list_lock_conflictsA
  4.2/5.0
  Behavior4/5

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

  Annotations already mark the operation as read-only, and the description adds the observable result: blocked sessions and blocking sources. It also limits the scope to 'current' lock conflicts, but does not cover possible permission requirements or output format nuances.

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

  Conciseness5/5

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

  The description is a single concise, front-loaded sentence that communicates purpose and output in one line. Every word earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple zero-parameter read-only list tool, the description supplies the essential requested content (blocked sessions and blocking sources). It could mention typical use context or caveats, but it is largely complete.

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

  Parameters4/5

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

  The tool has zero parameters and the schema is empty, so there is no parameter semantics burden on the description. Per rubric, baseline 4 applies.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('查看'/'list') and identifies the exact resource (current lock conflicts) with the returned content (blocked sessions and blocking sources). This clearly distinguishes it from sibling tools such as list_sessions and database_stats.

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

  Usage Guidelines3/5

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

  The description implies use when checking current lock contention, but it does not explicitly state when to choose this over alternatives or how it relates to list_sessions/explain_query. There are no exclusions or prerequisites, so usage guidance is only implied.

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

• list_databasesA
  4.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the description doesn't need to restate this. It adds that the tool returns sizes, which is useful context beyond the structured metadata. No hidden behaviors or side effects are disclosed, but for a simple list operation this is adequate.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that precisely conveys the tool's purpose with no redundant words. Every word earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  This is a simple parameterless read-only tool with clear annotations. The description sufficiently explains what will be returned (databases and sizes) and no output schema is required. The operation is completely specified for the agent's needs.

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

  Parameters4/5

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

  The tool takes zero parameters, so the baseline is 4. The description adds no parameter details, but none are needed since the schema is empty and the operation is self-contained.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the action (list), the resource (all connectable databases in a GaussDB instance), and the additional detail (sizes). It distinguishes itself from sibling tools like list_tables and list_schemas by focusing specifically on databases.

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

  Usage Guidelines4/5

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

  The description implies usage for enumerating databases rather than tables, views, or schemas. It provides clear context but does not explicitly mention when not to use it or alternative tools, so it misses the highest bar.

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

• delete_rowsA
  4.4/5.0
  Behavior4/5

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

  Annotations already include destructiveHint=true, and the description reinforces the safety requirement of a non-empty WHERE clause to prevent full-table deletion. It adds the behavioral detail that conditions are AND-connected, which goes beyond the annotation metadata.

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

  Conciseness5/5

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

  The description is a single, dense sentence that front-loads the primary action and packs essential constraints without redundancy. Every word contributes to understanding the tool's usage.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a delete tool with no output schema, the description covers the core invocation: table, required where, and optional schema. It omits return-value and edge-case behavior, but this is acceptable given the destructive nature is already captured by annotations and the safety constraint is highlighted.

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

  Parameters4/5

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

  The input schema covers 'where' and 'schema' but not 'table'; the description clarifies that 'where' is a column-value mapping joined by AND and emphasizes it must be provided. This adds the safety rationale ('prevent full-table deletion') beyond what the schema field descriptions state.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states '参数化删除' (parameterized delete) and specifies the resource as a table with WHERE conditions. It unambiguously conveys the delete action and differentiates from sibling update/insert tools.

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

  Usage Guidelines4/5

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

  The description explicitly warns that WHERE is required ('必填防全表误删除') to prevent accidental full-table deletion, offering a concrete safety guideline. It also notes the optional schema with default behavior, though it does not explicitly mention alternative tools.

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

• list_schemasA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate read-only, and the description adds specific behaviors (exclusion of system schemas, whitelist support). It does not mention rate limits or auth, but given the readOnlyHint, the added context is valuable and non-contradictory.

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

  Conciseness5/5

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

  Description is a single, concise sentence with no redundancy. It conveys all necessary information efficiently.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple listing tool with no output schema or parameters, the description is complete. It mentions the two key behaviors (system schema exclusion and whitelist), which is sufficient context.

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

  Parameters4/5

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

  No parameters exist, so description does not need to explain any. Baseline for zero parameters is 4, and description is consistent with the empty schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Description clearly states the tool lists schemas in the current database, with specific behaviors of excluding system schemas and honoring whitelist configuration. It distinguishes from sibling tools like list_tables and list_databases.

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

  Usage Guidelines4/5

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

  The description implies when to use the tool (when needing schema information) and mentions the whitelist behavior, but does not explicitly contrast with alternatives. For a simple listing tool, this is sufficient.

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

• test_connectionA
  4.5/5.0
  Behavior4/5

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

  Annotations (readOnlyHint=true) already signal a safe read operation. The description adds value by specifying the exact return payload (version, current database, user, server time), providing 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.

  Conciseness5/5

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

  A single, focused sentence that fully delivers the purpose and return details without any wasted words. Structure is ideal for a simple utility tool.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a parameterless tool with no output schema, the description is complete: it states exactly what the tool does and what it returns. The read-only annotation provides safety reassurance, making this 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.

  Parameters4/5

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

  There are no parameters (0), so the baseline is 4. The description correctly doesn't attempt to explain any parameters, and the empty schema is fully covered by the lack of parameters.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool tests a GaussDB connection and lists the specific information it returns (database version, current database, current user, server time). This distinguishes it from sibling tools that perform other database operations.

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

  Usage Guidelines4/5

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

  The purpose is self-evident and implies usage for verifying connectivity before other operations. It doesn't explicitly mention when not to use it or alternatives, but the context is clear enough given the tool's simple, unique function.

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

• transaction_beginA
  4.5/5.0
  Behavior4/5

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

  With annotations present (readOnlyHint=false, destructiveHint=false), the description adds meaningful behavior: returns a transaction handle and automatically rolls back/reclaims after 5 minutes of idle time. This is useful context beyond the annotations, though it does not mention potential lock/resource implications.

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

  Conciseness5/5

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

  The description is compact and effectively front-loaded: first states the action and result, then explains usage with related tools, then notes the idle timeout. Every sentence adds operational value with no redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a zero-parameter tool with no output schema, the description covers the essential information: what the tool does, what it returns, how the handle is used by sibling tools, and the timeout behavior. It is fully adequate for an agent to invoke and use the tool correctly.

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

  Parameters4/5

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

  The tool has zero parameters, so the baseline of 4 applies. The description adds relevant output semantics by explaining that a tx_handle is returned, which is more useful than only relying on the empty schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool starts a GaussDB transaction and returns a transaction handle (tx_handle), distinguishing it from sibling tools like transaction_commit and transaction_rollback. The verb-resource pairing is specific and unambiguous.

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

  Usage Guidelines4/5

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

  It explicitly explains that subsequent query/execute/write tools can pass in the handle to run within the same transaction, giving clear context for when to use it. It does not explicitly state exclusions, but the intended workflow is evident from the description and sibling set.

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

• transaction_commitA
  4.5/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description need not repeat that. The description adds value by disclosing the dependency on a transaction handle, which is a key behavioral requirement beyond the annotation fields. It doesn't describe post-commit effects, but that is not essential given the tool's simplicity and the presence of sibling transaction tools.

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

  Conciseness5/5

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

  The description is extremely concise, with only two short clauses. Every word is purposeful: it states the action and the required prerequisite. There is no ambiguity or unnecessary elaboration, making it an excellent example of efficient documentation.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with a single parameter, no output schema, and existing annotations, the description fully covers the necessary context. It explains what the tool does, what input is needed, and where that input comes from. Nothing significant is missing for an AI agent to invoke it correctly.

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

  Parameters4/5

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

  The schema only defines 'tx_handle' as a string with zero description coverage. The description compensates by explaining that the handle is the one returned by transaction_begin, giving meaning to the parameter and where to obtain it. This adds clear semantic value beyond the raw schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function with a specific verb ('提交事务' = 'Commit the transaction') and resource ('transaction'). The phrase distinguishes it from sibling tools like transaction_rollback and transaction_begin, making the purpose unambiguous.

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

  Usage Guidelines4/5

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

  The description provides explicit usage guidance by specifying that a handle from transaction_begin is required ('需提供 transaction_begin 返回的句柄'). While it doesn't explicitly state when not to use it, the prerequisite and the context of transaction management imply appropriate usage. This is sufficient for a simple commit operation.

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

• explain_queryA
  4.6/5.0
  Behavior5/5

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

  The description explicitly discloses a critical behavior beyond annotations: when analyze=true, the tool actually executes the SQL, times it, automatically wraps in a transaction with rollback, and ensures write statements are not persisted. This enriches the readOnlyHint annotation and provides valuable safety context.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence in Chinese with a parenthetical detail. Every word earns its place, with no redundancy or filler.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description is sufficient for a low-complexity tool. It does not describe the output format, but for an explain plan tool, this is generally implied. No output schema exists, but the core purpose is clear. Minor gap around return values.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3. The description enriches the analyze parameter by explaining the transactional rollback and non-persistence behavior, adding meaning beyond the schema's brief description. The sql parameter is self-evident.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses specific verb '查看' (view) and resource 'SQL 执行计划' (SQL execution plan), clearly distinguishing it from execution tools like query and execute. It also mentions the analyze option, further clarifying scope.

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

  Usage Guidelines4/5

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

  The description provides clear context: it's for viewing execution plans, with analyze=true enabling real execution and timing. It does not explicitly name alternatives or exclusion criteria, but the sibling set makes it obvious when to use this tool over query or execute.

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

• queryA
  4.8/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, and the description adds crucial details: rejection of write statements, limit/offset truncation without SQL modification, and optional transaction handle. No contradictions.

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

  Conciseness5/5

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

  One well-structured sentence that front-loads the core purpose, then lists constraints and options. Every phrase adds value with no redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the output schema exists, the description covers the main aspects: allowed SQL prefixes, write rejection, truncation behavior, and transaction support. It is complete for a general query tool.

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

  Parameters5/5

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

  Schema covers all parameters at 100%, but description adds semantic context: limit/offset does not modify SQL, tx_handle integrates with transaction_begin, and clarifies the single-statement requirement.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Description clearly states it executes read-only SQL queries on GaussDB, specifies allowed keywords (SELECT/WITH/EXPLAIN/SHOW/VALUES), and returns result rows. It distinguishes from siblings like execute (write operations) and explain_query (specific to EXPLAIN).

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

  Usage Guidelines4/5

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

  Implies usage for read-only queries and bans write statements, but does not explicitly name alternatives like execute for write operations. The single-statement constraint and transaction handle context are clear.

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