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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds valuable behavioral context: the optional DDL invocation and a DM-specific gotcha that index position columns are named COLUMN_POSITION while constraint position columns are named POSITION. This helps the agent correctly interpret results without needing to discover the quirk at runtime.

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

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

Three sentences with no fluff: the first lists the complete output scope, the second gives the usage timing, and the third surfaces a critical naming distinction. Each sentence earns its place and 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?

There is no output schema, so the description correctly takes on the burden of explaining return values, which it does thoroughly by enumerating all structural components. It also includes the optional DDL behavior and the crucial column-name discrepancy warning, making it complete for an agent to invoke and interpret results 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 100%, and the input schema fully describes all four parameters. The description adds only a small overlap by mentioning optional DDL, which duplicates include_ddl. Per the calibration baseline, 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: '返回一张表的完整结构' and enumerates exactly what is returned (columns, keys, constraints, indexes, comments, optional DDL). It also distinguishes itself by explicitly stating it should be used before writing SQL to avoid guessing column names/types, clearly separating it from sibling tools like dm_query and dm_table_sample.

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 phrase '写 SQL 之前调用它，避免猜列名和类型' provides clear, explicit context for when to use this tool. However, it does not name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already cover readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds substantial context on top: it discloses the implementation quirk that Dameng's bare EXPLAIN returns no result set so EXPLAIN FOR is used, enumerates the output columns (OPERATION, TAB_NAME, IDX_NAME, SCAN_TYPE, ROW_NUMS, COST), and warns that params are inlined as escaped literals because bind parameters are unsupported. These are exactly the non-obvious behaviors an agent needs.

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 compact set of four sentences with no filler. The main purpose is front-loaded, and each sentence earns its place: the function, the EXPLAIN FOR quirk, the output columns, the call context, and the constraints. The length is proportionate to the tool's complexity.

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

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

Even though there is no output schema, the description discloses the return columns so an agent knows what the result will look like. Combined with 100% parameter schema coverage and annotations covering the safety profile, nothing needed to invoke the tool correctly is missing. Minor omissions like error behavior for non-SELECT input are acceptable given the SELECT-only constraint is already stated.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters and the baseline is 3. The description reinforces the params-inlining behavior, but the schema's params description already states the same thing ('EXPLAIN 不支持绑定参数，这里的值会被安全地内联为字面量'), so the description adds little semantic 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 opens with a specific verb+resource: '返回一条 SELECT 语句在达梦 DM8 上的执行计划', which unambiguously states what the tool does. It also differentiates from siblings like dm_query by framing this as execution-plan analysis rather than query execution, and reinforces the purpose with the use case '排查慢查询、确认有没有走索引时调用'.

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

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

The description explicitly states when to call ('排查慢查询、确认有没有走索引时调用') and gives a clear exclusion ('只接受 SELECT'). It does not, however, name an alternative sibling tool (e.g., pointing to dm_query for actually executing the query), so the when-not guidance is situational but not tied to a named alternative.

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 and idempotent behavior. The description adds valuable implementation details beyond annotations: it queries ALL_USERS and falls back to SYSOBJECTS with TYPE$='SCH' if permissions are insufficient. This gives the agent useful expectations about behavior and failure modes.

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 deliver action, usage context, and fallback behavior without redundancy. The purpose is front-loaded, and every sentence contributes meaningful information.

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

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

For a simple zero-required-parameter list tool, the description covers purpose, use cases, data source, and permission fallback. An output schema exists, and annotations are rich, so nothing essential is missing for correct invocation.

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

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

The only parameter, response_format, is fully described in the schema with enum values and a clear description. Schema coverage is 100%, so the description does not need to compensate. It adds no additional parameter meaning, matching the baseline.

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

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

Description states a specific verb and resource: list all schemas/users accessible to the current connection user. It also names concrete invocation scenarios, distinguishing it from sibling table-oriented tools like dm_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?

Provides clear when-to-use guidance: when unsure which schema a table belongs to, or when confirming available business schemas. It does not explicitly name alternative sibling tools or state when not to use it, but the context is clear enough.

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 the tool read-only and idempotent. The description adds useful behavior beyond annotations: NUM_ROWS is from statistics and may be NULL, and identifiers are case-insensitive. No contradictions with 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?

Three compact sentences each earn their place: what the tool returns, when to use it and the count caveat, and the case-insensitivity note. Information is front-loaded and no filler is present.

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 list tool with no required params and no output schema, the description covers the return shape (row count, tablespace, comment), the main data-quality caveat, and the alternative for exact counts. Remaining defaults and format are already documented in the schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond schema by illustrating pattern matching ('ORDER matches data_order_main') and confirming case-insensitive identifiers, which helps the agent use owner/pattern correctly.

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

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

Description states a specific action (list tables in DM8 by schema/name keyword) and the exact payload (row-count statistics, tablespace, comments). It clearly positions the tool as an exploration helper, which differentiates it from sibling tools like dm_describe_table or dm_table_count.

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?

Gives explicit usage scenarios ('which tables are in this library', 'find order-related tables') and an explicit alternative: use dm_table_count when accurate row counts are required. This satisfies the when/when-not/alternatives criterion.

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, so the bar is lower. The description adds useful behavioral context beyond annotations: it reads session and instance metadata only, touches no business tables, and returns permission-flag status. 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?

Three short sentences with no filler. The first sentence states the core function and outputs, the second gives the exact trigger condition for use, and the third clarifies scope. Every sentence earns its place.

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 no-parameter diagnostic tool with annotations and an output schema, the description is complete: it explains what the tool does, what it returns, when to use it, and what it will not do. No critical information an agent needs to select and invoke it correctly is missing.

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

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

The tool has zero parameters and schema coverage is effectively complete, so there is no parameter detail the description needs to add. Baseline for zero-parameter tools is 4, and the description correctly focuses on output and behavior instead.

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 names a specific verb-resource pair: checking whether the DM8 database connection is normal, and lists concrete returned values (server version, instance name, current user, permission switches). It is clearly distinguished from the sibling tools, which are about schemas, tables, queries, and explains that this tool only reads metadata rather than business 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 gives explicit usage guidance: call this tool first when troubleshooting 'cannot connect' or 'no write permission' errors. It also implies a when-not by stating it does not query business tables, though it does not explicitly name alternative sibling tools for those 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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses non-obvious runtime behavior: rejection of DML/DDL/multi-statements, three-layer result truncation with follow-up suggestions, and automatic re-read of big BIGINT keys as strings. No contradiction with annotations; context is added.

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 dense, purposeful sentences: core function, safety boundary, pagination pattern, and edge-case behavior. Nothing is wasted and the most important scoping 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?

The description covers return shape, safety, pagination, truncation, and big-integer handling, which is substantial for a query tool with no output schema. It stops short of describing error surfaces (e.g., exact rejection message or JSON framing), but the essential invocation knowledge is present.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description adds practical guidance: pagination values must go in params, DM8 native binding is verified, and params must never be used to interpolate identifiers. This is meaningful extra semantic context 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 opens by stating '执行一条 SELECT 语句，返回列名与结果行', giving a concrete verb, resource, and output. It further narrows scope by enumerating rejected statement types, which clearly distinguishes dm_query from read-only sibling tools like dm_explain or dm_table_sample.

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

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

It explicitly says only SELECT statements are permitted and states how to paginate with LIMIT ? OFFSET ? and bound params. It does not explicitly name alternative sibling tools or say when to prefer them, but the inclusion/exclusion rules are unambiguous enough for an agent to decide when to call 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint). The description adds useful behavioral context beyond those: matching spans three attributes, results include owner table/type/comment, and Chinese comments are searchable. 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?

Two compact sentences in Chinese, front-loaded with the search scope and immediately followed by practical examples. Zero fluff; every word contributes to understanding the tool's purpose and usage.

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 search tool with full schema coverage and safety annotations, the description adequately covers behavior, return fields, and usage scenarios. Pagination and offset/limit are documented in parameters, and since there is no output schema, the returned fields are stated. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so parameters are fully documented in the schema. The description's mention of keyword matching across three attributes duplicates the schema's keyword parameter description, adding minimal new 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 states a specific verb (跨表搜索) and resource (tables and columns), and specifies the matching criteria (表名、列名、列注释) and return contents (所属表、列类型、注释). This fully distinguishes it from siblings like dm_list_tables (table listing) and dm_describe_table (single-table detail) without ambiguity.

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?

Concrete example queries ('哪个表里有手机号字段', '跟退款相关的列在哪') clearly signal the exploration/discovery use case, and the '跨表搜索' phrase implies cross-schema scoping. However, it does not explicitly name alternatives or exclusion criteria, so it lacks the top-tier explicit routing.

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

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

Beyond the readOnly/idempotent annotations, the description discloses that the default is exact COUNT(*), that exact=false reads an estimate that may be unavailable because most tables lack statistics, and that ALL_TABLES.NUM_ROWS is unreliable. This adds real behavioral context and does not contradict 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?

Three concise sentences: what it does, a critical caveat, and a usage tip. Every sentence carries necessary information and the main action 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 read-only row-count tool with a full schema and output schema, the description covers the essential caveats (NUM_ROWS unreliable, exact=false fallback) and points to the right sibling. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the practical consequence of exact=false in this database (statistics usually unavailable), which enriches the schema's parameter 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 opens with '返回一张表的行数' — a specific verb plus resource. It also distinguishes itself from dm_list_tables by warning that NUM_ROWS is usually NULL, so an agent can immediately tell this tool from its sibling.

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 instructs not to use dm_list_tables' NUM_ROWS as the real row count and to use this tool instead. It also gives usage guidance for large tables: set exact=false to use statistical estimates when available.

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

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

The annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds useful behavioral context: it avoids writing SELECT, handles identifier case/quoting concerns, and caps sampling at 5 rows by default to avoid filling the context.

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

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

Three sentences with no filler: purpose comes first, usage guidance follows, and the rationale for the default limit is included. Every sentence earns its place.

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 sampling tool with full parameter documentation and safety annotations, the description is nearly complete. It covers purpose, usage boundaries, and behavioral rationale. A small gap is that it does not describe the return format or acknowledge limit/offset semantics, though those are present in the schema.

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

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

Schema description coverage is 100%, so the input schema already fully documents limit, offset, owner, table, and response_format. The description reinforces the default 5-row behavior and the table-oriented nature of the tool, but adds little parameter meaning beyond the schema.

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

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

The description states a specific action: sampling rows from a specified table to inspect its data. It clearly differentiates this from dm_query by noting that filtering or aggregation belongs to that sibling tool.

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

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

The description explicitly says when to use this tool: when you want to quickly understand what data in a table looks like. It also gives an explicit exclusion: for conditional filtering or aggregation, use dm_query.

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