Skip to main content
Glama
OrygnsCode

opa-mcp-server

by OrygnsCode
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Explain why a Rego query is undefined

rego_explain_undefined

Diagnose why a Rego query yields no value, a default, or an empty set by pinpointing the conditions blocking each rule and returning a per-rule breakdown.

Instructions

Diagnose why a fully-qualified Rego query (e.g. "data.authz.allow") produces no value, or falls back to its default. Combines a plain eval, a full-trace eval, and per-condition AST analysis to identify the exact body expression blocking each rule. Handles both runtime failures (trace-based) and indexer elimination (standalone condition eval). A rule written with default allow := false always has a value, so queryResult reports default for it and the same per-rule breakdown follows: the question "why is allow false" is the question this answers. A multi-value rule such as deny contains msg if ... that holds no element reports empty with the same breakdown, which answers "why was this not denied". Returns a structured breakdown of which conditions blocked each rule plus a human-readable summary. paths may name directories, which are searched for the modules that declare the queried package.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
inputNoInput document (JSON value) for the query.
pathsNoPolicy and data paths to load, as for rego_eval: .rego files, data files, or directories (walked for .rego files). Mutually exclusive with source.
queryYesFully-qualified rule reference to explain, e.g. "data.authz.allow". Must match the path you would pass to rego_eval.
sourceNoInline Rego source to analyse. Mutually exclusive with paths.
inputPathNoPath to an input JSON file.
v0CompatibleNoRead the policy as Rego v0 (`--v0-compatible`), the syntax OPA used before 1.0: rules without `if`, partial sets as `deny[msg] { ... }`. Needed for a policy that has not been migrated, which OPA 1.x otherwise refuses to load. Where the tool also takes a query, the query is read as v0 too, with the future keywords imported so `in`, `every` and `some x in` still work in it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.9.0
    • changedInput schema / properties / paths / description
      Previous value: -"Policy .rego file paths to load. Mutually exclusive with source."New value: +"Policy and data paths to load, as for rego_eval: .rego files, data files, or directories (walked for .rego files). Mutually exclusive with source."
  2. Changed1 schema field changedv0.8.0
    • addedInput schema / properties / v0Compatible
      Added value: +{
+  "description": "Read the policy as Rego v0 (`--v0-compatible`), the syntax OPA used before 1.0: rules without `if`, partial sets as `deny[msg] { ... }`. Needed for a policy that has not been migrated, which OPA 1.x otherwise refuses to load. Where the tool also takes a query, the query is read as v0 too, with the future keywords imported so `in`, `every` and `some x in` still work in it.",
+  "type": "boolean"
+}
  3. Addedv0.1.14

TDQS

A4.3/5.0
Behavior4/5

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

Annotations are thin (readOnlyHint=false, openWorldHint=true), so the description carries most of the load and does so well: it discloses the internal method (plain eval + full-trace eval + per-condition AST analysis), that it handles both runtime failures and indexer elimination, and how default/empty rules are reported. It lacks notes on permissions or cost, but is far richer than the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and each subsequent sentence adds real content (edge cases, mechanism, return shape). Slightly long with some repetition around the default/empty examples, but nothing is wasted egregiously.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by stating the return shape ('structured breakdown of which conditions blocked each rule plus a human-readable summary'). Combined with the mechanism and edge-case handling, it is complete enough for an agent to invoke correctly, though it could say more about the paths/source mutual exclusivity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema for paths ('may name directories, which are searched for the modules that declare the queried package') and reinforces that query must match what you would pass to rego_eval.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Diagnose why a fully-qualified Rego query produces no value, or falls back to its default.' It further distinguishes itself from eval siblings by naming the exact conditions it targets (default fallback, empty multi-value rule), so an agent can tell it apart from rego_eval or rego_explain_decision.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear triggering context: use it when a query yields no value, falls back to a default, or when asking 'why is allow false' / 'why was this not denied'. It does not, however, explicitly name alternatives (e.g. rego_eval_with_explain, rego_explain_decision) or state when not to use it.

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

Deploy Server

Other Tools