[docs-scanner] Confusing explanation of approval-required outcome vs permit in MCP policy
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Newbie friendliness
- 88/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Domain
- documentation
Research direction
Open content/manuals/ai/governance/reference/mcp-policy.md and read the “Approval annotation” section. Clarify that @requireApproval annotates a permit and requires confirmation before allowing the request; keep the wording consistent with the policy behavior described there. Done when readers can tell an approval-required outcome is an annotated permit, not a separate competing outcome.
Written by the indexing model from the issue text.
Description
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
permitannotated with@requireApprovaland noforbidoverrides 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
permitwith@requireApprovalrequires user confirmation before allowing the request. This approval-required behavior takes precedence over a plainpermitwithout the annotation.
Found by nightly documentation quality scanner
- Dominant language
- Markdown
- Stars
- 4.7k
- Forks
- 8.5k
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 139
Getting set up
- Ships a Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from docker/docs
-
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
Maintainers usually reply within 1 day
-
status/triage
Difficulty 1/5 Under an hour Newbie friendliness 68/100
Maintainers usually reply within 1 day
-
[docs-scanner] Unclear policy change timing in organization policies overviewPossibly taken @Mhdomer claimed this today. Open
Difficulty 1/5 1-3 hours Newbie friendliness 89/100
Maintainers usually reply within 1 day
-
[docs-scanner] Unclear pronoun reference in cloud delivery notePossibly taken @craig-osterhout claimed this 1 day ago. Open
Difficulty 1/5 Under an hour Newbie friendliness 94/100
docker/docs#26547 · 1 assignee ·
Maintainers usually reply within 1 day
-
Debian installation pitfallPossibly taken @Duo-ee claimed this 7 days ago. Openstatus/triage
Difficulty 1/5 Under an hour Newbie friendliness 85/100
Maintainers usually reply within 1 day
Similar issues
-
Blog update untriaged
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
-
sync-en
Difficulty 1/5 1-3 hours Newbie friendliness 84/100
Maintainers usually reply within 1 day
-
sync-en
Difficulty 1/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 88/100
-
Difficulty 1/5 Under an hour Newbie friendliness 83/100
GSA/digital-gov-drupal#569 ·
Maintainers usually reply within 2 days