bitrix_lists_search_letters

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

With no annotations provided, the description carries the full burden and does so well. It discloses substring matching behavior, how projectQuery restricts the result set, robustness of letterNumber matching to historical field changes, the file reference structure in results, and a known limitation with legacy CFile-based fields for outgoing letters.

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

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

The description is a single dense paragraph that front-loads the core purpose, then explains each search mode, the result-to-file-download handoff, and the known limitation. Every sentence contributes useful information without redundancy or 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?

Given that there is no output schema and no annotations, the description covers the essential search modes, result file linkage, and a specific limitation. It is slightly incomplete because it does not describe the broader result shape or limit/pagination behavior, but the critical usage path is well-covered.

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 adds meaningful semantics for projectQuery, letterNumber, and query, and indirectly covers direction via 'входящие/исходящие'. However, the limit parameter is not explained at all, leaving one parameter under-documented.

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 ('Найти письма') on a specific resource (Bitrix Lists registry, incoming/outgoing) and lists concrete search dimensions: project, subject, or letter number. It also distinguishes itself from the sibling bitrix_lists_get_letter_file by explaining that result files are passed to that 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 context for when to use the tool: search letters in the Bitrix Lists registry by project, subject, or number, and then feed result file references into bitrix_lists_get_letter_file. It does not explicitly state when not to use it or name alternatives, but no other letter-search sibling exists, so the guidance is adequate.

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