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

Annotations already mark the operation read-only and open-world. The description adds context by clarifying that it only searches public threads, defining the unanswered filter ('only one visitor message'), and stating that results include thread IDs and message counts.

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?

A single compact sentence conveys scope, filter semantics, and return value shape with no filler. The key behavioral detail (unanswered) is placed prominently.

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 read-only search tool with moderately simple parameters, the description covers purpose, filter behavior, and returned fields. Pagination and session_token behavior are only partially covered, but the schema supplies session_token details and the tool is otherwise well-scoped.

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 only 25%, but the description compensates for q ('by topic') and unanswered (single visitor message). It does not clarify page semantics, leaving an important pagination parameter underdocumented.

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 names a specific action ('Find'), a clear resource ('public conversation threads'), and a search dimension ('by topic'). It also distinguishes this discovery tool from siblings like read_thread, start_discussion, and reply.

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 this is the search/discovery tool for public topics, but it does not explicitly state when to use it instead of siblings such as read_thread. The 'unanswered=true' filter offers one clear use case, so guidance is present but mostly implicit.

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