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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses that content must be plain text, empty content causes an error, optional parameters fall back to defaults, and return/error formats are JSON or plain text via with_error_handling. This is solid coverage for a create-comment operation, though it does not discuss permissions beyond the user_key identity.

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 an opening summary, bulleted use cases, an Args section, Returns section, and a concrete example. Each section earns its place and the important behavioral caveats are 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 is complete for a tool with five parameters and an output schema. It covers parameter semantics, defaults, return shape (including comment_id on success), error handling, and provides a runnable example. There are no significant gaps that would prevent an agent from calling this tool 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 0%, so the description must fully compensate. It explains all five parameters: issue_id is required, content is required and must not be empty, project accepts a name or project_key and defaults to the environment variable, work_item_type defaults to the default type, and user_key identifies the acting Feishu user. This adds substantial 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 starts with a clear verb and resource: '为指定工作项添加一条评论（纯文本）' (add a plain-text comment to a specified work item). It distinguishes itself from sibling tools like list_task_comments, update_task_comment, and delete_task_comment by explicitly framing this as the creation action.

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 includes an '适用场景' section with concrete use cases: recording communication conclusions, meeting minutes, handling records, and leaving auditable text notes beyond field updates. It gives clear situational context, though it does not explicitly state when not to use this tool versus 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?

With no annotations provided, the description carries the full behavioral burden. It discloses the asynchronous nature via '后台任务 ID 列表' (background task ID list) and the identity-switching capability via user_key (X-USER-KEY). However, it does not state whether updates are partial/patch-style, how per-item failures are reported, or whether the operation is reversible.

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 docstring is front-loaded with the purpose statement, followed by a clean Args list and a Returns note. It is verbose, but every line earns its place given the 0% schema coverage — the parameter list is necessary documentation rather than padding.

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 12-parameter mutation tool with zero annotations, the description covers parameter semantics and return shape well. It falls short on resolving sibling choice (update_task is a near-duplicate for single items) and on clarifying partial-update semantics — gaps that matter because the schema marks zero parameters as required.

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 fully compensates: it documents all 12 parameters, including value formats (project by name or Key, priority examples like P0/P1/P2, assignee by name or email) and the dependency relationship between field_name and field_value. This adds substantial meaning that the bare schema entirely 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-resource statement — '批量更新工作项字段' (batch update work item fields) — and clarifies the scope as single or multiple work items. This functionally differentiates it from singular siblings like update_task, though it never names the sibling 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 explicit when-to-use or when-not-to-use guidance relative to sibling tools such as update_task or transition_task_status; usage context is only implied by the 'batch' designation. The only concrete usage guidance present is parameter-level — issue_id and issue_ids are flagged as mutually exclusive (二选一), which helps invocation but not tool selection.

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 burden and does add useful behavior: it specifies that success returns a JSON string with a defined data structure and that failures return plain-text errors handled by with_error_handling. However, it does not disclose side-effect behavior such as whether existing child bindings are replaced, whether the operation is idempotent, or what permissions are required.

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 purpose is front-loaded in one clear sentence, and the Args/Returns sections are organized and scannable. The internal reference to with_error_handling is minor noise, but overall every section 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?

The output schema already covers the success return shape, and the description usefully adds the failure mode and parameter semantics. For a mutating operation with no annotations, however, the absence of when-to-use guidance and side-effect disclosure leaves the agent under-informed about consequences and alternatives.

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 all six parameters, including defaults for project and user_key and a recommendation for relation_name. The only weak spot is work_item_type, which is described as a name but not given its purpose in the binding operation.

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 opening sentence states a specific action (bind multiple work items) on a specific resource (parent work item's child tasks) via relation rules, which is clear and distinct from sibling operations like unbind_child_tasks. It does not explicitly name the sibling alternatives, so it stops one step short of full differentiation.

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 parameter-level advice, notably that relation_name should be provided when multiple rules exist, but it never tells the agent when to choose this tool over unbind_child_tasks or list_child_tasks. There is no stated condition, prerequisite, or exclusion, so usage context is largely absent.

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 performs well: it discloses automatic field-value conversion ('系统会自动处理字段值的转换（如将 P0 转换为对应的选项 Key）'), fallback defaults, and exact return behavior ('创建成功，Issue ID: xxx' on success, error info on failure). It does not cover permission requirements or side effects such as notifications, but the core mutation behavior and automatic transformations 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 clear sections — purpose, key auto-conversion behavior, Args list, Returns, and two realistic Examples — and the purpose is front-loaded. It is longer than minimal, but the length is justified by the 0% schema coverage and 7-parameter surface; nearly 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 7-param creation tool with no annotations and empty schema descriptions, this is nearly complete: purpose, parameter semantics, default behaviors, auto-conversion, and return messages are all covered, and an output schema exists for return values. The one notable omission is user_key semantics, plus there is no guidance on failure scenarios beyond 'returns error info'.

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 is the sole semantic source, and it compensates strongly for 6 of 7 parameters: project accepts a name or 'project_xxx' key format, priority enumerates P0-P3 with default P2, assignee accepts name or email, description supports plain text, and work_item_type falls back to the first available type. The real gap is user_key, which appears in the schema but is never explained in either the schema or the description.

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: '在指定项目中创建新的工作项（任务/Issue）' (create new work items in a specified project) and explicitly identifies itself as '创建飞书项目工作项的主要工具' (the main tool for creating Feishu project work items). This role is unambiguous against the sibling set, which contains update/batch_update/get/transition tools but no other creation 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 gives clear usage context: it documents the default project resolution from environment variable FEISHU_PROJECT_KEY, the default work_item_type fallback to the first available type, the default priority P2, and includes two worked examples (minimal default-project call and fully-specified call). However, it never names alternatives or states when NOT to use it, stopping short of explicit exclusion 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 does well: it discloses the success return format (data with issue_id and comment_id), the failure return format (plain-text error via with_error_handling), and common failure causes including a permission prerequisite. It stops short of explicitly stating the deletion is permanent/irreversible, but the disclosure is solid.

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 into Args, Returns, and Examples sections, with the core action stated up front. It is moderately long, but the length is justified given 0% schema coverage, since parameter semantics and return formats must live in the description. No filler or tautology.

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 5-parameter delete operation with no annotations, the description is thorough: all parameters documented with defaults, success and failure return formats specified, common error causes listed, and a concrete example provided. Minor omissions — no explicit irreversibility warning and no cross-references to sibling comment tools — keep it from a 5.

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 fully compensate — and it does. Every one of the 5 parameters gets meaning beyond its schema title: issue_id and comment_id are identified as the required keys, project documents name-or-key flexibility and env-var defaulting (FEISHU_PROJECT_KEY), work_item_type documents default-type behavior, and user_key is mapped to the X-USER-KEY header.

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 ('删除指定评论' — delete specified comment), which is clear and accurate. It doesn't explicitly differentiate from sibling comment tools like update_task_comment or add_task_comment, though the delete verb itself separates it from them.

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

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

No guidance on when to use this tool versus alternatives is provided. The description explains failure conditions (comment_id not found, no permission) but never states 'use this to remove a comment, use update_task_comment to edit one.' Usage context is only implied by the tool name and the example invocation.

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 return format (JSON full work item details), that all available fields including custom fields are returned, that user-related fields are converted to person names for readability, and that failures return error info. This is meaningful behavioral context beyond the 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 Intro, Args, Returns, and Examples sections. It is slightly redundant in repeating 'complete details' and 'all fields', but every section earns its place and examples add practical 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?

Given that an output schema exists, the description does not need to enumerate the return structure. It covers all four parameters, their defaults, optionality, and real-world examples. The user_key behavior and default project resolution are also explained, making the tool complete 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 0%, so the description must fully document the parameters. It does: issue_id is required, project accepts a name or project_key with defaulting behavior, work_item_type defaults to the first type, and user_key acts as the Feishu user identifier. Examples further clarify usage.

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: '获取单个工作项的完整详情' (get complete details of a single work item). It clearly differentiates from sibling get_tasks by emphasizing a single item and all fields, so an agent can distinguish it 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?

The description gives clear context: '当你需要查看工作项的所有字段信息时使用此工具' (use when you need to view all fields of a work item). It does not explicitly name alternatives or exclusion cases, but the usage context is sufficiently clear.

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 behavioral burden. It discloses the return format ('JSON 格式的选项列表，格式为 {label: value}'), failure behavior ('失败时返回错误信息'), and default behavior for optional parameters (default project via FEISHU_PROJECT_KEY, default first work item type). This goes beyond minimal transparency, though it could explicitly state that the operation is read-only.

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 Args, Returns, and Examples sections, and the primary purpose is front-loaded. It is somewhat verbose due to multiple examples, but each part serves a purpose and the formatting aids quick scanning.

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 all four parameters, explains defaults and optionality, provides three examples, and states the return/error behavior. With an output schema present and no nested objects, the tool description is sufficient for an agent to invoke it correctly without additional context.

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

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

Schema description coverage is 0%, so the description must compensate, and it does thoroughly. The Args section explains each parameter's meaning, optionality, defaults, and examples (e.g., field_name as 'status'/'priority', project by name or key, work_item_type like '需求管理'). This adds substantial value beyond the bare 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: '获取字段的可用选项列表' (get the available option list for a field). It clearly identifies the resource (task field options) and provides usage examples for common fields like status and priority, making it easy to distinguish from sibling task-management 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 description explicitly tells when to use the tool: '当你不确定某个字段有哪些可选值时，使用此工具查询', and clarifies that it's useful for understanding status transitions and priority options. It does not mention when not to use it or list alternatives, but the context is clear enough for a lookup 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?

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses default project resolution via FEISHU_PROJECT_KEY, default work_item_type, behavior when a field does not exist, related_to matching semantics, pagination limits, and the user_key impersonation option.

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 long but well-structured with a summary line, numbered behavioral features, Args section, Returns section, and clear Examples. Every section adds value; the examples demonstrate realistic combinations and parameter formats without redundancy.

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

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

For an 11-parameter list-fetch tool with no annotations, the description is complete. It covers default values, filtering behavior, output shape, error behavior, and usage examples. An agent has enough context to select the tool and invoke it correctly without inspecting sibling schemas.

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 titles and defaults with no descriptions. The description compensates fully by explaining every parameter in detail, including types, defaults, accepted formats, and real examples. related_to and project receive especially rich clarification.

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: '获取项目中的工作项列表' (get work item list in a project). It clearly enumerates supported filtering modes and explicitly distinguishes this list-oriented tool from sibling tools like get_task_detail, create_task, and update_task.

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 clear usage context: default behavior with no filters, recommended name_keyword search, optional filtering by status/priority/owner, and pagination. It even notes that nonexistent fields are skipped. However, it does not explicitly state when to prefer a sibling tool such as get_task_detail for single-item retrieval.

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，描述承担了完整的行为披露义务。它明确说明了成功时返回 JSON 字符串、失败时返回纯文本错误信息，并列出常见错误原因和内部委托流程，agent 能准确预判调用结果。

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?

按场景、职责、注意、Args、Returns、Examples 分段组织，信息密度高且前置了核心用途。但成功/失败返回格式在注意和 Returns 两处重复说明，略有冗余。

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?

在无 annotations、参数描述覆盖率为 0% 的情况下，描述覆盖了所有必要调用信息：参数、返回值格式、错误模式、默认行为和示例。配合存在的输出 schema，agent 已具备正确调用该工具的完整上下文。

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%，描述完全弥补了参数语义空白。每个参数都给出了含义、可选性、默认值或作用，包括 project 的环境变量回退、mode 的透传语义和 user_key 的用户身份用途。

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?

描述以明确的动词+资源说明了工具用途：获取将工作项流转到目标状态前需要补全的必填字段。与兄弟工具 transition_task_status 等形成清晰区分，且通过场景示例让用途一目了然。

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?

描述清楚指出了使用时机（在执行状态流转前查询必填要求），并给出常见场景和工具职责边界。但没有显式命名兄弟工具或说明何时不应使用本工具，排除性指引略弱。

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 burden. It documents success vs failure response formats (JSON with success=true vs plain-text error), the env-var default for project, and page/relation-rule resolution behavior. It stops short of mentioning auth requirements, rate limits, or empty-result behavior, but those are not essential for a read-only list operation.

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 sectioned and front-loaded with the one-line purpose. Although long, the background, numbered behavior, Args, Returns, and Examples sections are each informative and avoid 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?

For a 7-parameter tool with no annotation support and zero schema descriptions, the description is complete: it explains parameter semantics, default selection, ambiguity errors, return payload shape, and gives two examples. There is no missing information an agent needs 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?

Schema description coverage is 0%, and the description fully compensates: every one of the 7 parameters is explained with type, default, and meaning, including parent_issue_id, relation_name, page_num/page_size, project, work_item_type, and user_key. Examples show realistic calls.

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 opening sentence states a specific action and resource: '列出指定父工作项下的子任务' and clarifies the underlying mechanism (空间关联关系规则). The behavior section names the exact API call, RelationAPI.work_item_list, which separates this from broader task tools like get_tasks and from bind_child_tasks/unbind_child_tasks.

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 concrete selection rules for relation_name: exact match if provided, auto-select when there is exactly one rule, and an explicit error when multiple rules exist. It does not explicitly list alternative tools or say when not to use this tool, but the context is clear.

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?

There are no annotations, so the description carries the burden of explaining behavior. It discloses that the tool is read-only by nature, describes the return format as a JSON mapping of project_name to project_key, and notes failure behavior. It does not mention permissions or pagination, but for a simple list operation this is adequate.

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

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

The description is well-structured with a clear purpose, Args, Returns, and an Example. Every section adds value, and the example usefully demonstrates that the tool can be called without arguments.

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 one optional parameter, the description is complete: it states what it returns, the return format, failure behavior, and when to call it. Nothing essential is missing for an agent 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?

The input schema only provides a name, type, and default for user_key, with no semantic explanation. The description adds meaningful detail by explaining that user_key is the Feishu X-USER-KEY and can be used to operate as a particular user, which fully compensates for the sparse schema.

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

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

The description clearly states the tool '列出所有可用的飞书项目空间' (lists all available Feishu project spaces), which is a specific verb and resource. It also explains that the returned list includes project names and project_keys, making it easy to differentiate from the task-focused sibling 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 description explicitly says to call this tool first when the project_key is unknown, which is clear and actionable. It does not explicitly describe when-not-to-use or mention alternatives, but there is no competing project-listing sibling, so the context is sufficiently clear.

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 behavioral disclosure burden. It discloses pagination behavior, optional project/type fallback defaults, environment variable usage, and the JSON return shape. It does not mention error cases or explicitly confirm read-only semantics, but '获取...列表' sufficiently implies a non-mutating list operation.

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 one-line purpose, an Args section, a Returns section, and a minimal example. Every section adds necessary value, especially given the lack of schema descriptions, and there is no wasteful 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?

For a 6-parameter tool with no annotations, the description covers parameter semantics, defaults, return format, and a usage example. It is sufficiently complete for an agent to call the tool correctly, though it could add error behavior or clarification of the optional user_key usage.

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 documenting every parameter: issue_id, page_num, page_size, project, work_item_type, and user_key. It adds meaningful semantics like defaults, the server-side page_size limit, the FEISHU_PROJECT_KEY fallback, and what 'project' can be.

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 begins with a clear verb and resource: '获取指定工作项下的评论列表' (retrieve the comment list under a specified work item). This differentiates it from sibling comment mutation tools like add_task_comment, update_task_comment, and delete_task_comment.

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 makes it clear this is for listing comments and provides an example call, but it does not explicitly state when to use this tool over alternatives or when not to use it. Sibling names imply the distinction, but no direct usage guidance is provided.

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 it meets it thoroughly. It states success returns a JSON string with success=true, failure returns plain text via with_error_handling, the automatic resolution of state_key/transition_id, the default project behavior, and common error causes such as unmatchable target_status.

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 long but tightly organized into summary, usage suggestions, notes, Args, Returns, and Examples so an agent can scan efficiently. Some repetition exists between the Notes section and Returns section regarding failure returning plain text, but every sentence otherwise contributes meaningful call-related detail.

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

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

For a 7-parameter tool with no annotations and 0% schema description coverage, the description is essentially complete: it documents all parameters, return format, failure modes, pre-call requirements, and provides two examples. An agent has enough information to invoke this tool correctly and interpret its result.

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, and it largely does. Every parameter is listed with a concise explanation: issue_id and target_status required, fields as list[dict] passthrough, project defaults to environment variable, mode reserved, user_key for Feishu identity. The included examples add useful concreteness for fields formatting, though mode and work_item_type remain somewhat underspecified.

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: '将指定工作项流转到目标状态' (transition the specified work item to a target state). It goes beyond a generic label by explaining that it resolves target_status into state_key/transition_id and invokes the backend workflow state_change endpoint, which clearly distinguishes it from content-update tools like update_task.

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 recommends calling get_task_transition_requirements before this tool, which is strong usage guidance for preparation. It also clarifies that fields is currently only a minimal list[dict] passthrough. It does not explicitly state when not to use this tool versus alternatives, but no sibling offers a workflow transition, so the main prerequisite guidance is sufficient.

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 burden, and it does well by disclosing that the implementation calls RelationAPI.delete and that the server semantics usually mean 'clear all bindings under this rule.' It also states that failures return plain-text errors via with_error_handling. However, it does not clarify behavior when relation_name is omitted or whether the operation is reversible, so it is not fully 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 an implementation note, an Args section, and a Returns section. The purpose is front-loaded, and every sentence provides useful information without 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 covers purpose, parameters, return format, and failure behavior, and an output schema exists, so return values do not need much explanation. The main gap is that relation_name is optional, yet the description repeatedly refers to '该规则' without stating what happens when relation_name is not provided or how the rule is otherwise determined. This is a meaningful ambiguity for a 5-parameter tool with no annotations.

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

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

Schema description coverage is 0%, and the description compensates by enumerating all five parameters with roles and required/optional status, such as parent_issue_id being required and user_key mapping to X-USER-KEY. It adds meaning beyond the schema's titles and defaults, but it does not explain how the optional parameters combine to identify the specific rule or what happens when relation_name is 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 states a specific verb and resource: '解绑指定父工作项的子任务关系' (unbind child-task relationships of a specified parent work item). It also clarifies the scope as '按关联关系规则整体解绑' (unbind as a whole per relation rule), which distinguishes it from per-child unbinding and from sibling tools like bind_child_tasks and list_child_tasks.

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?

Usage is implied through the tool name and purpose: use this to remove child-task relation bindings for a parent work item. However, the description does not explicitly state when to use it versus alternatives, when not to use it, or any prerequisites such as whether the relation must already exist.

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 burden of behavioral disclosure. It does add useful behavioral context: multiple fields can be updated at once, fields_json enables bulk custom-field updates, user_key allows acting as a specific user, and success returns '更新成功'. However, it does not mention permissions, reversibility, partial-failure behavior, or side effects for a mutating operation.

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 a short summary, an Args list, and a Returns line. Each parameter earns its place given the zero schema coverage, though the repeated '（可选）' markers add some redundancy with the schema's optionality.

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 all 12 parameters and the return value, which is essential because the schema provides no descriptions. It does not clarify interactions or conflicts between field_name/field_value vs fields_json, nor does it mention valid values or when to prefer transition_task_status, leaving minor gaps for a 12-parameter tool.

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

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

Schema description coverage is 0%, so the description must explain all parameters. It does: every parameter is listed with a plain-language meaning, and fields_json is accompanied by a concrete JSON example. This compensates fully for the lack of 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 clearly states the tool updates work item fields, with a specific verb and resource. It also highlights multi-field updates via fields_json, but it does not explicitly distinguish itself from the sibling tool batch_update_tasks or clarify that status transitions should go through transition_task_status.

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

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

No explicit guidance is given about when to use this tool versus alternatives such as transition_task_status or batch_update_tasks. The description lists parameters but does not state prerequisites, exclusions, or which scenarios favor a sibling 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?

With no annotations, the description carries the behavioral burden; it does so well by specifying the success return format, the failure format (plain text via with_error_handling), and common error causes including permission and missing-comment cases. It also clarifies that content is pure text and how optional defaults are resolved.

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 Args, Returns, and Examples sections. Every sentence adds useful information, and the primary purpose is stated first. The example is concrete and demonstrates realistic 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 six-parameter mutation tool, the description covers parameter semantics, return behavior, error cases, and an example. It is nearly complete; the only minor gap is explicit guidance on prerequisite or alternative tool selection, but that is not critical for invoking this tool 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?

The input schema has 0% description coverage, but the description fully compensates by documenting every parameter: issue_id, comment_id, content, project, work_item_type, and user_key. It explains defaults, environment variable fallback, and optionality, providing meaning well beyond the bare 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: '更新指定评论内容' (update specified comment content). It is clearly distinguished from sibling comment tools like add_task_comment and delete_task_comment by targeting an existing comment_id.

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 usage is implied through the description: agents should use this when they need to modify an existing comment's content. However, there is no explicit guidance about when not to use it or when to prefer siblings such as add_task_comment or delete_task_comment.

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