feishu_task_comment

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 mentions actions (create, list, get) but lacks details on permissions required, rate limits, error handling, or what the tool returns (e.g., format of comments). For a tool with multiple actions and no annotations, this is a significant gap in transparency.

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 front-loaded with the tool's purpose and usage context in two sentences. However, the inclusion of 'Actions: create, list, get' is somewhat redundant since the schema already defines the 'action' parameter with these enums, slightly reducing efficiency.

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 complexity (9 parameters, no annotations, no output schema), the description is incomplete. It lacks details on behavioral traits (e.g., side effects, authentication), doesn't explain the return values or error cases, and doesn't fully guide parameter usage across different actions. For a multi-action tool with no structured output, this is inadequate.

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 high (89%), so the baseline is 3. The description doesn't add meaningful parameter semantics beyond what the schema provides (e.g., it doesn't explain how parameters like 'action' map to different behaviors or dependencies between parameters). It lists actions but doesn't detail which parameters are required for each action.

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's purpose: '飞书任务评论管理工具' (Feishu task comment management tool) with specific actions (create, list, get). It distinguishes itself from sibling tools like feishu_task_task or feishu_task_subtask by focusing on comments. However, it doesn't explicitly differentiate from feishu_doc_comments, which might handle comments on documents rather than 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?

The description provides clear context for when to use the tool: '当用户要求添加/查询任务评论、回复评论时使用' (when users request to add/query task comments, reply to comments). It specifies the actions (create, list, get) but doesn't explicitly state when to choose this tool over alternatives like feishu_doc_comments or mention prerequisites (e.g., authentication).

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