find_chat

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

No annotations are provided, so the description fully carries the behavioral disclosure burden. It reveals the response structure (ranked matches in my_results and results), the selection logic (taking only my_results→results, not the entire pool), and explicitly declares the operation as 'read-only'. This goes well beyond a simple statement of what the tool does.

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 longer than a minimal one-liner, but each sentence adds valuable context about ranking, selection, and fallback. It is front-loaded with the core purpose and then flows into implementation details. The TODO note is slightly tangential but relevant to future behavior, making the description efficient overall.

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 moderately complex (server-side search with ranking, multiple result sets, and a fallback path). The description covers the behavioral flow, selection criteria, and read-only nature. It omits details like error handling or rate limits, but the presence of an output schema makes the absence of explicit return-value description acceptable. The description is complete enough for an agent to invoke the 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 compensate. The query parameter is implied as the search string, but the limit parameter is not described at all. No additional meaning is added beyond the field names, failing to fully compensate for the schema's lack of 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 'Find chat by search (not by iterating over dialogs)' and specifies 'server-side contacts.Search', identifying the exact verb, resource, and method. It also distinguishes from sibling tools by explicitly contrasting with iterating over dialogs (list_chats) and implying a search scope different from search_in_chat.

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 context for when to use this tool: for search-based lookup of chats/contacts rather than brute-force iteration over dialogs. It mentions a fallback to local filtering as a TODO, implying the current server-side search is the primary approach. However, it doesn't explicitly name alternative tools or provide detailed when-not-to-use scenarios beyond the 'not iterating dialogs' exclusion.

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