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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the description only needs to add context, and it does: a 180-day lookback window, result sampling ('shows a few chats with the message and its neighbours'), and an explicit 'nothing is linked' statement so the agent knows the inferred identity is not persisted. The untrusted-content warning is also actionable. It stops short of 5 because the sampling limit is vague ('a few') and the return shape is left entirely to the output schema.

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 180-day scope and the grouped-by-contact framing are front-loaded, and nearly every sentence carries information that changes how the agent interprets results. The identity-evidence sentence is convoluted enough to require a second read, and the branch list could have been compressed, but there is no 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?

With an output schema present, return values need not be described, and the description covers the time window, the grouping, the sampling behavior, the no-side-effects guarantee, and prompt-injection safety. The only real gap is the absence of any pointer to the sibling search tools for the plain message-search case.

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 100%, so a baseline of 3 would be defensible, but the description genuinely adds meaning the schema lacks: it explains what the result set becomes under each chat_id variant, which the schema only gestures at. The phrase parameter's case-insensitivity and length bounds remain schema-only, which is fine.

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 opening clause states a specific resource and filter: chats containing an exact phrase within the last 180 days, grouped by contact. That is far more precise than the name alone and conveys the unusual identity-linking angle. It never names a sibling, though, so an agent choosing between this and search_messages_and_contacts or list_messages must infer the distinction from the identity-grouping behavior.

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 three chat_id branches are spelled out explicitly (no chat_id = every one-to-one chat; hidden-number chat_id = the other chats; normal chat_id = hidden-number chats not linked to its contact), which is genuine usage guidance for the parameter's modes. What is missing is any statement of when to prefer this tool over the search siblings, or any exclusion beyond the implicit one-to-one scope.

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