feishu_im_user_search_messages

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 does so comprehensively. It describes the search scope ('跨会话'), filtering capabilities, pagination behavior, return format details (including specific fields like message_id, msg_type, content, sender, create_time, chat metadata), and how results relate to other tools. It also specifies important constraints like '所有参数均可选，但至少应提供一个过滤条件' (all parameters optional but at least one filter required) and page_size limits.

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, usage, constraints, return values) and every sentence earns its place. It's appropriately sized for a complex 12-parameter search tool, providing necessary detail without redundancy. The information is front-loaded with the core purpose, followed by practical usage guidance, then technical constraints.

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 search tool with 12 parameters and no annotations or output schema, the description provides complete context. It covers the tool's purpose, detailed usage scenarios, parameter constraints, return format (including specific field names and chat metadata), pagination behavior, and integration with sibling tools. The description fully compensates for the lack of structured metadata.

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 100% description coverage, so the baseline is 3. The description adds significant value beyond the schema by explaining parameter relationships and constraints in the '【参数约束】' section, such as the requirement for at least one filter, mutual exclusivity between time filters, and page_size defaults/ranges. It also provides context about how parameters work together in the '用法' section. However, it doesn't fully explain complex parameter interactions beyond the basic constraints.

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 the tool's purpose as '跨会话搜索飞书消息' (search Feishu messages across sessions) with the user identity context. It clearly distinguishes this search functionality from sibling tools like feishu_im_user_get_messages (which retrieves messages from a specific chat) and feishu_search_user (which searches for users). The verb '搜索' (search) combined with the resource '飞书消息' (Feishu messages) provides specific, unambiguous purpose.

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 guidance in the '用法' section, detailing multiple filtering capabilities (keyword, sender, mentions, message type, time range, chat scope). It also specifies when to use this tool versus alternatives by stating that results can be used '配合 feishu_im_user_get_messages / feishu_im_user_get_thread_messages 查看上下文' (with those tools to view context). The parameter constraints section further clarifies usage rules like mutual exclusivity between time filters.

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