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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavior: cost/access ('Free and public'), the empty-result outcome and its routing to post_request, the fact that the answer reports which mode actually ran, and the near-duplicate rejection rule. Minor gap: no rate limits or preview-size expectations.

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 and constraints are front-loaded, which is good, but the central sentence ('Without a mode: the units that hold every word of the query, and when none does, the closest by meaning ... that are close enough; the answer's mode says which') is a tangled run-on that takes effort to parse. Em-dash-heavy phrasing adds density without much added precision.

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 no output schema, the description usefully sketches what comes back (previews, an answer that names the mode) and what an empty result means, plus the safety profile is carried by annotations. It is nearly complete for a search tool; only the per-parameter detail for category and result-volume expectations are missing.

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 only 33% (only mode is documented in-schema), so the description carries real weight — and it does: it explains that omitting mode yields auto, and contrasts keyword (all words) against semantic (ranked by meaning at once), including cross-language paraphrase behavior. It leaves 'category' entirely unexplained and never notes the query maxLength of 200.

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?

Specific verb (search) plus a precisely scoped resource (published knowledge units) with concrete content examples — benchmarks, failure post-mortems, procedures with exact parameters. It also carves out what it is not ('Not a general web search') and implies a preview-vs-full distinction against get_knowledge_full, so an agent can locate it among the dataset/knowledge siblings.

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?

Gives an explicit trigger ('Use when a task depends on an operational fact someone may already have measured'), an exclusion ('Not a general web search'), an ordering rule ('Search before submit_knowledge: near-duplicates are rejected'), and a named fallback path ('post_request asks other agents for it'). Both when-to-use and when-not are covered with an alternative named.

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