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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It reveals that the tool does not use next_id/previous_id anchors and forces the new block to be the last child, which is important behavioral context beyond the basic insert action. It does not cover error cases or side effects of invalid input, but the core behavior is well-documented.

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 well-structured with sections for scenarios, usage, notes, differences, and an example. Each sentence adds value and the content is front-loaded with the core purpose. While a bit lengthy, the structure makes it easy to scan, 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 simple append operation, the description covers the purpose, parameters, usage scenario, behavioral nuance, and distinction from a sibling tool. An output schema exists, so return values do not need to be documented. The example clarifies the expected result, making the tool fully usable without consulting additional resources.

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 for documenting parameters. It does so by explaining parent_id as the target parent block ID, data as the content to insert, and data_type as supporting markdown or dom. However, it does not elaborate on the exact allowed values or the optional nature of data_type beyond what the schema implies.

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

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

The description clearly states the tool inserts a trailing child block under a parent, using the phrase '插入后置子块' and demonstrating with an example. It explicitly distinguishes from insert_block, making its specific resource and behavior clear.

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

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

The description provides explicit when-to-use guidance: appending to a parent block for stable hierarchy, and when not to use it, directing users to insert_block for inserting in the middle. The section '与 insert_block 的区别' explicitly defines the alternative and the conditions that select 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?

With no annotations provided, the description carries the full burden and discloses two important behaviors: paths must start with '/', and re-creating the same path will not overwrite an existing document. This is meaningful behavioral context beyond the obvious 'create' mutation.

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

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

The description is compact, well-structured into scenarios, usage, and notes. Every line adds useful information, and the most important constraint (path must start with '/') is clearly surfaced in the notes.

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 three-parameter create tool, the description covers purpose, parameters, and key edge behavior. Since an output schema exists, return-value details are not required. It could be slightly more explicit about error behavior or what happens when creation fails, but nothing essential 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 description coverage is 0%, so the description must compensate. It explains all three parameters: notebook_id as target notebook ID, path as a human-readable path starting with '/', and markdown as the document body. This fully covers the parameter semantics.

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

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

The description states a specific action (create) on a specific resource (document) via Markdown, and lists concrete use cases. It is clearly distinguishable from sibling tools such as update_block or insert_block because it targets whole documents at a given path.

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

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

It provides clear applicable scenarios: creating structured documents at fixed paths and quickly writing complete Markdown documents. It does not explicitly name alternatives or state when not to use this tool, so it stops short of full when/when-not guidance.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose that the delete operation is destructive and that the return value contains an operation record for audit purposes. It omits details like permission requirements or cascade effects, but the essential destructive behavior is clearly communicated.

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

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

The description is concise, front-loads the main action, and uses clear bullets for scenarios and cautions. Each section earns its place: purpose, applicable scenario, and safety/audit notes. There is no filler or repetition.

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

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

For a simple one-parameter destructive tool, the description covers the core decision of when to use it, warns about destructiveness, recommends pre-delete verification, and mentions the auditability of results. Since an output schema is present, not detailing the return structure is acceptable. Missing permission details or explicit alternatives would strengthen it further.

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 should compensate for the parameter. It only mentions block_id indirectly by recommending verification before deletion, which adds minimal context. The parameter is self-named and obvious from the delete context, but the description does not add format, constraints, or source guidance beyond the schema's string type.

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 '删除指定块' (delete the specified block), giving a specific verb and resource. It also provides the intended scenario—cleaning up incorrectly inserted or unneeded blocks—which clearly distinguishes it from sibling tools like update_block, insert_block, or move_block.

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 the tool: for cleaning up incorrectly inserted or unneeded blocks. It also advises confirming block_id with a query tool before deleting, which gives practical usage guidance. It does not name specific alternative tools or state when not to use it, so it is not 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?

With no annotations provided, the description carries the full disclosure burden and does well: it declares read-only behavior, restricts to SELECT, warns that returned string fields are masked, and explicitly says it cannot be used for raw audit of sensitive values. It also documents ValueError for non-SELECT queries.

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 well-structured with clear sections: core behavior, applicable scenarios, usage tips, cautions, and Args/Returns/Raises. Every section adds useful operational information and there is no redundant wording.

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 one-parameter SQL execution tool, the description covers what it does, when to use it, the exact parameter semantic, return type, error behavior, and a critical data-masking caveat. The presence of an output schema further reduces the need to detail the return format, yet the description still provides Returns and Raises.

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

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

The schema only defines 'query' as a string with 0% description coverage. The description compensates by defining the parameter as 'query (str): SQL SELECT 查询语句', clarifying it must be a SQL SELECT statement, and it further recommends explicit LIMIT usage. This adds essential meaning beyond the raw type.

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 precise statement: '直接对数据库执行只读的 SELECT 查询' (execute read-only SELECT queries directly against the database). It further narrows scope with '仅支持 SELECT 语句' and positions the tool relative to built-in query tools, making its purpose distinct from siblings like search_blocks or find_documents.

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 '适用场景' section explicitly states when to use the tool: cross-field/cross-table advanced filtering and complex retrieval not covered by built-in query tools. The caution also gives a when-not case: '如需精确审计原始敏感字段值，不适合使用该工具'. This is clear usage guidance with exclusions.

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

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

No annotations are provided, so the description carries the full burden. It transparently discloses key behavioral traits: title filtering is done via blocks.name, not hpath; omitting notebook_id searches all open notebooks; and the return format is a list of dicts with 'name', 'id', and 'hpath'. This goes beyond a simple action statement and equips the agent with non-obvious behavior details.

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

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

The description is well-organized with clear sections (适用场景, 使用方法, 注意事项, Args, Returns) and every sentence adds value. It avoids redundancy and front-loads the most important usage guidance. The length is appropriate for 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?

Given the tool's complexity, the description is complete: it covers all parameters, states the return structure, highlights the critical difference between name and hpath filtering, and names the alternative tool for advanced queries. The output schema is not shown but the Returns section sufficiently describes the result format.

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 fully compensates by explaining every parameter in plain language: notebook_id scope, title LIKE fuzzy matching, exact date format YYYYMMDDHHMMSS for created_after/updated_after, and the default limit of 10. This is significantly more informative than the bare schema properties.

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

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

The description clearly states a specific action (find documents) with a specific resource (documents in notebooks) and defines the scope via filtering options such as notebook_id, title, and timestamps. It also explicitly scopes to type='d', which distinguishes it from generic block search tools like search_blocks and from related tools like find_notebooks.

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 tells the agent when to use this tool: for filtering documents by notebook, title, or date fields. It also provides a clear alternative, stating that complex conditions like hpath prefix filtering should use execute_sql. The note about filtering by blocks.name rather than hpath further guides correct usage and avoids common mistakes.

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 behavioral disclosure burden. It reveals case-insensitive contains matching, default limit 10, raw notebook fields (id/name/icon/closed), and the need for caller-side exact-match filtering. The minor inconsistency between 'raw info' and the simplified Returns field list prevents a higher score.

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 definition is well organized into 适用场景/使用方法/注意事项/Args/Returns and front-loads its purpose. There is some redundancy between the usage bullets and the Args block, but the overall structure is compact and scannable.

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 tool with two optional parameters, it covers use cases, filtering behavior, return shape, and the exact-match caveat. An agent can correctly invoke it and interpret results; the only real gap is the ambiguity about whether returned fields are only name+id or the full raw set.

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%, but the description fully compensates: name is documented as optional fuzzy/case-insensitive matching and 'omit to list all', while limit is documented as a max count with default 10. This adds exactly the meaning the input schema lacks.

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 (list) and resource (notebooks). It clearly distinguishes the tool from siblings like find_documents by targeting notebook objects and mentions returning IDs for use by other tools.

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

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

The '适用场景' section states concrete cases: obtaining all notebook IDs for later write/query tools and light name filtering. It does not explicitly name sibling alternatives or say when not to use it, so it falls just short of full guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It explains that the function returns current block field snapshots rather than historical snapshots, warns that deleted is currently always emptyhol and requires historical snapshot comparison, and flags that include_markdown=true significantly increases response size.

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 front-loaded with the core function, then organized into compact sections for applicable scenarios, sibling distinction, caveats, and parameter details. Each section adds distinct value, and the only repeated idea — no before/after — is used to reinforce the central differentiation from get_block_diffs.

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 four parameters, no annotations, and an output schema, this description covers everything an agent needs to select and call the tool correctly. It addresses invocation-time concerns such as time format, optional parameters, default limits, return contents, and the deleted-block limitation, leaving no critical call-blocking gap.

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%, but the description fully compensates by documenting all four parameters. It provides the exact datetime format for start_time and end_time, marks end_time as optional, states the default and meaning of limit, and explains include_markdown with a payload-size caveat.

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 pair — querying content blocks added or modified within a time range. It explicitly differentiates itself from get_block_diffs by stating it does not perform snapshot comparison or return before/after values, so an agent can immediately understand what this tool does and how it differs 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?

A dedicated '适用场景' section says to use this tool when only a change list/index is needed and per-block before/after diffs are not. It also names get_block_diffs as the alternative and clearly states the functional distinction, making both when-to-use and when-not-to-use explicit rather than left to inference.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds meaningful details beyond the action: returned kramdown will have sensitive information masked, and block IDs/timestamps in SiYuan attribute markers will be preserved. It does not cover error handling or permissions, but for a read operation these disclosures are substantive.

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 well-structured with clear sections: purpose, applicable scenarios, notes, args, and returns. The main purpose is front-loaded, and each section earns its place, though the Returns section is somewhat redundant given the output schema exists.

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 single-parameter read tool, the description covers the key context an agent needs: what is fetched, the relevant use case, and important output characteristics like sensitive-data masking and preservation of locating markers. It does not discuss failure modes, but the tool is simple enough that this is a minor gap.

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 for the undocumented block_id parameter. The 'Args: block_id (str): 块的 ID' line essentially restates the parameter name and adds little semantic value beyond what 'Block Id' in the schema already suggests. It does not explain where to find the ID, expected format, or edge cases.

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 starts with a specific verb and resource: '获取指定块的完整 Markdown 内容' (get the full Markdown content of a specified block). This clearly states what the tool does and implies a singular-block scope, which helps differentiate it from the plural sibling get_blocks_content, though it does not explicitly name or contrast that 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?

The '适用场景' section explicitly states when to use the tool: reading a single block's kramdown source for review or subsequent processing. This provides clear context, but there are no explicit when-not-to-use instructions or named alternatives.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the dependency on history_root readability, the failure condition when history is inaccessible, that before/after text is sanitized, and that max_text_length truncates long text. This is strong behavioral disclosure beyond the bare tool name.

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 well-structured with clear sections: purpose, applicable scenarios, differences from the sibling, caveats, and arguments. It front-loads the main purpose and every sentence adds value, making it efficient without being bloated.

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

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

Given the tool's moderate complexity, zero annotation coverage, and no schema-level parameter descriptions, the description adequately covers selection criteria, invocation parameters, key caveats, and return intent. The output schema is present, so detailed return-value documentation is not required here.

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%, but the description compensates fully by documenting every parameter: start_time and end_time formats, default values for limit/history_root/max_text_length, and the truncation semantics of max_text_length. It adds meaningful meaning beyond the raw JSON 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 verb and resource: query modified content blocks in a time range and return before/after comparisons. The applicable scenarios (auditing specific block changes and needing change types/diff statistics) further clarify its purpose, and it explicitly contrasts itself with the sibling get_block_changes.

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

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

The description provides explicit applicable scenarios and directly differentiates this tool from get_block_changes, noting that it reads historical snapshots, returns before/after text with diff statistics, and is heavier while depending on /history. This gives an agent clear criteria for choosing this tool over alternatives.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses partial-failure semantics ('单个块失败不会中断整体，失败项会返回 error 字段') and sensitive-information masking in kramdown output, both of which are valuable beyond the schema. It does not mention auth, rate limits, or ordering, but the key quirks are covered.

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 organized into compact labeled sections (适用场景, 注意事项, Args, Returns) and every section contributes operational information. The Args section is somewhat redundant with the schema, but overall the structure is clear and front-loaded with the core purpose.

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

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

With a single self-evident parameter and an output schema present, the description adds the important contextual details an agent needs: batch usage rationale, per-block partial failure, the error field, and sensitive-information masking. It could additionally mention batch-size limits or how error values are represented, but it is sufficiently complete for correct selection and 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 schema has 0% description coverage for the only parameter, and the Args section mostly restates the schema: 'block_ids (List[str]): 块 ID 列表'. This adds no meaningful constraints or semantics such as maximum batch size, duplicate handling, ordering, or required behavior, so the description does not compensate for the schema gap.

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

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

The description opens with '批量获取多个块的完整内容', which clearly states a specific verb, resource, and batch scope. It also distinguishes itself from the sibling get_block_content by emphasizing multiple blocks and reduced call overhead, so an agent can tell them apart.

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 it applies to '一次性拉取多个块内容，减少多次调用开销', providing a clear when-to-use context. However, it does not explicitly tell the agent to use get_block_content for single-block fetches or give exclusion criteria, so it stops short of full when-not guidance.

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

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It does this well by revealing that text content will be masked for sensitive information and that binary files that cannot be decoded as UTF-8 return '[Binary Data]'. It stops short of documenting error behavior or access permissions, but for a simple read tool this is substantive.

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 well structured: a one-line primary purpose, a short usage sentence, bulleted behavioral notes, and an Args section. Every sentence adds value, 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?

For a one-parameter read tool, the description covers the essential aspects: purpose, path semantics, masking behavior, and binary fallback. An output schema is indicated as present, so return-value details need not be expanded. It is slightly incomplete in not guiding the agent toward the binary-capable sibling when raw bytes are needed, but overall it is sufficient.

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

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

The input schema provides only a bare 'path' string with no description, so schema coverage is 0%. The description compensates by explaining that path is a file path and gives a concrete example format ('/data/history/2023/01/...'). With only one parameter, this is sufficient semantic coverage.

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

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

The description opens with a clear verb+resource statement: '读取指定文件的内容（只读）' (read the content of the specified file, read-only), which immediately tells the agent what the tool does. It also hints at a text-reading focus by describing binary fallback behavior, but it does not explicitly distinguish itself from siblings like get_file_base64 or get_history_file.

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 a general usage context: '用于读取历史快照或其他数据文件' (for reading historical snapshots or other data files). This gives some situational guidance, but it does not specify when to prefer this tool over alternatives such as get_file_base64 or get_history_file, nor does it give any exclusions.

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

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

No annotations are provided, so the description carries full responsibility. It discloses read-only behavior, the UTF-8 decode requirement, the exception thrown for binary files, and that the content is masked before Base64 encoding. The masking step is mentioned but not fully explained.

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 well-structured with a clear purpose, usage note, args, and return value, and the main purpose is front-loaded. The only minor weakness is the undefined term '打码', but there is no wasted content.

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

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

For a one-parameter tool with an output schema, this description covers purpose, parameter format, return type, and a key failure mode. It is missing a detailed explanation of the masking behavior and permission expectations, but overall it is sufficiently complete.

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

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

Schema coverage is 0%, and the description adds real value by clarifying that path is a file path and giving a concrete example ('/history/.../blocks.msgpack'). This helps agents construct valid calls even though details like absolute vs. relative paths are absent.

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

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

The description clearly states the tool reads a file and returns its content Base64-encoded, and identifies a concrete use case (UTF-8 text files like JSON in history snapshots). It stops short of a 5 because it does not explicitly contrast with siblings like get_file or get_history_file.

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

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

It provides when-to-use context (UTF-8 text files needing Base64) and notes that binary files will fail. However, it never mentions alternative tools, so an agent must infer routing among the many file-related 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?

No annotations are provided, so the description carries the full burden and it does well by disclosing read-only semantics, required path prefixes, and sensitive-information masking. It references get_file for behavioral parity, which delegates some detail, but for a simple read operation this is sufficient.

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

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

The description is front-loaded with its purpose and organized into Notes, Args, and Returns sections, making it easy to scan. The prefix rule is repeated three times, which is slightly redundant, but the overall structure is efficient and clear.

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 one-parameter, read-only file tool with an output schema, this description is complete: it covers path constraints, read-only behavior, sensitive-info masking, and return type. An agent has everything needed to invoke it 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?

With schema description coverage at 0%, the description compensates by explaining the only parameter, path, as the historical snapshot file path and by repeating the required prefix constraint. It adds genuine meaning beyond the bare schema, though a concrete example would make it slightly stronger.

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 precise verb-object statement: '读取历史快照文件内容（只读）', meaning read historical snapshot file content in a read-only manner. It clearly identifies the resource and distinguishes itself from the general get_file by restricting paths to '/history' or '/data/history' and from listing-oriented siblings like list_history_entries.

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 gives an explicit usage condition: the path must start with '/history' or '/data/history', and it notes that behavior matches get_file. However, it does not explicitly say when not to use it or name alternatives such as list_history_entries for enumeration, leaving the guidance clear but not fully contrastive.

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 burden, and it delivers: it discloses the next_id > previous_id > parent_id precedence, warns that parent_id can be silently ignored when adjacent anchors are provided, and flags the 'looks like it is not under the heading' pitfall. It also advises against relying on parent_id alone.

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 fully sectioned (scenarios, usage, cautions, sibling comparison, examples) and front-loads the core constraint that at least one anchor is required. The length is justified because every section adds information needed to invoke the tool safely and correctly.

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 nontrivial insertion tool with no annotations, the description covers the required anchor constraint, precedence rules, failure-prone scenarios, alternatives, and concrete examples. An output schema exists, so not describing return values is acceptable, and nothing essential for calling the tool 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 description coverage is 0%, so the description must compensate; it does so for next_id, previous_id, and parent_id with clear 'insert before/after/child' semantics and examples. However, data_type is left undocumented (only its default 'markdown' appears in the schema), and data itself is only illustrated through examples rather than explicitly defined.

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

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

The description states a specific operation ('插入块' – insert a block) and immediately specifies the positional anchors (next_id/previous_id/parent_id). It also distinguishes itself from nearby siblings prepend_block/append_block, so an agent can separate it from them without opening any schemas.

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 gives explicit selection criteria: use insert_block for neighbor-relative or parent-based placement, and explicitly says to use append_block/prepend_block when the goal is to force a block under a heading. It also explains the API priority between conflicting anchors, leaving no ambiguity about when to choose 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?

No annotations are provided, so the description carries the full burden. It explicitly discloses read-only behavior ('不会修改任何文件' – will not modify any files) and a permission dependency ('返回结果依赖思源工作空间内的实际路径权限'). This goes beyond a minimal listing description and helps the agent set expectations.

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 front-loaded with the core purpose, followed by concise bullet notes and clearly separated Args/Returns sections. Every sentence adds functional information, and there is no redundant or filler content.

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

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

For a simple one-parameter read-only tool, it covers purpose, usage context, parameter semantics, return shape, and permission behavior. The output schema covers detailed return structure, so the description doesn't need to. Minor gaps such as error handling or recursion behavior prevent a perfect score.

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

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

The input schema provides no parameter description (0% coverage), so the description must compensate. It defines 'path' with examples ('/data' or '/data/history'), giving concrete format guidance. It does not cover absolute vs. relative paths or validation rules, but the examples are sufficient for normal use.

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: '列出指定路径下的文件和文件夹（只读）' (list files and folders under the specified path, read-only). This clearly differentiates it from sibling tools like get_file or get_history_file, which retrieve file content or history rather than directory listings.

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

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

It provides concrete usage context: '常用于探索 /data 目录结构，例如查看 /data/history 下的快照' (commonly used to explore the /data directory structure, e.g., view snapshots under /data/history). It does not explicitly contrast with alternatives or state when not to use the tool, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavior disclosure. It states the operation is 'list' and 'enumerate', implying a read-only action, and it clarifies that the tool does not return snapshot content. However, it does not explicitly state that it is read-only, mention any permissions needed, or describe error conditions (e.g., invalid path). While the read-only nature is strongly implied, the absence of explicit behavioral guarantees leaves a gap.

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

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

The description is concise and well-structured: a single opening sentence states the purpose, followed by bullet-point notes that add constraints and clarifications. There is no fluff, and the most important information (purpose and usage constraint) 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 tool is simple with one optional parameter and an output schema (list). The description covers the purpose, path constraint, and indicates the return type (list of entries). It does not mention error handling, sorting, or recursion, but for a basic enumeration tool this is acceptable. Given the lack of annotations, it might be expected to state its read-only nature explicitly, but the description adequately conveys the core behavior.

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

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

The input schema only provides a default value for 'path' with no description. The tool description compensates by explaining that the path is the history directory path and adding the critical constraint that it must start with '/history' or '/data/history'. Since schema description coverage is 0%, this added meaning is essential and provided.

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

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

The description explicitly states what it does: '列出历史快照目录下的文件和文件夹' (list files and folders in the history snapshot directory). It further clarifies that it does not return snapshot content, distinguishing it from sibling tools like 'get_history_file' and 'get_block_changes'. This is a clear verb and resource with a scope boundary.

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 practical usage context: it is for enumerating the history directory, and it includes a path constraint ('must start with /history or /data/history'). It implicitly tells users not to use it for content retrieval by stating it does not return snapshot content. However, it does not explicitly name alternatives such as 'get_history_file' for content or 'get_block_changes' for diffs, so it stops short of full when-to-use guidance.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses section-range movement for headings, subtree group movement for non-headings, the API priority rule when both previous_id and parent_id are passed, the deprecation error on allow_heading_only_move=true, and the restriction that anchors cannot point inside the moving subtree. No annotation contradiction since no annotations exist.

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?

Well-organized with clear sections and the key constraint (previous_id/parent_id at least one) front-loaded. However, it is long and somewhat redundant: the group-move safety advice appears three times (notes, safety suggestions, and parameter guidance), and the worked examples are verbose relative to their illustrative value.

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

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

For a complex tool with 0% schema coverage and no annotations, the description is complete: purpose, scenarios, parameter behavior, edge cases (heading section range, subtree grouping), precedence rules, failure constraints, sibling distinction, and safety guidance are all present. Return values need no explanation because an output schema exists.

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

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

Schema description coverage is 0%, so the description must compensate. It provides plain-language semantics for previous_id (move after anchor), parent_id (move under parent), and allow_heading_only_move (deprecated, errors if true), plus worked examples showing block_id usage. The only gap is that block_id is not explicitly defined as 'the block to move' in prose, though the examples make it clear.

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 (move an existing block) and resource (block position/hierarchy), and explicitly differentiates from insert_block by contrasting 'insert new block' vs 'move existing block'. It also distinguishes two movement modes (order via previous_id, hierarchy via parent_id), which disambiguates it from sibling tools like prepend_block and append_block.

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?

Has an explicit '适用场景' section listing when to use it (adjust order, adjust parent-child, adjust section/hierarchy), parameter-level guidance for when to supply previous_id vs parent_id, and a dedicated 'difference from insert_block' section naming the alternative and its distinguishing condition. Safety advice even recommends preferring parent_id for stable parent attachment.

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

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

No annotations are provided, so the description carries the full burden. It discloses the key behavioral trait: this is a parent-first safe write that does not depend on next_id/previous_id, and it gives a concrete example of insertion order. It does not cover permissions or error behavior, but the critical positioning semantics are transparent.

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 well-structured with dedicated sections for use cases, usage, differences, and a worked example. Every section adds value, and the example makes the insertion position unambiguous without being verbose.

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 3-parameter tool with an output schema, the description covers purpose, parameter semantics, alternative routing, and behavioral consequences with a concrete example. Missing details like authentication are not necessary for correct invocation, and return values are handled by the output schema.

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

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

Schema description coverage is 0%, so the description must compensate for the schema's silence. It explains that parent_id is the target parent block ID, data is the content to insert, and data_type supports markdown or dom. This covers all parameters, though exact dom formatting and default behavior are not detailed.

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: inserting a child block at the front of a parent block. It also explicitly contrasts itself with insert_block, so an agent can distinguish the tools without reading schemas.

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

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

It provides explicit when-to-use guidance: use when a stable parent-child relationship is needed, and explicitly directs users to insert_block when positioning by adjacent blocks is required. The distinction between the two tools is clearly 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 provided, so the description carries the full burden of behavioral disclosure. It does state constraints (msg non-empty, timeout positive integer) and the return shape, but it does not disclose failure behavior, side effects, persistence, or any safety profile. For a tool that pushes messages to the frontend, this is a notable gap.

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

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

The description is compact and efficiently organized with purpose, use-case scenarios, notes, args, and returns. It front-loads the core purpose and every sentence contributes information without fluff or repetition.

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

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

For a simple 2-parameter utility, the description covers purpose, use cases, parameter semantics, validation constraints, and return type. The output schema is also provided. The main omissions are explicit failure semantics and a clearer contrast with push_message, but given the low complexity, the description is largely complete.

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

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

Schema description coverage is 0%, but the description fully compensates by defining each parameter in plain terms: msg as the error message content and timeout as the display duration in milliseconds with a default of 7000. It also adds validation constraints beyond the schema, making the parameters well-understood.

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–object pair ('推送前台错误消息') and adds error-specific context ('参数校验或接口调用失败'), which clearly distinguishes it from the general sibling push_message. It stops short of naming the alternative explicitly, so it is clear but not fully differentiated by sibling comparison.

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?

An '适用场景' section explicitly states when to use the tool: when parameter validation or API calls fail. This provides clear contextual guidance. However, it does not state when not to use it or mention the alternative push_message, so the guidance is not exhaustive.

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

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

No annotations are provided, so the description carries the full burden. It adds meaningful behavioral details: msg must be non-empty, timeout must be a positive integer millisecond value, and the return value is a dict containing a message id. However, it does not disclose side effects, persistence, or visibility scope of the pushed message.

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 well-structured with clear sections: scenario, notes, args, and returns. Every section is concise and adds value, with no filler, tautology, or redundant repetition.

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

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

For a simple two-parameter tool, the description covers purpose, usage context, constraints, parameter semantics, and return shape. The only notable gap is the lack of explicit guidance about using push_error_message for error-related messages, but otherwise the description is sufficiently complete.

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

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

Schema description coverage is 0%, and the description compensates by explaining msg as message content and timeout as display duration in milliseconds with a default of 7000. It also adds constraints not present in the schema: msg must be non-empty and timeout must be a positive integer. It does not explicitly note that msg is required, but the schema already marks it required.

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 ('前台消息'), and adds a concrete scenario ('在写入流程中向前台反馈进度或结果'). It is clear about what the tool does, though it does not explicitly differentiate it from the sibling push_error_message.

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 names the intended context: during write flows, to report progress or results to the frontend. This provides clear usage context, but it does not say when not to use it or mention the sibling push_error_message as the alternative for error feedback.

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 transparency burden. It discloses important traits: query uses SQL LIKE semantics, parent_id only matches direct children, and returned content is masked for sensitive information. This goes well beyond a simple 'search' statement.

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 well-structured with sections for scenarios, usage, notes, args, and returns. It is slightly redundant because the '使用方法' section partially repeats the Args section, but the organization and front-loaded purpose make it easy for an agent to scan.

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

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

The description covers the tool's purpose, parameter behavior, edge cases (non-recursive parent_id), and security-relevant masking behavior. It does not mention all possible sibling alternatives or boundary semantics like inclusive/exclusive time filters, but the essentials for invoking it correctly are 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 description coverage is 0%, so the description fully compensates. Every parameter is explained with meaning, optionality, formats, and defaults. It also adds semantics not obvious from the schema, such as the date format YYYYMMDDHHMMSS and the default limit of 20.

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

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

The description clearly states the tool searches content blocks in SiYuan Notes by keyword, type, and other conditions. It also labels itself as the core and most flexible query tool, which helps differentiate it from mutation and retrieval siblings like update_block or get_block_content.

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

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

The description provides explicit usage scenarios: global keyword search and narrowing by block type or time window. It gives practical method notes for query, parent_id, and block_type, though it does not explicitly compare against sibling alternatives or state when not to use this tool.

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，描述承担了行为披露责任。它说明了关键行为：整块替换、不是局部 patch，并警告修改前确认 block_id 避免误改。虽然没有提及权限或是否可恢复，但核心破坏性特征已透明化。

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

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

结构清晰：先说明目的，再分场景、用法、注意事项三个小节，每项内容都直接有用，没有冗词或重复。信息密度高且易扫读。

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

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

工具本身复杂度不高，且已有输出 schema，返回格式无需赘述。描述覆盖了用途、参数、替换语义和误操作风险；主要缺失是与 insert/append 等替代工具的明确边界说明，但调用所需核心信息基本齐全。

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 覆盖率为 0%，描述必须补偿参数语义。它逐项解释了 block_id、data_type、data 的含义，并补充了 data_type 仅支持 markdown 或 dom 这一关键限制，超出了 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?

描述明确说明“更新块内容”，并以“整块替换，不是局部 patch”进一步界定操作性质，能与 insert_block、append_block 等兄弟操作区分。但没有显式点名替代工具，因此未达到满分。

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?

给出明确适用场景：“已知 block_id 时，直接替换该块内容”，并提示这是整块替换而非局部 patch。不过没有说明何时不应使用，也没有提到可选用的兄弟工具，缺少排除性指引。

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