[docs-scanner] Confusing explanation of approval-required outcome vs permit in MCP policy #26560

File: content/manuals/ai/governance/reference/mcp-policy.md

Issue

The "Approval annotation" section states:

An approval-required outcome takes precedence over a normal permit.

This phrasing is confusing because an approval-required outcome IS a type of permit (specifically, a permit with the @requireApproval annotation). The statement makes it sound like there are two separate, competing outcomes when in fact the approval-required outcome is just a modified permit.

Why this matters

Readers trying to understand the evaluation model will be confused about whether approval-required is a distinct decision type or a variant of permit. The current phrasing suggests they're different things that can conflict, when actually an annotated permit simply requires an extra step before allowing the request.

Suggested fix

Rewrite to clarify the relationship. For example:

When a request matches a permit annotated with @requireApproval and no forbid overrides it, the policy engine returns an approval-required outcome instead of immediately allowing the request. The annotation string is shown as the elicitation reason.

Or:

A permit with @requireApproval requires user confirmation before allowing the request. This approval-required behavior takes precedence over a plain permit without the annotation.

Found by nightly documentation quality scanner