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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description does not need to cover mutation or open-world assumptions. It adds useful context about the underlying index and output format, but it does not disclose potential behavioral nuances such as relevance ranking caveats or empty-result behavior. There is no contradiction with annotations.

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 description is a single dense sentence that front-loads the action and scope, uses a parenthetical to add valuable context about the Ensight index, and ends with the return type. Every phrase earns its place with no redundancy or 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 simple two-parameter search tool with fully documented parameters and no output schema, the description sufficiently covers what it searches, where it searches, and what it returns. It stops short of describing ordering or relevance semantics in detail, but 'best-matching' implies relevance-based ranking, and the schema covers the remaining invocation details.

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 100%, so the baseline applies: the schema already documents the query as a natural-language question or keywords and topK as the number of passages to return. The description adds no parameter-level detail beyond this, though it is consistent with the schema.

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 verb ('semantic search') and a precise scope: Entogo's product, solution, manufacturing, certification, lead-time, and warranty knowledge. It also distinguishes itself from structured lookup siblings like get_product or get_lead_time by framing the tool as passage-level, natural-language search, and it states the return type (best-matching passages with source URLs).

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 when to use it—for open-ended semantic questions across the named knowledge domains—and the schema reinforces this with a natural-language query field. However, it does not explicitly state when not to use it or point to alternatives like get_product for exact product lookups or get_lead_time for specific lead-time figures, so the decision rule is left to inference.

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