search_chats

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

With no annotations, the description bears full responsibility for behavioral disclosure. It mentions that the 'limit' parameter is 'applied client-side', which is a useful behavioral detail. However, it does not disclose any other traits such as authentication requirements, rate limits, or the impact of the search (e.g., whether it triggers side effects). The disclosure is partial.

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, using three well-structured sentences. The main purpose is front-loaded ('Search for chats by name or description'), followed by parameter descriptions and return summary. Every sentence adds value with no redundant information.

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 tool's simplicity (2 parameters, straightforward search), the description covers the essential aspects: purpose, parameters, and return structure. The presence of an output schema reduces the need to detail return fields, but the description still provides a useful summary of the payload contents. The description is complete for agent 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 coverage is 0%, so the description must fully explain parameters. It does: 'query' is described as a search query string, and 'limit' is explained with its default value and that it is applied client-side. This adds substantial meaning beyond the schema's bare type and default fields.

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 action ('Search for chats') and the specific fields to search against ('by name or description'). This verb+resource specification differentiates it from sibling tools like 'search_messages' and 'search_users', which perform searches on different entities.

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 implies the tool should be used when searching for chats, but it does not explicitly state when not to use it or provide alternative tools. The sibling tools are listed in context, but no guidance is given on when to prefer one over another. The description lacks explicit usage boundaries.

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