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

The verb '读取' indicates a read-only, non-mutating operation, which is useful since siblings include upsert_rows. However, with no annotations, the description carries the full burden and does not disclose return format, permissions, or potential errors, so transparency is only partial.

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

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

The description is a single short sentence with no filler, and the core action is front-loaded. It is concise, though slightly under-specified, which is more a completeness issue than a structure problem.

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

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

With no annotations, no output schema, and 0% parameter description coverage, the definition leaves the agent without enough context about how to supply library/table values or what the returned schema will look like. Sibling names hint at a workflow, but the description itself does not establish it.

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

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

Schema description coverage is 0%: the input schema only gives parameter names and types. The description mentions '表字段' (table fields) but leaves 'library' unexplained, and provides no value formats or how to obtain valid inputs, so it does not compensate for the missing schema 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 '读取表字段 schema' clearly states a read operation on a table's field schema, with a specific resource and scope. It is distinguishable from siblings like query (data retrieval) and list_tables (table enumeration), though it does not name them explicitly.

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?

There is no guidance on when to use this tool instead of list_tables or query, and no exclusions or prerequisite steps are mentioned. The intended workflow (first list libraries/tables, then fetch schema) is only inferable from sibling names, not stated.

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

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

No annotations are present, so the description carries the full burden. It clearly indicates a read-only listing operation scoped to the root directory, but it does not disclose details such as pagination, sorting, whether nested libraries are included, or what the response shape is. For a no-parameter list operation, this is adequate but minimal.

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

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

The description is a single concise sentence that immediately communicates the action and scope. There is no filler or redundant 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?

Given the zero-parameter schema and no output schema, the description is nearly sufficient: it names the action, resource, and scope. Minor gaps include no statement about non-recursive behavior or return format, but the tool is simple enough that these are not critical.

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

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

The tool has zero parameters, so there is no schema burden to compensate for. The description appropriately focuses on output scope rather than parameter details, matching the baseline for parameterless tools.

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

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

The description uses a specific verb ('列出') and a specific resource ('根目录内的 OpenSheet 库'), clearly distinguishing this from siblings like list_tables, which lists tables rather than libraries. The scope 'root directory' adds useful precision.

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 states what the tool does but gives no guidance on when to choose it over alternatives, nor any exclusions or prerequisites. An agent must infer from sibling names and the description that this is the tool for listing libraries, not tables or schemas.

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

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

With no annotations, the description bears the full burden. The verb '列出' implies a read-only listing operation, but the description does not disclose output format, pagination, error behavior, or whether any library validation occurs. It is minimally transparent but not richly so.

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

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

The description is a single short sentence with no redundant words. The operation and scope are front-loaded, making it easy to parse quickly.

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

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

For a tool with one required parameter and no output schema, the description gives only minimal context. It does not explain what a 'JSONL 表' is exactly, what the agent should do with the returned list, or how to obtain a valid library value. The ambiguity around 'JSONL' and library selection leaves meaningful gaps.

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

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

Schema description coverage is 0%, so the description must compensate. The phrase '库里的' clarifies that the 'library' parameter identifies which library's tables are listed. However, it does not explain valid library identifier formats, whether values come from list_libraries, or how missing/invalid libraries are handled.

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

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

The description clearly states the operation ('列出' / list) and the resource ('JSONL 表' / tables) scoped to a library. It is easily distinguished from siblings like list_libraries, though it does not explicitly name the sibling it differs from.

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

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

No guidance is given on when to use this tool versus siblings such as get_schema, query, or list_libraries. The description only states what it does, not when it should be chosen or what prerequisite steps (like selecting a library) are needed.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the critical read-only trait, which is essential for an agent to know this tool will not mutate data. It says nothing about return shape, SQL restrictions beyond read-only, error behavior, or permission requirements, so transparency is partial rather than complete.

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

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

The description is a single concise sentence with no filler. The key behavioral qualifier 'read-only' is front-loaded, and every word contributes meaning.

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

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

For a tool with three required parameters, zero schema descriptions, and no annotations, the description is too sparse. An agent still lacks clarity about the 'library' parameter, whether results are returned in a specific format, and what SQL constructs are allowed beyond the read-only restriction.

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

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

Schema description coverage is 0% and the description adds little to parameter meaning beyond what the parameter names already imply. 'sql' and 'table' are self-explanatory, but 'library' remains ambiguous and there is no guidance on how the three parameters relate or what format the SQL should follow.

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—querying tables via DuckDB SQL—and explicitly marks it as read-only, which distinguishes it from upsert_rows. It does not explicitly name sibling tools or contrast its scope with list/get_schema tools, so it is clear but not maximally differentiated.

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 read-only qualifier implies this tool is for SELECT-style data retrieval and not for modifications, giving some usage direction. However, it does not explicitly state when to choose this over list_libraries, list_tables, or get_schema, leaving the routing mostly to inference from the tool name and siblings.

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

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

With no annotations, the description carries full responsibility for behavior disclosure, and it delivers: it mentions Store concurrency protection, the exact receipt format (inserted/updated/unchanged counts and key lists), and the no-persistence behavior of dry_run=true. It does not cover error or validation behavior, but the most decision-relevant side effects are explicit.

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 cover the core operation, concurrency protection, return receipt, and dry-run behavior. The most essential verb and scope are front-loaded with no redundant filler.

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

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

The description compensates for the missing output schema by stating the receipt shape, and it covers the operation's key nuances. It lacks row-structure details and failure semantics, which would help for a 5-parameter mutation tool, but it is sufficiently complete for a competent agent to call the tool correctly in the common case.

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

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

Schema coverage is only 20%, with only dry_run documented. The description adds meaning by identifying key as the primary key, rows as the batch payload, and clarifying dry_run semantics. However, it does not explain how rows should encode the key or what values library/table expect, leaving part of parameter construction to inference.

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 (upsert) and a clear resource (rows keyed by primary key). This immediately distinguishes it from the read-only and metadata sibling tools like query and list_tables, so an agent can tell what it does without needing more context.

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 conveys that the tool is for batch insert-or-update operations by primary key and even highlights the dry_run inspection mode. However, it never explicitly contrasts it with alternatives such as query for reads or states when not to use it. The usage context is clear but the tool-selection guidance is only implied, not spelled out.

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