Check Rego against a JSON Schema

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: mismatches surface as rego_type_error diagnostics with file/line locations, the exact return shape `{ valid: true, errors: [] }` / `{ valid: false, errors: [...] }` is provided (important since there is no output schema), and the quirk that schemaPath-as-directory only works via `schemas:` annotations is disclosed.

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 purpose is front-loaded in the first sentence, and each subsequent sentence covers a distinct aspect: diagnostic behavior, return shape, schema input modes, and source modes. It is dense at roughly 110 words and mildly overlaps with the input schema's parameter descriptions, but nothing is 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?

With no output schema and 5 optional params spanning two mutually exclusive pairs, the description covers everything needed to invoke correctly: diagnostic type, return shape, all three schema-input modes, and both Rego-source modes. An agent can select inputs and interpret results without additional lookups.

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 100%, so the baseline is 3. The description adds value beyond the schema by tying inlineSchema to the `schema` field of rego_infer_input_schema's output and by explaining that schemaPath accepts either a file or a directory with directory reads only through `schemas:` annotations. It reinforces the source/paths split, while strict is left to the schema, which already documents it.

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 opens with a specific verb and resource: 'Validate that a Rego policy's input.* field references are consistent with a JSON Schema using opa check --schema.' This clearly differentiates it from siblings like rego_check (generic checking without a schema) and rego_lint, and explicitly positions it as a consumer of rego_infer_input_schema's output.

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 clear context for both input-mode pairs: inlineSchema vs schemaPath, with the directory mode conditioned on the policy declaring `schemas:` annotations, and inline Rego vs paths for the policy source. It names rego_infer_input_schema as a workflow upstream, but it never explicitly says when to prefer rego_check or rego_lint instead, so no exclusions or alternatives are stated.

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