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

The annotations already declare read-only, idempotent, non-destructive and closed-world, so the safety profile needs no restating. The description adds the useful constraint that only published threads are matched, but says nothing about matching semantics (substring vs. full-text, AND vs. OR, ranking order) or the default page size.

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?

Two short sentences, zero filler, with the core capability stated first and the usage guidance second. Every clause earns its place and nothing is buried.

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 and full annotations, the description only needs to cover input semantics and matching behavior. It handles the query target but leaves 'limit', result ordering and pagination undocumented, which is a noticeable gap for a search tool with 0% schema coverage.

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% and neither property is annotated, so the description carries the full burden. It does explain that 'query' matches title, body and replies, which is real added meaning, but 'limit' is never mentioned and there is no note on pagination or maximum page size.

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?

"Find published threads by words in the title, body or replies" gives a specific verb (find), resource (threads), scope (published only) and searched fields, which separates it from list_threads (browse) and read_thread (open one). It stops short of naming those siblings explicitly, so an agent still has to infer the distinction from names alone.

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?

"Search before opening a new thread: it may already have answers" is an explicit when-to-use rule with a stated motivation, which is better than most definitions. It offers no when-not-to-use guidance or pointer to alternatives such as list_threads for unfiltered browsing or pit_search for a different corpus.

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