WATR Software Oracle — estándar de arquitectura por rule_id

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

With no annotations, the description carries the full burden; it implies a read-only lookup returning a 'complete' rule, but says nothing about behavior on an unknown rule_id, whether lookup is case-sensitive, or whether permissions apply. Since an output schema exists, the return shape is covered elsewhere, keeping this at a middling score.

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?

Two short lines: the purpose is stated first, then only the example IDs, which earn their place by teaching the ID format. No filler or redundancy.

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 single-parameter lookup with an output schema, the essentials are present, but nothing explains how to discover valid rule_ids or what happens when one is not found, and the relationship to the search/list siblings is unaddressed.

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 0%, so the schema gives no meaning for rule_id, but the description compensates with four concrete example IDs (CC-FN-01, SOLID-DIP-01, SMELL-14, WATR-MH-02) that reveal the prefix-based ID format. It does not state whether IDs are exact-match or prefix-tolerant, leaving one gap.

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 specific verb (devuelve/returns) and resource (una regla, smell o meta-heurística) plus the lookup key (rule_id), so an agent knows exactly what it fetches. It does not explicitly contrast with siblings such as search_practices, which is the main ambiguity an agent could still face.

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 guidance on when to use this versus search_practices or review_code, and no mention of how an agent should obtain a valid rule_id (e.g., via search or list_domains). Usage is only inferable from the purpose statement itself.

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

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

With no annotations supplied, the description carries the full burden and does well: it discloses third-party egress to api.typesafe.ai, admits a quantified false-negative rate rather than overselling, and frames the output as non-authoritative probabilities. It omits operational details such as authentication, rate limits, latency, or cost, which keeps it short of a 5 for a no-annotation tool.

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 sibling contrast are front-loaded, then the two warnings follow in descending importance, which is the right order. It runs long and the measured-statistics sentence could be tightened, but nearly every sentence adds decision-relevant information rather than filler.

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 probabilistic judgment tool with network egress and no annotations, the definition covers purpose, alternatives, accuracy limits, and privacy risk, and an output schema exists so return values need not be explained. The gaps are real: the `language` parameter is unaddressed, and the description invokes a stance/threshold mechanism without saying how a caller supplies or influences it.

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, and it largely does not: `code` is only alluded to as 'el fragmento' and the `language` parameter is never mentioned at all. It also references a 'stance' and threshold selection that have no corresponding parameter in the schema, leaving the agent unsure how that mechanism is controlled.

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 opening states the resource (a code fragment) and what comes back (a probability per rule), and the second paragraph explicitly contrasts it with `review_code`: here the corpus judges, there you judge. The phrase 'opinión del corpus' is slightly metaphorical, but combined with the sibling contrast an agent can tell the two apart without opening either schema.

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 explicit when-to-use (order what to review first and say which rule), explicit when-NOT-to-use (not a gate, do not wire it into CI, with measured evidence of 38% of violations passing), and an explicit alternative for the privacy case (use `review_code` if the code cannot leave the machine). Nothing is left for the agent to infer.

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

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

No annotations are supplied, so the description carries the full burden of behavioral disclosure, and it only describes the payload's contents. It says nothing about read-only safety, corpus size, whether the full taxonomy is returned at once, or any auth/rate constraints. A single tool with zero annotations can be fully covered in one more clause, and this description doesn't do it.

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 front-loaded clause with no filler, and the enumeration of returned entities is packed into one short sentence. The only structural weakness is that it is a noun phrase fragment with no leading verb, which makes it read as a label rather than an instruction.

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?

The tool is simple — no parameters, and an output schema exists — so the description doesn't need to explain return values, though it does anyway. What remains missing is positioning against the four sibling tools, which matters a lot for a zero-arg discovery tool that an agent must choose deliberately.

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?

The tool takes zero parameters, so the schema already fully specifies the input surface and 100% coverage means there is nothing for the description to add. Baseline 4 is arguably earned, but the description also recasts the output fields (domains, topics, rule_id, stance) without adding syntactic meaning; a 3 reflects an adequate but non-contributing parameter story.

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 names the resource precisely: a map of the corpus covering domains, topics, each topic's rule_id, and stance. An agent can infer this is an index/overview listing rather than a fetch of a single rule. It stops short of an explicit verb (e.g., 'list') and never names the sibling it is not, so it doesn't reach 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?

There is no when-to-use guidance at all — nothing says to call this first to discover valid rule_ids before calling get_rule, nor any exclusion against search_practices or review_code. The only implicit signal is that this tool takes no arguments, which slightly suggests an entry-point/browse call.

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

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

No annotations are supplied, so the description carries the full burden, and it does meaningful work: it discloses that the tool does NOT judge, that it returns observed structural signals, rules with their stance, governing meta-heuristics, and a mandatory output format. That non-judgment boundary and the 'consistency comes from the corpus' framing are exactly the behavioral context an agent needs before calling.

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?

Front-loaded with the core action in the first sentence, followed by scope clarification and a reframing line. The second paragraph is slightly rhetorical ('el razonamiento y el veredicto son tuyos'), but each sentence still carries usable meaning.

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?

Because an output schema exists, return shape needn't be explained, and the description correctly focuses on scope and role. However, with 0% parameter coverage the definition leaves the language parameter and the expected code format entirely undocumented, and it never routes the agent against its four siblings.

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 both parameters: 'code' and 'language' have no descriptions beyond bare titles. The description only says 'un fragmento', giving no format, size, or path expectations for code and never mentioning the language parameter or how the empty-string default is interpreted.

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 specific verb+resource: it returns the WATR standard/rules that apply to a code fragment. The line 'Este servidor no juzga el código' implicitly separates it from the sibling judge_code, though it never names that sibling, so the differentiation is inferred rather than explicit.

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?

Usage is only implied: call this when you want the agent itself to produce the verdict rather than the server. It never explicitly says when to pick this over judge_code or get_rule, nor mentions any prerequisites, so the agent must infer the routing.

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

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.