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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is free to add behavioral context — and it does: Pāli-only index with an untuned multilingual model, English/Thai embedding degradation, score clustering on stock phrases, and the empty-result-means-nothing-cleared contract. The only gap is that it doesn't mention how the Pāli output language flag interacts with a null/disabled Thai result beyond the schema note.

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?

Well-structured with bolded section headers, emoji anchors, and the most decision-relevant content (use search_hybrid, then limitations) front-loaded. It is on the long side and the limitation bullets overlap somewhat, but nearly every sentence changes how an agent would call or interpret the tool.

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?

An output schema exists, so return value explanation is not needed, and the description covers the remaining agent-facing concerns: model scope, query-language ranking, result-ordering caveats, distance interpretation, and result-set behavior. Nothing needed to invoke or interpret the tool correctly is 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 100%, so the baseline is 3, but the 'Reading `distance`' section adds genuine interpretive meaning — smaller-is-closer semantics, the default cut of 0.7, and how raising/lowering threshold trades strictness for breadth — that goes beyond the schema's terse parameter descriptions. It stops short of giving concrete threshold guidance for specific query types, keeping it a 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?

Opens with a specific verb+resource and immediately defines the mechanism ('match by meaning, not exact words') plus the underlying implementation (cosine similarity over text_pali MiniLM embeddings). It explicitly distinguishes itself from search_hybrid and search_by_keyword, so an agent can differentiate it from siblings without opening schemas.

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?

Contains an explicit routing directive ('in most cases use search_hybrid instead') plus the three narrow conditions where this tool is the right choice (pure semantic, threshold tuning, debugging). It also names search_by_keyword for exact Pāli terms. This is the full when/when-not/alternatives triad.

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