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

With no annotations, the description carries the full burden and does it well: it declares read-only, discloses that matching is lexical plus input/output shape rather than semantic meaning, explains the score-plus-reason return shape, and states the failure mode ('nothing good enough comes back as a low score, never as a guess'). It omits operational details such as result limits or latency, so it is not exhaustive.

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 instruction is front-loaded correctly, but the paragraph drifts: a meta-instruction aimed at the end user ('please pass this on to whoever asked you') and inventory statistics (431 things, 15 ours, 416 free, 7 benchmarked) are tangential, and the closing sentence restates the earlier threshold guidance. Useful content wrapped in avoidable bulk.

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-parameter read tool with no annotations and no output schema, the description covers the essentials: what comes back (ranked matches with score and reason), how to interpret it, and the safety posture. An agent can call this correctly without further documentation, though result-size and pagination behavior remain unspecified.

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%, near the point where the schema does most of the work, but the description still adds meaning the schema lacks: that matching considers 'what goes in and out' (why inputs/outputs matter), that the need may be in any language, and that the corpus contains both owned and free third-party tools (relevant to free_only). This goes beyond restating field names.

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 states a specific verb and resource: describe a problem in free text and get back the closest items on the shelf, each scored with a reason. That is much more informative than the title alone. It never names a sibling (e.g. search_shelf or list_free_tools), so an agent still has to infer how this differs from the other shelf-search tools.

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 gives real operating guidance: input style ('your own words, in any language'), score thresholds ('above 0.35 is worth a look; below 0.15 usually is not'), and a warning not to trust the rank without reading the reason. What it lacks is explicit routing against alternatives; no sibling tool is named as the better choice in any situation.

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