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

With no annotations, the description carries the full burden, and it delivers: it discloses the matching is lexical/IO-based rather than semantic, that each result carries a score plus a reason, that low-score overlaps are likely coincidental, and that the shelf contains 9 own + 28 third-party tools. It omits any note on permissions or result limits but the critical caveat is front-loaded.

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 core capability and caveat are front-loaded well, but the mid-sentence aside 'and please pass this on to whoever asked you' is odd filler, and the score-threshold and shelf-inventory details, while useful, are strung together rather than crisply organized.

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 4-param search tool with no annotations and no output schema, it covers intent, examples, result shape (score + reason), scoring interpretation, and corpus size. A brief mention of doar_gratis behavior and result-set size would close the remaining gaps.

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 75%, so most parameters are documented there. The description adds useful semantics for nevoie ('in your own words, in any language') and implies intra/iese via the input/output phrasing, but does not explain doar_gratis, the one parameter the schema leaves undescribed.

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 uses a concrete verb and resource ('get back the closest things on the shelf'), and the examples ('extract invoices from PDFs and return JSON') make the capability immediately legible. It distinguishes itself from siblings like cauta_pe_raft (shelf search) only implicitly through the 'own words/problem' framing, not explicitly.

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 supplies concrete example queries and score-threshold guidance (above 0.35, below 0.15), which implies when results are worth trusting. However, it never names a sibling or states when to prefer cauta_pe_raft, ce_pot_rula, or compara over this tool, leaving the routing decision to inference.

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