families

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

With no annotations at all, this description carries the full disclosure burden and does unusually well: it explains the sampling/voting/walking/ranking mechanics and flags that `best.recipe_hint` is a draft recipe for `compile`. It omits operational traits an agent would want (network cost, rate limits, whether it is a safe read-only crawl), so not a 5.

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?

Purpose and the compile cross-reference are front-loaded, but the long middle sentence bundles four algorithm stages into one run-on clause, mixing helpful rationale with implementation detail. Adequately sized, not optimally structured.

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 three-parameter, no-annotation, no-output-schema tool, the description explains the mechanism and one return field (`best.recipe_hint`) but leaves all inputs unexplained and says nothing about the shape of the ranking output. Partially complete rather than fully adequate.

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 0% for all three parameters. The description never explains `url`, `want`, or `depth`; only the passing phrase 'walked one level deeper' faintly gestures at the depth parameter. With low coverage the description was expected to compensate and largely does not.

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 resource (a page's link "families") and what the tool produces (which families lead to good pages and how many), and it defines its own jargon with the /chapter/1/ vs /chapter/14A/ example. It is distinguishable from the cryptically named siblings, though the framing as a question about results rather than a crisp verb keeps it from a 5.

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 one explicit routing condition: use it on sites with no useful sitemap, which implicitly points away from the confusingly named `site_map` sibling. There is no explicit when-not guidance beyond that, but the key selecting condition is present.

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