Authored by Claude Opus 4.7 (Claude Code). Session 48197e2e-3e95-47eb-9eb8-bbb032948845 consuming handoff from session b5a17132-7324-46e1-b73e-038825bb4d55 (same model, prior session).

Resolves #10341

Summary

Codifies a new §5.3 MCP-Tool-Description Budget Audit step in the pr-review skill, parallel to §5.2 Close-Target Audit. Reviewer-side discipline that catches bloated OpenAPI tool descriptions at review time, before they enter the runtime tool-surface payload.

OpenAPI tool-parameter descriptions in ai/mcp/server/*/openapi.yaml are loaded into every consuming agent's context window when the tool surface is enumerated. Bloat on a single param multiplies across ~80 MCP tools across every agent session — meaningful context-window pressure that competes with the actual reasoning budget. The principle was implicit; codifying it as an audit step prevents recurrence.

Changes

• .agent/skills/pr-review/references/pr-review-guide.md — added §5.3 MCP-Tool-Description Budget Audit with: rule statement + three-audiences/three-budgets table (OpenAPI vs JSDoc vs PR body), trigger conditions, audit checks (single-line preferred, no internal cross-refs, no architectural narrative, external standard URLs OK, 1024-char hard cap), Required Action template, author response options, distinction-from-JSDoc clause, empirical anchor citing PR #10340, out-of-scope clauses. Plus one anti-pattern row in §7.4.
• .agent/skills/pr-review/assets/pr-review-template.md — added 📡 MCP-Tool-Description Budget Audit section between Close-Target Audit and Cross-Skill Integration Audit, structured as a 5-item checklist matching the audit checks.

Net: 67 lines across 2 files. No code changes.

Empirical Anchor (Verified Against Merged State)

PR #10340's initial task parameter description on mailbox/messages was a ~600-char block-literal with internal Phase 1/Phase 2 framing and ticket cross-refs (#10334/#10313/#10338). @tobiu's cycle 1 challenge — "these directly map to mcp server tools — they must be short and meaningful" — tightened it to a ~155-char single-line description in one follow-up commit.

Verified: the merged state (commit dace09f49) shows:

`Optional A2A Task envelope (https://a2a-protocol.org/latest/specification/) for structured agent coordination. Omit for free-form markdown messages.`

4× reduction with no information loss for the consuming agent.

Deltas from Ticket

• Adjacent-but-distinct framing for PR #10342 — the ticket's handover comment claimed §5.3 would catch PR #10342's newState enum bug (IN_PROGRESS, COMPLETED, BLOCKED vs actual Submitted, Working, …, Blocked) and expectedCurrentState required-vs-optional drift. Honest scoping: those are CONTRACT-CORRECTNESS bugs, not BUDGET bugs. The §5.3 audit checks (single-line, no narrative, char-cap) wouldn't surface them. Out-of-scope clause now explicitly flags "OpenAPI/JS contract drift" as adjacent territory warranting separate codification if recurrent — preserving §5.3's tight budget-focused scope while acknowledging the related discipline gap.
• No memory-anchor names in skill file — the ticket AC requested cross-references to feedback_mcp_output_category_split etc. Per substrate-awareness discipline (pull-request §11), harness-private memory file names don't appear in public skill artifacts; the conceptual principles they encode are what's codified. Memory anchors stay in the PR body / commit narrative for provenance.

Test Evidence

Pure markdown documentation; no runtime test surface. Manual verification:

• `grep -n '^### 5.3|MCP-Tool-Description Budget' pr-review-guide.md` → §5.3 at line 118, anti-pattern row at line 231.
• Empirical anchor verified against merged state of `ai/mcp/server/memory-core/openapi.yaml` for both #10340 (task param) and #10342 (newState + expectedCurrentState).
• Template diff inspected — new section sits between Close-Target Audit and Cross-Skill Integration Audit, mirrors §5.2's checkbox pattern.

Cross-Skill Integration Audit (Self-Applied per §8.1)

• No predecessor skill needs to fire §5.3 — it's a reviewer-side audit, only invoked when the pr-review skill is loaded for a PR.
• AGENTS_STARTUP.md §9 entry for pr-review lists high-level capabilities ("structured evaluation metrics, graph ingestion tags, severity ladder"); §5.1/§5.2 sub-audits aren't enumerated there either, so adding §5.3 doesn't surface a new top-level capability worth listing. No update needed.
• No reference file mentions a predecessor pattern to update.
• No new MCP tool surface introduced.
• New convention is documented in-place in pr-review-guide.md §5.3 and the template — discoverable via the skill load-path.

Post-Merge Validation

• Future PRs touching ai/mcp/server/*/openapi.yaml get §5.3 audit coverage in cross-family review.
• Reviewer-side discipline catches description bloat pre-Approval rather than post-Approval (the failure mode that gave rise to this ticket).

Cross-Family Review Request

Per pull-request §6.1 cross-family mandate. Requesting review from @neo-gemini-pro.

Related

• PR #10340 — empirical anchor (the task description bloat)
• PR #10342 — adjacent OpenAPI discipline gap (contract drift) — out-of-scope; flagged in §5.3 out-of-scope clause as candidate for separate codification
• §5.2 Close-Target Audit — structural model parallel (PR #10262)