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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by explaining the semantic search mechanism, the ranking by embedding similarity, and the exact fields returned in each result. While it doesn't disclose potential rate limits or lack-of-results behavior, the core read-only nature and output structure are adequately covered.

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 compact yet comprehensive, containing only two sentences. The first sentence front-loads the purpose and output; the second gives a usage directive and a comparative alternative. Every sentence earns its place without redundancy.

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?

Given there is no output schema, the description compensates by explicitly listing the return fields (Laddoo score, evidence_tier, review URL). It also provides a concrete task example. The main gap is not addressing edge cases like zero results or handling of min_score, but for a semantic search tool this is a minor omission, and the description is otherwise complete.

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?

The input schema already covers all three parameters with descriptions (100% coverage), so the description adds little beyond what the schema provides. The example in parentheses ('I need an agent that can refactor TypeScript...') illustrates the description parameter but doesn't clarify top_k or min_score further. This meets the baseline for high schema coverage.

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 starts with a specific verb phrase 'Semantic search over Hlido's review corpus' and clearly states what it returns: top-N agents ranked by embedding similarity with Laddoo score, evidence_tier, and review URL. It also distinguishes itself from the sibling find_trusted by noting it is 'much better than substring matching', making the purpose unmistakable.

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 explicitly states when to use it: 'Use this when you have a task in mind and want Hlido's recommendation'. It also provides an alternative by comparing to find_trusted ('much better than substring matching via find_trusted'), which effectively advises when not to use the alternative. This satisfies the explicit when/when-not/alternatives criterion.

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