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

Beyond the annotations, the description discloses that the target directory is emptied before the pull, warns that pulled policies are arbitrary executable Rego with exfiltration/network risks, and notes the external binary dependency and path restrictions. This is substantial value added on top of destructiveHint and readOnlyHint.

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 description is front-loaded with the main action and each subsequent sentence covers a distinct aspect: use case, prerequisite, path constraint, and security warning. No filler or redundancy; the security warning earns its place.

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 side-effectful tool with no output schema, the description covers purpose, prerequisites, destructive side effects, security implications, and path constraints. An agent has everything needed to decide whether to call it and to call it safely.

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?

With 100% schema description coverage, the schema already documents the url schemes and the policy directory fallback and emptying behavior. The tool description doesn't add new parameter-level meaning beyond restating that the policy directory must be inside allowed paths, so the 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 opens with a specific action: 'Download Rego policies from an OCI registry or Git repository into a local directory using conftest pull.' It identifies the resource, destination, and direction, and it distinguishes itself from the sibling conftest_push by direction and from conftest_test by sequencing ('hydrate ... before running conftest_test').

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 usage context: 'Use this to hydrate a local policy/ directory before running conftest_test' and states prerequisites (conftest on PATH or CONFTEST_BINARY, OPA_MCP_ALLOWED_PATHS). It does not explicitly name an alternative to use instead, but the download-vs-push contrast and the sequencing with conftest_test provide clear context.

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?

Annotations already flag this as destructive, non-idempotent and open-world, so the safety profile is covered. The description adds genuinely useful context beyond that: it never handles credentials, auth must pre-exist (docker login/ORAS keychain/REGISTRY_AUTH_FILE), and the allowed-paths sandbox constraint. It doesn't discuss overwrite behavior for an existing tag or failure modes.

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 sentences, front-loaded with the action, followed by the two operational prerequisites. Every sentence earns its place, though it is slightly dense with environment requirements that could be trimmed.

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 remote-mutating tool with no output schema, the description covers the essentials an agent needs: authentication expectations, path sandboxing, and the required binary. It omits what a successful push returns and how an existing tag at the same repository is handled, which leaves a small gap.

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 schema already documents `policy`, `repository` and `v0Compatible` in depth. The description reiterates the allowed-paths and credential constraints but adds no syntax or format detail the schema lacks; baseline 3 applies when the schema does the heavy lifting.

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 and resource: packages a local Rego policy directory as an OCI artifact and pushes it via `conftest push`. This is clearly distinguishable from the pull-oriented sibling conftest_pull and from the bundle tools.

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 concrete preconditions for use: credentials must be pre-configured in the host environment, the policy directory must be inside OPA_MCP_ALLOWED_PATHS, and conftest must be on PATH or CONFTEST_BINARY set. It does not explicitly name a when-not or alternative tool, so it stops short of a 5.

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 readOnlyHint=false and openWorldHint=true already declared, the description goes further: it discloses the binary prerequisite and failure mode, the mutual-exclusivity rules for policy/config sources, the default ./policy fallback, the per-file/per-namespace pass/fail/warn return shape, and that policies can invoke OPA built-ins like http.send (network egress).

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 and return contract, then prerequisites and source-selection rules. It is dense and somewhat long for a description, but nearly every sentence carries non-schema information.

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 12-parameter, zero-required, no-output-schema tool, the description covers invocation prerequisites, input source selection, defaults, return structure, and execution environment. An agent has enough to call it correctly without opening the schema.

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 100%, so the baseline is 3; the description earns extra by spelling out the paired sources (`files` vs `inlineConfig`, `policy` vs `inlinePolicy`), the omit-policy default, and the parser/inlineConfigParser split. Most per-parameter detail, however, remains in the schema.

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?

Starts with a specific verb+resource ('Evaluate configuration files') and enumerates the accepted input formats, then names the underlying command. It also distinguishes itself from siblings like rego_test/conftest_verify by naming the conftest execution path and the file-vs-string input model.

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?

Explains when this applies (config files vs Rego policies) and states the prerequisite (`conftest` on PATH or `CONFTEST_BINARY`), plus the CONFTEST_NOT_FOUND outcome. It does not explicitly compare against siblings such as conftest_verify or rego_test, so no exclusions are given.

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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, which say nothing specific), it discloses concrete behavior: per-file pass/fail results, a NO_TESTS_FOUND sentinel for empty test sets, the external `conftest` dependency (PATH or CONFTEST_BINARY), and a CONFTEST_NOT_FOUND failure mode. This is genuinely useful operational context, though it omits what happens if a test itself errors mid-run.

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?

Four sentences, each carrying distinct information (what it runs, the opa-test equivalence, return values, dependencies), with the core purpose front-loaded. It is dense but not padded; the equivalence sentence could be tightened slightly but earns its place by anchoring expectations.

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, the description correctly steps in to describe return shape (per-file pass/fail, NO_TESTS_FOUND) and prerequisite/environment failure (CONFTEST_NOT_FOUND). For a 4-param, zero-required tool this is largely complete; the only gap is the unaddressed overlap with the conftest_test sibling.

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 parameters (data, policy, namespace, v0Compatible) are already fully documented with constraints and allowed roots. The description adds only a passing reference to the policy directory and does not enrich parameter meaning beyond the schema, so the baseline 3 applies.

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 gives a specific verb and resource ('Run the `test_*` rules inside `*_test.rego` files within a conftest policy directory') and clarifies the goal is verifying the policies themselves. It is clear in isolation, but it never distinguishes itself from the very similar sibling conftest_test, so an agent cannot confidently route between them.

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 implies usage by framing the tool as 'Equivalent to `opa test` but using conftest's policy-loading machinery', which hints at when to pick it over plain OPA tooling. However, it gives no explicit when-to-use/when-not, and says nothing about how it differs from conftest_test or the rego_test siblings, leaving the closest routing decision to inference.

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?

Annotations already indicate readOnlyHint=true, destructiveHint=false, etc. The description adds value by specifying what the tool returns (name, version, runtime details) and that it checks binary reachability. No contradiction with annotations.

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 concise sentences: first states purpose, second provides usage guidance. No wasted words, front-loaded with key information.

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 description covers return values (name, version, runtime details, binary status) adequately. No output schema, but the description provides sufficient context for a simple info tool. Minor gap: 'runtime details' is vague, but overall complete enough.

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 has no parameters, and schema coverage is 100%. The description does not need to add parameter info. Baseline for 0 parameters is 4, and the description adds no unnecessary detail.

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 clearly states the tool returns name, version, and runtime details of the opa-mcp server. The verb 'Return' and resource 'opa-mcp server instance' are specific. Among siblings which are mostly OPA/Conftest/Rego manipulation tools, this is the only info tool about the server itself, so differentiation is clear.

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?

The description explicitly states two use cases: confirming the version of opa-mcp and verifying reachability of OPA, Regal, and Conftest binaries. While it doesn't mention when not to use it, the context is clear and no alternatives are needed as the tool is unique among siblings.

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?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, so the write/overwrite profile is covered. The description adds useful context about the output artifact and inline signing, but does not disclose that an existing output file may be overwritten or that paths must fall within allowed roots beyond what the schema says.

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 tight sentences, front-loaded with the core action and artifact. The trailing capability list is slightly list-like but still earns its place by signalling optimization/signing/WASM support up front.

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 build tool with no output schema, the description supplies the key missing piece an agent needs — the returned artifact type and that signing is optional — while the rich schema and annotations carry parameter and safety detail. Routing guidance versus sibling bundle tools is the only notable gap.

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% and the schema documents all 17 parameters in depth, so the baseline is 3. The description's mention of optimization, custom revision strings, and the WASM target echoes only a few of those parameters and adds little syntax or format detail beyond the schema.

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 ('Build a deployable bundle from policy / data paths using `opa build`') and names the output artifact (`.tar.gz` archive). This clearly distinguishes it from siblings like opa_bundle_sign and opa_bundle_verify, which operate on an existing bundle rather than producing one.

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 implied by the 'build' framing and the mention of signing/WASM targets, but the description never states when to reach for this tool versus opa_bundle_sign, opa_bundle_verify, or opa_put_policy. No prerequisites (allowed roots, signing key requirements) are stated outside the schema.

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?

The description goes well beyond the annotations by disclosing the in-place mutation ('signed in place', `.signatures.json` is written), the naming scheme for recorded files, archive refusal, key-type constraints, and return values. These details align with `destructiveHint=true` and `idempotentHint=true` without contradicting them, and they compensate for the lack of an output schema.

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?

Although longer than typical tool descriptions, every sentence carries a distinct piece of information: action, side effects, archive exception, key details, claims, and return value. The most decision-relevant fact (archive refusal and `opa_bundle_build` route) is placed after the core mechanics, which is still well front-loaded and dense without padding.

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 4-parameter tool with no output schema, the description covers the operation, side effects, return payload, parameter specifics, and the important boundary case (archives). The only minor omission is behavior when `.signatures.json` already exists, but the `idempotentHint` annotation covers that, so nothing essential is missing.

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 schema already documents all four parameters (100% coverage), so the baseline is 3. The description adds value on top by explaining that RSA/ECDSA keys are PEM files while HMAC algorithms expect a file holding the secret, and by spelling out what `claimsFile` should contain. This moves it to a 4.

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+resource pair ('Sign a bundle directory with `opa sign`') and immediately differentiates from siblings by explaining it signs directories, not archives, and that signed archives come from `opa_bundle_build`. It also names `opa_bundle_verify` as the counterpart for verification, so an agent can distinguish it among the bundle-related tools.

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?

Explicitly states that archives are refused and directs agents to `opa_bundle_build` with `signingKey` when a signed archive is needed. It also tells agents where the signed directory can be verified (`opa_bundle_verify`, `opa build`, `opa run --bundle`), making the tool's place in the workflow clear. No ambiguity about when to use this tool versus its bundle siblings.

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?

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description goes well beyond that by disclosing the temp-file mechanism, the file-by-file verification order, digest-vs-parsed-value differences, failure reason enumerations, and the precise condition for returning `verified: true`. It also surfaces the `verificationKeyId` nuance.

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 description is long but every sentence carries substantive behavioral or edge-case information for a complex tool. It is front-loaded with the core purpose and implementation, then proceeds into verification details and error conditions. Some schema repetition exists, such as the `scope` instruction, but overall it earns its length.

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?

Given there is no output schema, the description thoroughly documents return behavior: `INVALID_BUNDLE` with an enumerated `details.reason`, `INVALID_INPUT` for unusable keys or algorithms, and the exclusive condition for `verified: true`. It also covers failure ordering, v0 compatibility, directory verification convention, and key-ID behavior, making the tool self-sufficient for correct invocation.

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 100%, so a baseline of 3 applies, but the description adds meaningful semantics: `scope` is emphasized as needing to match the signing value exactly, `v0Compatible` is tied to post-signature failure behavior, and `verificationKeyId` is explained as rarely needing to be set with a single key. This enriches the schema without being redundant.

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 sentence names a specific verb and resource: 'Verify the signature of a signed bundle directory or `.tar.gz` archive with the public key.' It also clarifies the implementation mechanism and the matching relationship to `opa_bundle_sign`, which distinguishes it from general Rego verification siblings like `rego_verify` and `conftest_verify`.

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?

The description gives strong usage context: it explains that OPA has no standalone verify command, how the verification is performed, what inputs are required, and how `scope` must exactly match the signing value. It does not explicitly name alternative tools or say when not to use this tool, but the guidance is clear enough to invoke correctly.

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?

Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds value by specifying the exact HTTP endpoint and explaining the concept of partial evaluation (substituting knowns). This provides behavioral context beyond annotations without contradiction.

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 sentences efficiently deliver the action and result. No extraneous text. The first sentence is front-loaded with the verb 'compile' and endpoint, making it immediately actionable.

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 description covers the tool's core behavior and return value (residual query) without an output schema. It assumes familiarity with OPA concepts but is sufficient for an agent. Could add more on use cases or prerequisites, but is adequate for the complexity.

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 100% with clear descriptions for all three parameters. The tool description reinforces the purpose of partial evaluation but does not add new parameter-specific details beyond the schema. Baseline score of 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 clearly states the tool sends a query to the OPA server's /v1/compile endpoint for partial evaluation and returns the residual query. This distinguishes it from evaluation tools like rego_eval or opa_query_decision, showing a specific verb and resource.

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?

The description does not explicitly state when to use this tool vs alternatives such as rego_eval or opa_query_decision. It only mentions partial evaluation but gives no guidance on scenarios or exclusions, leaving the agent to infer usage context from the tool name and siblings.

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?

The description discloses non-obvious behavior well beyond the annotations: OPA drops the `credentials` block, returns `services.*.headers` verbatim, and redacts header values while keeping header names. This is exactly the kind of behavioral context that helps an agent anticipate the returned data and security implications.

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 sentences, front-loaded with the core purpose and followed by a high-value behavioral caveat. Every clause earns its place; there is no redundant or filler content.

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?

This is a simple zero-parameter read operation. The description states what is returned, where it comes from, and the important redaction behavior. Annotations already convey read-only and idempotent safety. No critical information is missing for correct invocation.

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 has zero parameters and the schema coverage is 100%, so there are no parameter semantics for the description to clarify. Per the rubric, a zero-parameter tool gets a baseline of 4.

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 uses a specific verb ('Return') and a precise resource ('the running OPA server configuration from `GET /v1/config`'). This clearly identifies what the tool does and separates it from sibling tools like opa_status or opa_health, which concern server health rather than configuration.

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?

The use case is implied: if an agent needs the running OPA server configuration, this is the tool. However, the description does not explicitly state when to prefer this over alternatives or mention any exclusions, so guidance is present only by inference.

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?

Beyond the annotations (destructiveHint=true, idempotentHint=false), the description discloses the 204 success response, the 404-to-DATA_NOT_FOUND mapping, and the intentional root-path exclusion. These behaviors directly inform an agent about success, failure, and edge cases, which is exactly the kind of context annotations alone cannot provide.

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 description is information-dense but every sentence earns its place: the core action, path syntax rules, fallback parameter guidance, and edge-case behavior are all stated with no filler. The most important context is front-loaded and the formatting is easy to scan.

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 destructive operation with no output schema, the description is complete: it covers success codes, error mapping, path constraints, and the root-path edge case. The annotations already mark the destructive nature, and the description fills the remaining behavioral gaps an agent would need to safely invoke the tool.

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?

Although the schema already covers 100% of parameters, the description adds crucial semantics: dotted vs slash-only path parsing, how to address keys containing dots or slashes, and when to switch from `path` to `segments`. This resolves ambiguous inputs that the schema descriptions only partially convey.

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 uses a specific verb ('Remove') with a clear resource ('document from OPA's data store') and the path-based scope. It naturally distinguishes itself from sibling tools like opa_delete_policy by explicitly targeting the data store rather than policy.

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?

The description gives clear operational context: it explains when to use `path` vs `segments`, notes the root-path deletion exclusion, and requires at least one segment. It does not explicitly compare itself to alternative data-management tools like opa_patch_data or opa_put_data, but the conditional guidance is strong and the tool's purpose is unmistakable among siblings.

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?

Annotations already declare destructiveHint=true, making the delete behavior clear. The description adds minimal extra context ('from the running OPA server') but does not disclose potential side effects, authentication needs, or constraints beyond the schema.

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 sentence with no wasted words. Every word is necessary and clear.

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?

Given the simple one-parameter schema and no output schema, the description is mostly complete. However, it could mention error handling (e.g., policy not found) or that deletion is permanent, which would raise completeness to 5.

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 100% with 'Policy ID to delete.' in the parameter description. The tool description adds no further meaning, meeting the baseline of 3.

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 clearly states the action 'Delete', the resource 'a policy', and specificity 'by ID from the running OPA server'. This distinguishes it from sibling tools like opa_get_policy or opa_delete_data.

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 tool vs alternatives (e.g., opa_put_policy to update) or prerequisites like ensuring the policy exists. The description only states the action without contextual usage advice.

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?

Annotations are sparse (readOnlyHint=false, openWorldHint=true) so the description carries real weight, and it delivers: mutual exclusivity of bundle/dataPaths, per-file failure reporting ('appears in `results` with an `error` field rather than a `result` field'), and the gating semantics where errors become `failed: true` instead of throwing. Note the description frames the operation as pure evaluation while readOnlyHint=false implies otherwise, but the description never claims a read-only guarantee, so this is conservatism rather than a contradiction.

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?

Four dense sentences with no filler, ordered purpose → alternative → parameter relationships → gate behavior, so the most decision-relevant information is front-loaded. It runs long, but every clause maps to a real selection or invocation decision.

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 10-parameter tool with no output schema, the description covers the essentials: which parameters are mutually exclusive, what the per-file result surface looks like (result vs error), and what the gate flags change. It stops short of describing the full success-result shape per file, which is the only remaining gap.

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 100%, so the baseline is 3, but the description goes beyond by explaining the relationship between `bundle` and `dataPaths` (mutually exclusive, loaded as `opa eval --data` would) and why the `decision` path form matters ('passing one straight through leaves every file undefined'). That is semantic framing the schema alone does not establish.

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?

Opens with a specific verb+resource ('Evaluate a policy decision against one or more input files using `opa exec --format=json`') and immediately scopes it against the closest sibling: 'Unlike `rego_eval` (single input), `opa exec` processes every file independently.' An agent can distinguish this from the many other eval tools without opening a 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?

Names the alternative (`rego_eval`) and the condition that selects this tool instead ('processes every file independently ... ideal for CI pipelines that check many config files against a policy in one call'). It also gives when-to-use guidance for the gate flags ('Set one of `fail`/`failDefined`/`failNonEmpty` to turn the call into a CI gate').

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral detail about path interpretation: dotted notation versus slash-only separator, and how a key containing a dot can still be addressed. This goes beyond what annotations and schema alone provide.

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 description is three tightly written sentences with no filler. The core action is front-loaded, and the necessary path-format nuances are packed efficiently into the remaining sentences.

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 low-complexity read tool with strong annotations, the description is nearly complete. It covers the trickiest part: path formatting and segments selection. A minor gap is that it does not state what happens when neither `path` nor `segments` is provided, even though the schema allows zero required parameters.

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?

With 100% schema description coverage, the baseline is 3, but the description substantially enriches parameter understanding. It clarifies the dotted-path rule, the slash-only fallback, the `example.com` addressing case, and the exact condition for using `segments` instead of `path`. This resolves real ambiguity in how to invoke the tool.

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 'Read a path from OPA's data hierarchy,' which names a specific verb, resource, and scope. This clearly differentiates it from siblings like opa_get_policy (policies) and opa_query_decision (decision evaluation) by targeting the data hierarchy specifically.

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?

The description gives strong internal guidance on when to use `path` vs `segments`, but it never names alternative tools or states when this tool should be preferred over opa_get_policy or opa_query_decision. Tool-selection context is implied by 'data hierarchy' but not made explicit.

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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar for added context is lower. The description adds real behavior: the tool returns Rego source, omits the AST by default, explains the size tradeoff, and notes the includeAst alternative. No contradiction.

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 sentences, all substantive, with the main purpose in the first clause. No filler or duplication of schema fields.

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 simple one-required-parameter read tool, the description covers what the caller gets (Rego source), the optional behavior (includeAst), and the alternative for AST. Annotations cover safety and idempotency, and schema covers parameters, so nothing essential is missing.

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 100%, so parameters are fully documented; the description adds little beyond what the schema already provides. The mention that AST is omitted 'unless asked for' aligns with includeAst's schema description, so no additional compensation is needed.

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?

Description opens with a specific verb+resource: 'Fetch a single policy by ID from the running OPA server.' It clearly scopes to one policy, distinguishes from list/put/delete siblings, and differentiates from rego_parse_ast by stating this returns Rego source and AST is optional.

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?

Explicitly states that the AST is omitted unless asked and directs the agent to use `rego_parse_ast` when an AST is wanted, giving a concrete when-not. It also implies the primary use case—getting the Rego source for one policy—without ambiguity.

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?

Annotations already cover the safe-read profile (readOnlyHint, idempotentHint, non-destructive), so the description's job was to add behavioral depth beyond that, and it delivers: the exact endpoint, 200-vs-otherwise result semantics, the key gotcha that an unactivated bundle yields { healthy: false } rather than a tool error, and the OPA_UNREACHABLE failure mode. These are precisely the interpretation cues an agent needs and cannot derive from annotations or the schema.

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 sentences, roughly 70 words, with no filler. The endpoint is front-loaded, followed by result interpretation, the unreachable edge case, and finally the flags — a logical order where every sentence earns its place. Nothing is redundant with the schema or annotations.

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 zero-required-param, read-only health check with no output schema, the description is fully sufficient: it names the endpoint, defines both success and failure result shapes, covers the edge cases (unactivated bundle, unreachable server), and documents both optional flags. There is nothing an agent needs in order to call this tool correctly that is missing.

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% — both bundles and plugins already carry adequate descriptions. The description's phrase 'query flags to require those subsystems to also be healthy' adds a small amount of meaning by tying the booleans to the subsystem-health concept, which aligns with and slightly reinforces the schema. Since the schema does the heavy lifting, the 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?

Names the specific resource (`/health` endpoint) with a clear verb ('Hit'), and then defines the expected response semantics. This makes the tool immediately distinguishable from the many siblings in the namespace, especially opa_status and opa_config, without needing to open their schemas.

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?

The description conveys useful context about when to use the tool — checking whether the OPA server (and optionally its subsystems) is healthy — and clarifies that an unactivated bundle appears as a health result rather than a tool error, which affects result interpretation. However, it never explicitly names alternatives or gives when-to-use / when-not-to-use conditions, so routing among overlapping siblings like opa_status and opa_config is left to inference.

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?

Annotations already cover the safety profile comprehensively (readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false), so the bar for the description is lower. The description adds genuine behavioral value beyond annotations by disclosing the response-cap behavior: enabling either include flag can cause list responses to exceed the cap. This is exactly the kind of operational trait an agent needs to anticipate failure modes.

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 sentences, zero filler. The first sentence front-loads the action and return value; the second handles the optional parameters and the reason for the defaults. Every clause earns its place.

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 simple listing tool with 0 required parameters, rich annotations, and no output schema, the description is nearly complete: it states the return value at a useful level ('policy IDs and a count') and explains both flags. It could marginally improve by describing the response envelope or ordering, but nothing an agent needs to invoke it correctly is missing.

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 100% with unusually rich per-parameter descriptions (size ratios, response-cap warnings, alternative-tool routing), which sets the baseline at 3. The description adds meaning on top by distinguishing the two flags at a semantic level — 'Rego text' vs 'parsed AST' — and stating the shared default-off behavior and its rationale, which is not fully redundant with the schema text.

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 a specific verb and resource — 'List policies registered on the running OPA server' — and goes beyond that to specify the return value ('policy IDs and a count'). The phrase 'running OPA server' clearly differentiates this from the many rego_* sibling tools that operate on static policy files, and from opa_get_policy/opa_put_policy/opa_delete_policy which target individual policies.

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?

The description provides clear context: use this to enumerate registered policies, and the optional include flags are discouraged by default because they 'push a list of any real size past the response cap.' This effectively tells an agent when NOT to set the flags. It does not explicitly name opa_get_policy as the alternative for fetching a single policy's source in the description body — that routing lives in the schema — so it stops just short of a 5.

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?

Annotations already indicate this is a destructive, non-idempotent write operation. The description adds useful behavioral context by explaining the operation format and that omitting path and segments patches the root to add a new top-level document. It does not go into further side effects, but the annotation covers the main destructive risk.

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 description is three sentences with no wasted words. It front-loads the core action, then gives the operation shape, then handles the important root-patch special case. Each sentence earns its place.

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 three-parameter tool with annotations covering the destructive nature and a schema covering all parameters, the description provides the remaining key context: how operations are structured and how to target the root. There is no output schema, but return-value details are not critical for invoking this tool correctly.

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 clarifying the JSON Patch operation shape and the special root-patching behavior when both path and segments are omitted. This is meaningful parameter-level guidance an agent would not get from the schema alone.

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 clearly identifies the action: applying an RFC 6902 JSON Patch to the OPA data document. It names a specific verb and resource and is distinct from sibling tools like opa_put_data and opa_delete_data, though it does not explicitly differentiate itself from them in the description.

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?

The description implies when this tool is useful by defining it as the JSON Patch mechanism for data, and it gives a concrete usage tip about omitting path/segments to patch the root. However, it does not explicitly state when to use this tool instead of alternatives such as opa_put_data or opa_delete_data.

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?

Annotations already declare destructive and idempotent hints; the description adds non-obvious runtime behavior: the body is JSON, path separator parsing switches between dots and slashes, and dot-containing keys can be addressed via slash-separated paths. This is meaningful context beyond 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.

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

Every sentence earns its place: purpose, body format, separator rule, and segments fallback. The most important verb-first statement is front-loaded and the paragraph is dense without padding.

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 tricky path-encoding behavior is fully explained, and annotations cover the destructive/idempotent safety profile. There is no output schema and no response description, but for a write operation the essential calling requirements are covered.

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 100%, so baseline is 3, but the description elevates it by explaining how `path` is parsed, why `hosts/example.com` works, and when `segments` is the right parameter. It adds practical meaning not fully present in the schema's field descriptions.

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 a specific action ('Write or replace a value') on a specific resource (OPA data path), which clearly distinguishes it from siblings like opa_patch_data and opa_delete_data. The 'replace' wording communicates full overwrite rather than merge or delete.

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 useful in-tool guidance for choosing path versus segments, but it never addresses when to use opa_put_data instead of opa_patch_data or opa_delete_data. Tool-vs-alternative selection is therefore left mostly implicit.

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?

Annotations already indicate destructive and idempotent behavior. The description adds that the policy is uploaded as raw text/plain and parsed server-side, and that it replaces any existing policy with that ID, providing useful behavioral context beyond annotations.

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 sentences, no redundant information. It is concise and front-loaded with the key action. Could potentially be structured as a brief paragraph but still efficient.

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 mutation tool with no output schema, the description covers core behavior (replace, raw text). However, it does not mention return values or error conditions, which would be helpful for completeness given the tool's destructive nature.

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 descriptions already define 'id' and 'source' adequately. The description adds that the source is raw text/plain, which is helpful but not extensive. With 100% schema coverage, the description does not significantly enhance parameter understanding.

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 clearly states the verb 'Upload' and resource 'Rego policy' with a given ID. It distinguishes from sibling tools like opa_get_policy and opa_delete_policy by specifying the upload/replace action.

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 is provided on when to use this tool versus alternatives such as opa_put_data or opa_bundle_build. There is no mention of prerequisites or context where this tool is preferred.

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?

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds valuable behavioral context by specifying the POST method, the data-path endpoint, and that the response is 'whatever the rule produces'. It does not detail error or undefined-rule behavior, but the annotations lower the burden.

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 description is two sentences with no wasted words. It front-loads the action and endpoint, then gives a concrete example in the second sentence.

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?

Without an output schema, the phrase 'returns whatever the rule produces' gives useful response expectations, and annotations cover the safety profile. The need to provide a path or segments is implied but not explicit, which is a minor gap given the schema hints.

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 schema already documents all five parameters with clear descriptions. The description reinforces the meaning of `path` and `input` through the data.X.allow example, but it does not add significant meaning beyond the schema, so the baseline of 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 a specific verb ('Evaluate'), a specific resource ('the running OPA server'), and the mechanism ('POSTs to the data path'). The quoted example, 'given this input, what does data.X.allow say?', clearly differentiates this from local evaluation siblings like rego_eval.

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 when to use this tool: querying a running OPA server with an input document. It implicitly distinguishes from local rego evaluation tools, but it does not explicitly name alternatives or state when not to use this tool.

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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses meaningful behavioral details: the response reflects startup-reported configuration, includes bundle/decision-log/plugin settings, and service header values are redacted because they may contain API keys. This adds genuine transparency beyond what structured annotations already convey.

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 sentences, each earning its place: the first states the action and endpoint, the second clarifies the difference from a sibling tool, and the third covers response contents and a security-relevant redaction. The description is front-loaded and compact with no 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?

Although there is no output schema, the description compensates by enumerating response categories, clarifying the relationship to opa_config, and warning about redacted header values. For a zero-parameter read-only status tool, this is sufficient context for an agent to invoke it correctly and interpret its result.

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?

There are zero parameters, so schema coverage is complete by definition and the description need not explain parameters. It still adds useful context about what the returned configuration document contains and the redaction policy, which is more than the empty schema provides. Baseline 4 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 opens with a specific verb and resource ('Return the running OPA server configuration via GET /v1/config') and precisely distinguishes this tool from its sibling opa_config by noting the 'status' key presentation and the intent to check 'what is running' vs 'what was configured'. This gives an agent a clear, unambiguous purpose.

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?

The description explicitly names the alternative tool opa_config and states the selection criterion: use this when the agent wants 'what is running' rather than 'what was the server configured with'. This is direct routing guidance with no ambiguity about when to prefer this tool.

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?

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description carries most of the behavioral load. It discloses the underlying mechanism (`opa bench`) and the shape of the result (iterations, ns/op, allocation counts), which is genuinely useful for an agent that has no output schema. It does not mention execution cost, timeouts, or the fact that benchmarking repeatedly executes the policy.

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 sentences that are front-loaded with the action, then the return shape, then the reason to use it. No filler and nothing repeated from the schema.

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?

No output schema exists, so the description must say something about returns, and it does summarize the statistical fields. The count>1 behavior (runs/fastest, omitted raw) is only explained in the schema's count parameter, leaving the description slightly thin for an agent sizing up results.

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% across all six parameters, so the schema already documents query, input, paths, count, inputPath, and v0Compatible in detail. The description adds no parameter-level meaning beyond what the schema supplies, which is the baseline-3 case.

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 (benchmark) and resource (a Rego query against a policy + input), names the underlying command (`opa bench`), and reports what comes back (iterations, ns/op, allocation counts). It does not explicitly name the nearest sibling (rego_eval_with_profile), so an agent must infer the distinction itself.

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?

"Use this to spot slow rules" gives a motivating use case, which implies the performance-investigation context. There is no explicit when-not guidance and no mention of alternatives such as rego_eval_with_profile, so the agent must decide between them on its own.

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?

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds genuinely useful behavior beyond that: the default behavior (`names_only: true`), the response-size limitation rationale, the need to raise OPA_MCP_MAX_RESPONSE_BYTES for full records, and the OUTPUT_TOO_LARGE risk implied by the schema. Nothing contradicts 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.

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

The description is front-loaded with the core purpose and then progresses logically through parameter modes, defaults, and caveats. Every sentence carries distinct information, and the length is justified by the four-parameter mode matrix. There is no filler or redundant restatement of the title.

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?

Given there is no output schema, the description carries the burden of return-value clarity and does it well: it names the returned categories, explains the `count` and `matched`/`missing` behavior via the schema's `builtins` description, and warns about response-size limits. Minor gap: it does not describe the exact JSON shape of the non-builtin sections (e.g., fields for future keywords/features/WASM versions), but enough is stated for an agent to select and invoke the tool correctly.

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 100%, so the baseline is 3, but the description adds value beyond the schema by explaining the parameter interplay: the mutual exclusivity implied for `current`/`version`, the effect of omitting both, and the relationship between `builtins` and `names_only`. The schema already contains detailed per-parameter text, so the description does not need to repeat it all.

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: 'Return OPA capabilities' and enumerates exactly what is included ('available builtins, future keywords, features, and WASM ABI versions'). This clearly distinguishes it from the rego evaluation/parsing siblings, which operate on policies rather than OPA runtime capability metadata.

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?

The description gives strong conditional guidance for each invocation mode ('With current: true...', 'With version: "v1.19.0"...', 'With neither...') and explains when to use `builtins` vs `names_only: false` based on response-size constraints. It does not explicitly name sibling alternatives, but no sibling tool offers this capability, so the mode-level guidance effectively covers when to use the tool.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real value beyond that: it documents the return shape ('{ valid: true, errors: [] }') and the failure mode (structured diagnostics with file/line locations), which matters given no output schema exists.

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 tight sentences with the core action, the return contract, and the input-mode choice front-loaded in that order. No filler or restated boilerplate.

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, the description correctly supplies the return contract, and annotations cover the safety profile while the schema covers all parameters. It is nearly complete; only the lack of sibling routing (check vs lint) leaves a minor gap.

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 every one of the 8 parameters is already documented in the schema, setting the baseline at 3. The description's only parameter-level addition is the source/paths mutual exclusivity, which the schema already states, so it adds little beyond the structured fields.

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 and resource ('Type-check Rego with `opa check`') plus the exact underlying command, which lets an agent separate it from rego_lint and rego_parse_ast. It does not explicitly name or contrast those siblings, so it falls short of full differentiation.

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?

The description conveys the source-vs-paths usage pattern ('Provide either `source` for inline checking or `paths` for file/directory checking'), which is useful. However, it gives no guidance on when to reach for rego_check versus rego_lint, rego_compile_query, or rego_migrate_v1, so usage is only implied by the verb.

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?

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), and the description adds real value: it names the failure mode (rego_type_error diagnostics with file/line), and gives the exact return shape `{valid, errors}`. It doesn't discuss rate limits or path-root rejection errors beyond what the schema already says.

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?

Dense but well ordered: purpose first, then diagnostic/return behavior, then the schema-input modes, then source-vs-paths. Every sentence carries information, though the final sentence slightly stacks multiple mode descriptions.

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 6-parameter, nested-object tool with no output schema, the description supplies the return contract and mode semantics the agent needs. Minor gaps remain around ordering when both none of source/paths are supplied, but overall it is complete enough to invoke correctly.

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 100%, so the baseline is 3, but the description adds integration meaning beyond the schema: it tells the agent it can pass `rego_infer_input_schema`'s `schema` output straight through as `inlineSchema`, and clarifies the directory-vs-file semantics of `schemaPath`.

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+mechanism: validate a Rego policy's `input.*` references against a JSON Schema via `opa check --schema`. This clearly distinguishes it from siblings like rego_check, rego_lint, and rego_infer_input_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?

Explains the two schema-input modes (inline via rego_infer_input_schema output, or path/directory) and the source-vs-paths choice, giving clear usage context. It does not, however, explicitly state when to prefer this over rego_check or rego_verify, so no full when-not framing.

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?

Annotations declare readOnlyHint=false and openWorldHint=true; the description goes beyond them by disclosing the default of `unknowns` (`["input"]`) and the meaning of the residual output. It does not address the surprising non-read-only annotation for what reads as a pure computation, but it adds genuine behavioral context.

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 sentences, front-loaded with the core operation and followed immediately by the key default and the intended use case. No filler; every clause carries information.

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 9 params, 100% schema coverage and no output schema, the description covers purpose, the critical default, and the use case well. Return values are described only at a high level ('residual policy'), which is acceptable given the absence of an output schema.

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 100%, so the baseline is 3. The description adds value the schema does not: the default value and interpretation of `unknowns` and what the residual encodes, which is the single most important parameter behavior for this tool.

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 a precise operation ('Run partial evaluation on a query'), explains the mechanic (substitute known values, return the residual policy), and contrasts implicitly with plain evaluation via the `partial` semantics. It does not explicitly name a sibling (e.g. rego_eval or opa_compile_query), so the agent must infer differentiation.

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 concrete use cases -- 'offline policy slicing or pre-computing decision sets' -- which is clear when-to-use guidance. It stops short of stating when NOT to use it or naming an alternative evaluation tool, so it is not a 5.

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?

Annotations declare readOnlyHint=false and openWorldHint=true, so the safety profile is at least partly covered. The description adds useful behavioral detail (per-file breakdown, ascending sort order) but says nothing about cost, side effects of executing test code, or prerequisite test files, which matters given readOnlyHint=false.

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?

Four tight sentences, front-loaded with the core action and outcome, then sort behavior and the threshold hint. No filler or redundancy, though the last sentence slightly duplicates the schema's threshold text.

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, the description does its job by characterizing the return value (per-file uncovered line ranges, sorted worst-first). It omits what happens when no tests exist or when paths contain no matching *_test.rego files, but it is otherwise sufficient for correct invocation.

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 schema already documents all four parameters, including threshold and v0Compatible. The description restates threshold semantics and the sort behavior but adds no format, syntax, or edge-case detail beyond what the schema provides. Baseline 3 applies.

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 and resource: runs `opa test --coverage` and returns per-file uncovered line ranges, identifying unexercised rules/branches. Clear to an agent. However, it never distinguishes itself from close siblings like rego_test or rego_eval_with_coverage, leaving differentiation implicit.

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?

The only usage guidance is 'Use threshold to limit the report to files below a target coverage percentage', which is parameter mechanics rather than when-to-use. There is no statement of when to pick this over rego_test, rego_test_multiroot, or rego_eval_with_coverage, so selection is left to inference.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's mention of 'static analysis' adds context but does not disclose additional behavioral traits like performance or side effects beyond what annotations provide.

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 description is a single, well-structured sentence that front-loads the purpose and key details. No redundant information.

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?

Despite no output schema, the description explains what the tool returns (base and virtual document references, transitively). It covers purpose, parameters, and output sufficiently for a static analysis tool.

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 100%, baseline 3. The description adds meaning by explaining the ref format (e.g., 'data.example.allow') and the paths constraint (must be inside allowed root), which adds value beyond the schema descriptions.

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 clearly states the tool performs static dependency analysis for a Rego reference, specifying the target ref format and what it returns (base and virtual document references). This distinguishes it from sibling tools like rego_check or rego_eval.

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?

The description implies usage for dependency analysis but does not explicitly state when to use this tool versus alternatives like rego_eval or rego_explain_decision. No when-not or alternative guidance is provided.

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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds valuable context by spelling out the exact report structure (clauseCount, isDefault, hasArgs, bodyLength, inline annotations). It does not mention error behavior for malformed source, a minor gap.

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 front-loaded sentences: purpose first, then return-field detail, then a usage cue. The field enumeration is dense but each clause earns its place by clarifying output for a tool without an output schema.

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, the description usefully documents return shape and both parameters are covered by the schema, so an agent has enough to call it correctly. It lacks explicit sibling routing, which is the main missing piece.

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; both `source` and the rich `v0Compatible` explanation are already fully documented in the schema, and the description adds no additional parameter meaning.

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 (describe/parse) and resource (Rego policy), then enumerates the returned summary fields (package, imports, rules, clauseCount, isDefault, hasArgs, bodyLength). It is unambiguous what it does, though it does not explicitly contrast itself with near-siblings like rego_parse_ast or rego_inspect.

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?

"Useful as the first step in any 'what does this policy do' workflow" implies a usage context, but there are no explicit when-to-use/when-not conditions or named alternatives among the many sibling analysis tools (rego_inspect, rego_parse_ast, rego_check).

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?

Annotations declare readOnlyHint=false and openWorldHint=true, so the safety profile is partially covered; the description adds real value beyond them by disclosing the return shape (`{result: [...]}`), the pre-1.0 Rego compatibility path, and the fact that a query can run with no policy at all. It does not restate or contradict 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.

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

Four compact sentences, front-loaded with what the tool does and the return shape before the optional-parameter notes. The colloquial "bread-and-butter authoring tool" is a slight indulgence but it conveys routing value cheaply.

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 10-parameter tool with no output schema, the description usefully supplies the return shape and the headline behaviors, so the essentials an agent needs to call it are present. What is missing is disambiguation from the large cluster of near-identical eval/query siblings, which the description never addresses.

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 schema already documents all 10 parameters thoroughly, including the batch semantics of `inputs` and the v0 rationale for `v0Compatible`. The description's parameter remarks (policy optional, `inputs` for many documents, `v0Compatible` for pre-1.0 policies) largely duplicate the schema text, 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?

States a specific verb and resource ("Evaluate a Rego query against a policy and an input document using `opa eval`") and calls itself the "bread-and-butter authoring tool," which positions it as the default entry point. It never names a specific sibling (rego_eval_with_explain, rego_eval_with_profile, rego_eval_with_coverage, opa_query_decision), so an agent must infer the distinction from the surrounding tool list.

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 implied usage context: policy is optional so a bare query works for built-ins/expressions, and `inputs` enables batching one query against many documents. There are no exclusions and no explicit routing to the decorated eval variants (explain/profile/coverage) that share almost the same job, which is the main decision an agent faces here.

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?

Annotations give only readOnlyHint=false and openWorldHint=true, so the description carries most of the behavioral burden. It discloses the return content (per-line coverage data), which is genuinely useful without an output schema, but says nothing about cost, performance, or what happens under partial evaluation. Notably readOnlyHint=false for an eval tool is odd, though the description neither confirms nor contradicts 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?

Two tight sentences with the distinguishing behavior (coverage) front-loaded and the rationale following. Zero wasted words.

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 nine parameters, sparse annotations, and no output schema, the description is thin for a tool whose headline output is coverage data. It states that per-line coverage is returned but does not characterize that shape or note anything about partial/unknowns interaction, leaving the schema and agent inference to fill sizable gaps.

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 schema already documents all nine parameters, including partial/unknowns and v0Compatible in notable detail. The description adds only the implicit `--coverage` flag mapping and no syntax or format guidance beyond the schema, so baseline 3 applies.

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: 'Evaluate with `--coverage` and return per-line coverage data.' This clearly separates it from the plain `rego_eval` and from the explain/profile variants. It never names a sibling explicitly, but the coverage framing is distinctive enough for an agent to select it.

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?

Provides an implied when-to-use: 'verifying that tests actually exercise the rules they're meant to.' That is real context, but there is no when-not guidance and no routing to related siblings like rego_coverage_gaps, rego_test, or rego_eval_with_explain.

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?

Annotations only cover readOnlyHint=false and openWorldHint=true, so the description's disclosure that this runs with full explain mode and returns a trace alongside the result is meaningful added context. It doesn't describe trace verbosity/size or how the trace is structured, but the core behavioral trait is surfaced.

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 tightly written sentences with the core action front-loaded and no filler. The chained-tool note is brief and earns its place as routing context.

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 9-parameter evaluation tool with no output schema, the description conveys the essential behavior (trace returned with result) and the workflow purpose. It could say more about what the returned trace contains, since no output schema exists to compensate, but it is sufficient to call the tool correctly.

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 all nine parameters (including the `--explain`-relevant ones like `partial`, `unknowns`, `v0Compatible`) are already documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, which is the expected baseline.

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 and resource (evaluate Rego with `--explain=full` returning a structured trace) and names the differentiator versus plain evaluation. It also positions the tool relative to a sibling (`rego_explain_decision`), so an agent can distinguish it without opening any 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?

"Use this when an agent needs to see why a rule fired (or didn't)" is an explicit, actionable trigger condition, and it hints at the downstream relationship with `rego_explain_decision`. It stops short of stating when to prefer plain `rego_eval` over this costlier variant (e.g. when no explanation is needed), so no exclusions are given.

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?

Annotations declare readOnlyHint=false and openWorldHint=true, and the description does not contradict them. It adds useful behavioral context by stating the output shape (per-rule timing and evaluation counts) rather than a plain decision result. It does not mention cost/overhead of profiling, path-root restrictions, or interplay with partial evaluation.

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 sentences with zero filler; the capability is front-loaded and the usage hint follows. Nothing could be removed without losing information.

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 9-parameter tool with no output schema, the description discloses what profiling returns (timings plus counts) and when to reach for it, which covers the main gaps. It omits return-format specifics and any caveat about profiling cost, so it is good but not fully complete.

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% across all 9 parameters, so the schema already carries parameter meaning. The description adds no parameter-level detail (e.g. that profiling is meaningless without paths/source). Baseline 3 applies when the schema does the heavy lifting.

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 (evaluate) plus the distinguishing artifact: `--profile` mode returning per-rule timing and evaluation counts. This differentiates it from plain rego_eval and from the explain/coverage variants without naming them explicitly. It is clear but stops short of sibling-level routing.

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?

"Use this to find hot rules in slow policies" gives a genuine use case, so usage is more than merely implied. However, it names no alternative and gives no exclusions, which matters here because rego_eval, rego_eval_with_explain, rego_eval_with_coverage and rego_bench all overlap and an agent must choose among them.

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?

Adds genuine context beyond annotations by describing the return shape and the intended agent workflow (read trace, narrate cause, no custom parser). With annotations limited to readOnlyHint=false/openWorldHint=true, it still omits any disclosure of tracing cost, side effects, or why the call is flagged non-read-only.

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 well-formed sentences, front-loaded with what the tool does followed by when to use it. No filler; only lightly redundant restatement of the output in the second clause.

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 9-parameter, no-output-schema tool, the description compensates by naming the return contents (structured trace, per-rule fired/not-fired summary) and the intended usage. Behavioral specifics like tracing performance and the non-read-only flag remain unaddressed, keeping it short of full completeness.

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 schema already documents all 9 parameters (v0Compatible, partial, unknowns, etc.). The description adds no format/syntax detail beyond the schema, so the baseline of 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?

States a specific verb+resource (evaluate a Rego query with full tracing) and its distinctive output (structured trace + per-rule fired/not-fired summary), which separates it from plain rego_eval. It does not, however, name the close siblings (rego_eval_with_explain, rego_explain_undefined) that an agent must choose between.

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?

Provides a clear motivating scenario ('why was this denied?'), which implies when to reach for it. But it gives no explicit exclusions or alternatives, and with near-identical siblings like rego_eval_with_explain and rego_explain_undefined present, the agent is left to 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 annotations marking this readOnlyHint=false and openWorldHint=true, the bar is lower, and the description adds real context: it combines three analysis passes, covers both runtime failures (trace-based) and indexer elimination (standalone condition eval), and explains how `default` rules are reported via `queryResult`. It also states the return shape (structured breakdown plus a human-readable summary), which matters because there is no output schema. It does not explain why the tool is flagged non-read-only, a minor omission.

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 purpose and mechanism, and most sentences carry information. The middle sentence about `default allow := false` and `queryResult` is convoluted and ends on a tautology ('the question ... is the question this answers'), which is the one place that does not earn its space.

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 6-parameter diagnostic tool with no output schema, the description does the necessary work: it explains the two failure classes handled and summarizes the return payload. It stops short of describing behavior when the query is actually defined (does it error, return empty, or succeed silently), which an agent would want to know before calling.

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% and the description largely restates it (fully-qualified query, defaults, v0 compatibility is covered in the schema). It adds only marginal param meaning, e.g. the requirement that the query path match what you would pass to rego_eval. Baseline 3 is correct when the schema carries the documentation burden.

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 a specific verb (diagnose/explain) and a precise resource/scope: a fully-qualified Rego query that produces no value or falls back to a default. It further distinguishes the scenario from a generic eval by describing the mechanism (plain eval + full-trace + per-condition AST analysis). It does not, however, name the nearby siblings it must be distinguished from (rego_eval_with_explain, rego_explain_decision), so an agent must infer the boundary.

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 implied rather than stated: the tool is for the case where a query is undefined or returns a default. There is no explicit 'when not to use this' or a named alternative such as rego_eval or rego_explain_decision for the case where the query does produce a value. The awkward restatement that 'why is allow false' is the question this answers adds scenario color but not routing guidance.

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?

Annotations already flag destructive behavior; the description adds crucial specifics: directory-package-mismatch moves files, Regal before 0.41 refuses uncommitted changes unless force:true, and regal must be installed. No contradiction with annotations.

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?

Dense but well-structured: main action first, then rule list, then critical safety caveats. Every sentence adds necessary information; the directory-package-mismatch warning is essential for a destructive tool.

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 destructive tool with 9 parameters and no output schema, the description covers the key behavioral caveats (file moves, git check, dryRun preview, regal requirement). It doesn't explain return values, but that's not critical for a fix command, and the schema handles parameter details.

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 covers all 9 parameters at 100%, so baseline is 3. The description adds value by explaining the behavior behind dryRun, disable, and force in context (preview, skip file moves, version-specific git check), going beyond the schema's per-parameter descriptions.

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 the exact command ('Run regal fix') and the resource ('Rego violations') with a specific list of mechanical fixes. The title and description together make it clear this applies fixes rather than just reporting them, distinguishing it from rego_lint and rego_format.

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?

Provides clear operational guidance: dryRun for preview, disable for directory-package-mismatch, force for older Regal. It does not explicitly name sibling alternatives or state when not to use it, but the context is strong.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context by explaining the `changed` flag and the OPA v1.12.0/v1.12.1 bug warning/blocking behavior. The phrase 'warns about or blocks' is slightly ambiguous, but it still discloses an important edge case beyond 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.

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

The description is two sentences with no filler. It front-loads the core purpose, then covers return behavior and the notable OPA bug edge case. Every sentence earns its place.

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 description explains the return value (`formatted source` and `changed` flag) and the important version-specific bug behavior, which is sufficient for most calls. It is slightly incomplete because it does not clarify the distinction from `rego_format_write` and leaves the warn-vs-block behavior ambiguous, but overall it covers the key operational details.

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 schema already documents both `source` and `v0Compatible` clearly. The tool description adds no additional parameter-level meaning beyond what the schema provides, so the baseline score of 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 clearly states the tool formats Rego source code using `opa fmt` and returns the formatted source plus a `changed` flag. This is a specific verb+resource and is easy to understand, but it does not explicitly distinguish itself from the sibling `rego_format_write` or other formatting-related tools.

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?

The description implies usage for formatting Rego source, and the `v0Compatible` parameter description explicitly routes conversion to Rego v1 to `rego_migrate_v1`. However, there is no general guidance on when to choose this tool over `rego_format_write`, `rego_fix`, or other alternatives, so usage context is only partially addressed.

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?

Annotations declare destructiveHint=true and idempotentHint=true. Description adds details: writes to disk, dryRun preview, abort on parse failure. No contradiction.

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?

Concise, front-loaded with main action, then key features (dryRun, return value, sibling differentiation, flags, error behavior). Every sentence adds value.

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 mutation tool with 5 params and no output schema, description covers return format, error behavior, version flags, and safety. Could mention idempotency or permissions, but redundant with annotations.

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 100%. Description adds meaning: paths must be within allowed root, dryRun for preview, regoV1 adds import rego.v1, v0Compatible/v1Compatible for version-specific formatting.

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?

Clearly states the tool runs `opa fmt --write` to format Rego files in place. Distinguishes from sibling `rego_format` by noting this writes to disk vs returning a string. Lists version flags.

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?

Explicitly recommends using `dryRun: true` for preview and distinguishes from `rego_format`. Mentions abort on parse failure. Could explicitly state when not to use, but differentiation is sufficient.

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?

Annotations already declare readOnly/idempotent/non-destructive, yet the description goes well beyond them: it discloses stub-skipping semantics, the `todo_test_` -> `test_` rename workflow and how `opa test` reports it as skipped, AST-based `input.*` inference feeding the `with input as {...}` placeholder, and the response's `inferredInputShape` field. This is rich behavioral context an agent cannot get from structured fields.

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 purpose, then layers on skip behavior, input-shape inference, tableStyle, and the response field. It is dense but every sentence carries distinct information; slightly long but no obvious 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?

No output schema exists, yet the description names the relevant return field (`inferredInputShape`) and explains the generated artifact's structure. For a read-only generator with three fully-described params, nothing an agent needs to call it correctly is missing.

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 100%, so baseline is 3, but the description adds real meaning: `tableStyle` is explained as an `every tc in cases { ... }` loop with a cross-reference to `rego_test varValues: true`, and `v0Compatible` semantics (stubs still emit `import rego.v1`) are clarified. It adds value beyond the schema's parameter list.

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 and artifact ('Generate a `*_test.rego` skeleton from a policy') and immediately scopes it against sibling tools by describing what is generated (stub tests per non-test rule) versus run. An agent can distinguish it from rego_test/rego_test_multiroot without opening a 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?

Clearly describes the generation context (skips existing `test_*`/`todo_test_*` rules, emits `todo_test_` for computed-head value rules) and explains when to use `tableStyle` (multiple input/expected pairs). It does not explicitly name alternative sibling tools or state exclusions, so it stops short of a 5.

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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description usefully adds behavioural context beyond that: analysis is AST-level via `opa parse` with no running OPA server required (a real differentiator from opa_exec-style tools), and input may be inline source, individual files, or recursively walked directories. It omits failure behaviour on malformed Rego and any path-root error handling.

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?

Four sentences, front-loaded with the core verb-resource-output and then the usage guidance and input modes; nothing is padding. Slightly dense -- the usage sentence could be trimmed -- but every clause contributes.

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, the description correctly carries the return-value burden by specifying a draft-07 JSON Schema describing every input.* field read. Combined with the input-mode coverage and the existing annotations, an agent has everything needed to invoke this correctly.

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 schema already documents `paths`, `source`, and the fairly intricate `v0Compatible` flag. The description restates the source/file/directory modes but adds no detail the schema lacks, and never mentions v0Compatible. Baseline 3 is appropriate when structured fields carry the load.

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 (statically analyse), resource (one or more Rego policies), and output (a draft-07 JSON Schema of every input.* field read). That output framing separates it from near-siblings like rego_check_schema (validates against a schema), rego_parse_ast (returns an AST), and rego_inspect, so an agent can route without opening any 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?

Names three concrete downstream uses -- writing integration tests, configuring `opa check --schema`, documenting a policy API -- which tells the agent when this is the right starting point. It stops short of explicit exclusions or naming the sibling to prefer when you already have a schema and only want validation (rego_check_schema), so it is clear context rather than full when/when-not guidance.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the actual return content (manifest data, namespaces, rule annotations, signature metadata if signed), which no annotation or output schema provides. It does not mention errors on unreadable paths, but that gap is minor for an inspection 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?

Two compact sentences with zero filler: the first names the action and accepted inputs, the second enumerates the outputs. Everything is front-loaded and each clause earns its place.

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, annotation-covered read tool with no output schema, the description supplies the missing return-value information an agent would otherwise lack. The only shortfall is the absence of when-to-use guidance relative to the many sibling inspection/parsing tools.

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%: both `target` and `v0Compatible` are thoroughly documented in the schema, including the v0 syntax details. The description adds no parameter-level meaning beyond what the schema already carries, so the baseline 3 applies.

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 (inspect) plus the exact resources it accepts (bundle archive, policy directory, single Rego file) and the underlying command (`opa inspect`). It also enumerates the returned artifacts (manifest, namespaces, rule annotations, signature metadata), which distinguishes it from siblings like rego_deps, rego_describe_policy, and opa_list_policies.

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?

The description never says when to choose this over alternatives such as rego_deps, rego_describe_policy, or rego_parse_ast. It only states what the tool does, leaving the selection decision entirely to the agent.

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?

The description goes well beyond annotations. It discloses the external dependency (`regal` on PATH or `REGAL_BINARY`), the failure mode (`REGAL_NOT_FOUND`), the auto-disabling of path-dependent rules for inline source, and the `<inline>` path substitution. This is excellent behavioral disclosure that cannot be inferred from the schema. The `readOnlyHint: false` is consistent with a lint operation that launches an external process; no contradiction.

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 description is compact and information-dense. The first sentence states the core purpose; the second covers dependencies and failure modes; the third explains conditional behavior for inline source. It is front-loaded and every sentence earns its place. A small deduction because the inline-source caveat is long and could be trimmed.

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 description covers return categories, dependency requirements, inline-source behavior, and path handling. With 9 parameters and no output schema, the remaining gap is the exact shape of the returned violation objects (e.g., severity codes, rule IDs). Still, for an agent choosing and invoking the tool, the most important operational details are present. Could mention that `paths` must be within allowed roots, but that is already in the schema.

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 100%, so every parameter already has a description in the schema. The tool description does not repeat parameter details, which is appropriate. However, it also doesn't add semantic context about how `enable`/`disable`/`enableCategory`/`disableCategory` interact or how `failLevel` maps to exit codes beyond what the schema already says. Baseline 3 is fair because the schema carries the load.

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 ('Lint'), a specific resource ('Rego source'), and names the actual linter ('Regal'). It also specifies returns 'categorized violations (style, bugs, idiomatic, performance) with file/line locations', which distinguishes it from other rego_* tools that analyze, transform, or evaluate Rego.

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?

The description clearly explains how to invoke it with `paths` or inline `source`, and notes the behavior difference for the inline case. It doesn't explicitly spell out 'use X instead when...' alternatives, but the sibling list is large and the description's focus on inline-source behavioral detail implies the relevant context. Slight gap: no explicit statement about when to prefer rego_check, rego_fix, or rego_security_audit over this linter.

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