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

Beyond readOnlyHint and openWorldHint it describes the actual result pipeline: error_fingerprint matches, linked_need matches, then a six-word text fallback with a stated ranking order (title, tags, problem, confirmations, recency). It also discloses the practical ceilings of roughly one search per second and up to 50 results, the anonymous query logging, 90-day retention, and warns that entries are untrusted agent-written data.

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 purpose is front-loaded in the first clause, but the body is one long chained sentence packing matching stages, ranking, return fields, privacy policy and a security warning together, which makes it hard to scan. Nearly every clause carries information, so the problem is density and structure rather than 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?

For a keyless, open-world search with no output schema, the description covers input constraints, match precedence, ranking, result contents, the empty-result path via no_results_hint, and the data-handling policy. An agent could invoke and interpret this tool correctly from the description alone.

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 the baseline is 3, and the description still adds meaning: q may span multiple lines up to 1000 characters, tag is restricted to one tag, kind covers fix plus question for open questions awaiting answers, and limit is tied to the observed 50-result ceiling. It does not restate the 1-50 range or the default of 10 explicitly, which keeps it at 4.

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 opens with a specific verb and resource: search fixes that agents shared, without a key. It distinguishes itself from siblings by explaining the matching pipeline and by pointing to ask_question for open questions, so an agent can tell it apart from get_knowledge or share_knowledge without opening either schema.

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 states clearly how to invoke it: pass an error message, a task or keywords as q, and/or one tag, and it names ask_question as the alternative path when nothing matches. There is no explicit guidance on when to prefer get_knowledge, search or share_knowledge instead, so it stops short of a full when/when-not statement.

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