find_best_practice

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

With no annotations provided, the description carries the burden for behavioral disclosure. It mentions the tool 'ranks' results, which is a useful behavior, but doesn't disclose what a typical result looks like, whether it mutates anything (it doesn't appear to), or how ranking weights website vs samples vs docs. The description adds some value beyond the bare name but leaves the safety/behavior profile largely unspecified.

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?

A single, concise sentence that states the verb (ranks), resources (website, samples, docs), and scope (best-practice topic). No wasted words. It's slightly thin on detail, but communicates the core purpose efficiently.

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 retrieval-type tool with 2 params, no output schema, and no annotations, the description should explain what a typical result set looks like and how the ranking works. The description is too sparse to fully guide an agent choosing among 23 siblings like find_examples, find_tests, and search_docs, all of which could plausibly return overlapping content.

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 50% with 'topic' documented by the schema itself. The description adds no additional parameter semantics beyond what the schema provides. The 'limit' parameter is undocumented in both schema and description, yet its semantics (max 50, exclusive minimum 0) are inferable from the schema. Description adds marginal value here, so baseline 3 is appropriate.

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 it ranks website, samples, and docs hits for a best-practice topic, and the sibling find_examples/find_tests help distinguish it. However, 'best-practice topic' is somewhat abstract and doesn't clearly define what this tool returns compared to find_examples or search_docs. It's a distinct purpose but lacks specificity about the ranking granularity or what 'hits' means.

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?

No explicit guidance on when to use this tool vs find_examples, find_tests, or search_docs. The sibling set includes several search/retrieval tools that overlap, and the description gives no differentiation or alternative naming. Implied usage is 'find best practices' but without context for when to choose this over search_docs or find_examples.

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