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

With no annotations, the description carries the full burden, and it does disclose the important trait that retrieval is lexical rather than semantic and that a non-English query will underperform. It does not state that the operation is read-only (implied by 'search'), nor anything about ranking, index scope, or limits beyond 'top-k'.

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?

Three short blocks, front-loaded with purpose then the language constraint, with the alternative tool named last. Every sentence carries information; the only minor friction is that the definition is written in Spanish while insisting the query be English, which is slightly ironic but not wasteful.

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 two-parameter search tool with an output schema and no annotations, the description covers the essentials: query language, lexical retrieval nature, return contents (rule_id and stance), and the follow-up tool. Only the k semantics and ranking behavior are left unexplained.

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%, so the description must compensate. It adds crucial meaning for the query parameter (must be English, translate intent before calling) and the phrase 'top-k' hints at the k parameter, but it never explains what k controls numerically, its default of 5, or any upper bound.

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?

States a concrete verb and resource: search WATR standard rules that apply to a query or fragment. It separates itself from get_rule by noting it returns only top-k with rule_id and stance while get_rule supplies full text, but it says nothing about how it relates to judge_code or review_code, which are also rule-driven alternatives.

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?

Gives real usage guidance: the query must be in English because the corpus is English and the search is lexical, and instructs translating intent first with a worked example ("catch vacío" -> "empty catch swallowing error"). It also points to get_rule as the follow-up for full rule text. It stops short of an explicit when-not-to-use rule versus the code-review siblings.

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