[docs-scanner] Contradictory information about MCP approval fields in audit records

Open Beginner friendly
  • Is something wrong?
#26,559 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
88/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
markdown
Domain
documentation

Research direction

Read content/manuals/ai/governance/reference/audit-records.md, focusing on the “Approval fields” section and its table. Clarify which fields apply to network approvals and which apply to MCP approvals, keeping the descriptions consistent with the prose. Done means readers can tell which fields to expect for each approval type.

Written by the indexing model from the issue text.

Description

File: content/manuals/ai/governance/reference/audit-records.md

Issue

The "Approval fields" section contains contradictory information about which fields appear in MCP approval records. The prose states:

For MCP approvals, an approved request is evaluated again and recorded with AUDIT_DECISION_APPROVAL_ALLOW, and a declined request is recorded with AUDIT_DECISION_APPROVAL_DENY. Neither record includes approval.approval_request_id or approval.grant_scope.

However, the table immediately below lists:

Field Description
approval.approval_request_id ID that links an approval required record to the record that resolves it.
approval.grant_scope Scope the user accepted. Present only on AUDIT_DECISION_APPROVAL_ALLOW records.

The table descriptions don't distinguish between network and MCP approvals, suggesting these fields are present on all AUDIT_DECISION_APPROVAL_ALLOW records, which contradicts the prose statement that MCP approvals don't include them.

Why this matters

A reader trying to parse MCP approval audit records will be confused about which fields to expect. If they follow the prose, they won't look for these fields. If they follow the table, they'll expect them to be present. This makes it impossible to correctly process MCP approval records.

Suggested fix

Clarify the table to indicate which fields apply to network approvals vs. MCP approvals. For example:

Field Description
approval.approval_request_id ID that links an approval required record to the record that resolves it. Present for network approvals only.
approval.grant_scope Scope the user accepted. Present only on network approval AUDIT_DECISION_APPROVAL_ALLOW records.

Or restructure the section to have separate subsections for network approval fields and MCP approval fields.

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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from docker/docs

All issues in docker/docs

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.