Author's Note: Filed by Claude Opus 4.7 (Claude Code) during session b5a17132-7324-46e1-b73e-038825bb4d55 after @tobiu's empirical challenge on PR #10340 surfaced a missing reviewer-side discipline. Empirical anchor: my original task parameter description in ai/mcp/server/memory-core/openapi.yaml was a 6-line block-literal (~600 chars) bloating the MCP tool surface with internal architectural framing (Phase 1/Phase 2 references, ticket cross-refs #10334/#10313/#10338) that does NOT belong in agent-runtime tool surface. Tobi's challenge: "these directly map to mcp server tools. they must be short and meaningful." Tightened to 1 line / ~155 chars. The principle was implicit; codifying it as a pr-review audit step prevents recurrence.
Context
OpenAPI YAML descriptions on MCP tool params (e.g. ai/mcp/server/*/openapi.yaml) are loaded into every consuming agent's context window when the tool surface is enumerated. Bloat compounds across the tool surface: a single 600-char description on one parameter, multiplied by ~80 MCP tools, multiplied by every agent session enumerating tool capabilities, becomes meaningful context-window pressure that competes with the actual reasoning budget.
Existing memory anchor: per feedback_mcp_output_category_split, OpenAPI MCP tool schemas are closed contracts — terse + meaningful is the convention. feedback_mcp_test_location and feedback_mcp_sync_blocks_transport_intentional capture other MCP-substrate disciplines that emerged from observed friction.
The pr-review skill currently audits:
- Decile-anchor scoring (§3.1)
- Score justification (§3.2)
- Required Actions (§5)
- Empirical Isolation Tests (§5.1)
- Close-Target Audit (§5.2)
- Depth Floor (§7.1)
- Cross-Model Asymmetry (§7.2)
- Provenance Audit (§7.3)
- Cross-Skill Integration Audit (§8)
- A2A Comment-ID Hand-off (§9)
It does NOT audit OpenAPI tool-description budget. Adding it closes the gap.
The Problem
PR reviews currently don't structurally check whether OpenAPI YAML changes (in ai/mcp/server/*/openapi.yaml) keep tool descriptions terse + usage-focused. The bloat I introduced on PR #10340 was caught by @tobiu post-Approval, requiring a follow-up commit. Reviewer-side discipline would have caught it pre-Approval.
The Architectural Reality — Three Audiences, Three Verbosity Budgets
Same code change can have different audiences. Each has a different verbosity budget:
| Surface |
Audience |
Verbosity budget |
Acceptable content |
OpenAPI YAML (openapi.yaml) |
MCP-consuming agents at runtime (every tool-surface enumeration) |
Terse, single-line, usage-focused |
What it is + when to use + when NOT to use |
| JSDoc (source code) |
Developers reading source |
Verbose; framing OK |
Architectural rationale, design history, cross-refs |
| PR body / ticket body |
Reviewers + Retrospective daemon |
Full Fat Ticket |
Narrative, deltas, test evidence, post-merge validation |
Conflating budgets — bloating YAML with what should have stayed in JSDoc — has empirical cost. Also conflates audience: an agent calling add_message doesn't need to know about Phase 1/Phase 2 sequencing; it needs to know whether to populate the param.
The Fix
Add a new sub-section to pr-review-guide.md (suggested location: §5.3, parallel to §5.2 Close-Target Audit) — MCP-Tool-Description Budget Audit:
<h3 class="neo-h3" data-record-id="6">5.3 MCP-Tool-Description Budget Audit</h3>
When a PR touches `ai/mcp/server/*/openapi.yaml`, audit each modified or added tool
description for budget compliance. Tool descriptions are loaded into every consuming
agent's context window when the tool surface is enumerated; bloat compounds across the
tool surface and competes with reasoning budget at runtime.
**Trigger conditions** (fire if any apply):
- PR adds new `description:` to an OpenAPI tool param or operation
- PR modifies an existing `description:` block-literal (`|` form)
- PR introduces new OpenAPI tool path or operation
**Audit checks:**
1. **Single-line preferred** — multi-line block-literal (`|`) descriptions warrant scrutiny
2. **No internal cross-refs** — descriptions should not cite ticket numbers, internal Phase
sequencing, or session IDs (those belong in JSDoc + ticket bodies)
3. **No architectural narrative** — descriptions should describe call-site usage
(what + when-to-use + when-not-to-use), not implementation history
4. **External standard URLs OK** — citing `https://a2a-protocol.org/...` is acceptable
when the param adopts an external spec; agents can navigate canonical docs
5. **Mind the 1024-char hard cap** — MCP protocol enforces a per-tool-description limit;
approaching it is a red flag (see `McpServerToolLimits` test for empirical bound)
**Required Action shape when violated:**
> *"OpenAPI description on param `X` of tool `Y` exceeds budget — multi-line block-literal
> + internal ticket references. Tighten to single-line usage-focused description; move
> architectural narrative to JSDoc on the corresponding service method or to the PR body."*
**Distinction from JSDoc audit:** JSDoc on service-method-source is a separate audience
(developers reading code). Verbosity is acceptable there. The audit fires only on the
OpenAPI YAML surface that becomes runtime tool-description payload.
Plus update pr-review-template.md with optional checkbox in 🔗 Cross-Skill Integration Audit or new 📡 MCP Tool Surface Audit section.
Acceptance Criteria
Out of Scope
- Auto-tooling for description-bloat detection — could imagine a CI step parsing YAML and flagging long descriptions. Out of scope here; discipline-layer enforcement first, mechanical-layer if discipline alone proves insufficient.
- Migration sweep of existing OpenAPI files — current files may have legacy verbose descriptions; cleanup is forward-only via this discipline + opportunistic refactoring during ongoing PR work.
- Generic verbosity budget for all skill descriptions — focused scope on MCP YAML surface specifically. Other surfaces (skill
triggers: field, frontmatter description:) have different audiences + different budgets.
- JSDoc audit — separate scope, different audience. JSDoc verbosity is acceptable there.
- PR body description bloat — also separate; PR bodies serve reviewers + Retrospective daemon, full Fat Ticket budget appropriate.
Avoided Traps
- Hard char-cap mandate — rejected; descriptions vary by tool complexity. Single-line preference + 1024-char cap awareness is sufficient. Per
feedback_challenge_numerical_thresholds_in_acs.
- Auto-rewriting descriptions — rejected; reviewer flags as Required Action; author makes the choice (tighten + document why, or push back with rationale).
- Coupling with JSDoc audit — rejected; different audience, different budget. JSDoc gets to be verbose; YAML doesn't.
- Treating ALL YAML changes as suspect — rejected; trigger conditions narrow the surface. Type-only changes (
type: string) or items-array changes don't need budget audit.
Related
- PR #10340 — empirical anchor; the
task param description that triggered tobi's challenge
feedback_mcp_output_category_split — existing memory anchor on closed contracts vs runtime introspectionfeedback_mcp_test_location — adjacent MCP discipline (test path)feedback_mcp_sync_blocks_transport_intentional — adjacent MCP discipline (sync semantics)feedback_challenge_numerical_thresholds_in_acs — discipline pattern: prefer observability/architectural-layer assertions over format-layer capsMcpServerToolLimits.spec.mjs — empirical bound for the 1024-char cap (per memory)- #10336 / #10337 — recently codified
external-precedent web_search step in ideation-sandbox; structural precedent for adding discipline-layer audits via single skill-step addition
Origin Session ID: b5a17132-7324-46e1-b73e-038825bb4d55
Retrieval Hint: "MCP tool description budget audit OpenAPI YAML pr-review skill bloat tool-surface enumeration runtime context-window 1024-char-cap discipline-layer single-line"
Context
OpenAPI YAML descriptions on MCP tool params (e.g.
ai/mcp/server/*/openapi.yaml) are loaded into every consuming agent's context window when the tool surface is enumerated. Bloat compounds across the tool surface: a single 600-char description on one parameter, multiplied by ~80 MCP tools, multiplied by every agent session enumerating tool capabilities, becomes meaningful context-window pressure that competes with the actual reasoning budget.Existing memory anchor: per
feedback_mcp_output_category_split, OpenAPI MCP tool schemas are closed contracts — terse + meaningful is the convention.feedback_mcp_test_locationandfeedback_mcp_sync_blocks_transport_intentionalcapture other MCP-substrate disciplines that emerged from observed friction.The
pr-reviewskill currently audits:It does NOT audit OpenAPI tool-description budget. Adding it closes the gap.
The Problem
PR reviews currently don't structurally check whether OpenAPI YAML changes (in
ai/mcp/server/*/openapi.yaml) keep tool descriptions terse + usage-focused. The bloat I introduced on PR #10340 was caught by @tobiu post-Approval, requiring a follow-up commit. Reviewer-side discipline would have caught it pre-Approval.The Architectural Reality — Three Audiences, Three Verbosity Budgets
Same code change can have different audiences. Each has a different verbosity budget:
openapi.yaml)Conflating budgets — bloating YAML with what should have stayed in JSDoc — has empirical cost. Also conflates audience: an agent calling
add_messagedoesn't need to know about Phase 1/Phase 2 sequencing; it needs to know whether to populate the param.The Fix
Add a new sub-section to
pr-review-guide.md(suggested location: §5.3, parallel to §5.2 Close-Target Audit) —MCP-Tool-Description Budget Audit:<h3 class="neo-h3" data-record-id="6">5.3 MCP-Tool-Description Budget Audit</h3> When a PR touches `ai/mcp/server/*/openapi.yaml`, audit each modified or added tool description for budget compliance. Tool descriptions are loaded into every consuming agent's context window when the tool surface is enumerated; bloat compounds across the tool surface and competes with reasoning budget at runtime. **Trigger conditions** (fire if any apply): - PR adds new `description:` to an OpenAPI tool param or operation - PR modifies an existing `description:` block-literal (`|` form) - PR introduces new OpenAPI tool path or operation **Audit checks:** 1. **Single-line preferred** — multi-line block-literal (`|`) descriptions warrant scrutiny 2. **No internal cross-refs** — descriptions should not cite ticket numbers, internal Phase sequencing, or session IDs (those belong in JSDoc + ticket bodies) 3. **No architectural narrative** — descriptions should describe call-site usage (what + when-to-use + when-not-to-use), not implementation history 4. **External standard URLs OK** — citing `https://a2a-protocol.org/...` is acceptable when the param adopts an external spec; agents can navigate canonical docs 5. **Mind the 1024-char hard cap** — MCP protocol enforces a per-tool-description limit; approaching it is a red flag (see `McpServerToolLimits` test for empirical bound) **Required Action shape when violated:** > *"OpenAPI description on param `X` of tool `Y` exceeds budget — multi-line block-literal > + internal ticket references. Tighten to single-line usage-focused description; move > architectural narrative to JSDoc on the corresponding service method or to the PR body."* **Distinction from JSDoc audit:** JSDoc on service-method-source is a separate audience (developers reading code). Verbosity is acceptable there. The audit fires only on the OpenAPI YAML surface that becomes runtime tool-description payload.Plus update
pr-review-template.mdwith optional checkbox in🔗 Cross-Skill Integration Auditor new📡 MCP Tool Surface Auditsection.Acceptance Criteria
.agent/skills/pr-review/references/pr-review-guide.mdupdated with new§5.3 MCP-Tool-Description Budget Auditsectiontaskparameter pre-fix vs post-fix character counts (~600 → ~155 chars, 4× reduction)pr-review-template.mdextended with audit checkbox where relevantfeedback_mcp_output_category_split,feedback_mcp_test_location,feedback_mcp_sync_blocks_transport_intentionalOut of Scope
triggers:field, frontmatterdescription:) have different audiences + different budgets.Avoided Traps
feedback_challenge_numerical_thresholds_in_acs.type: string) or items-array changes don't need budget audit.Related
taskparam description that triggered tobi's challengefeedback_mcp_output_category_split— existing memory anchor on closed contracts vs runtime introspectionfeedback_mcp_test_location— adjacent MCP discipline (test path)feedback_mcp_sync_blocks_transport_intentional— adjacent MCP discipline (sync semantics)feedback_challenge_numerical_thresholds_in_acs— discipline pattern: prefer observability/architectural-layer assertions over format-layer capsMcpServerToolLimits.spec.mjs— empirical bound for the 1024-char cap (per memory)external-precedent web_searchstep in ideation-sandbox; structural precedent for adding discipline-layer audits via single skill-step additionOrigin Session ID:
b5a17132-7324-46e1-b73e-038825bb4d55Retrieval Hint:"MCP tool description budget audit OpenAPI YAML pr-review skill bloat tool-surface enumeration runtime context-window 1024-char-cap discipline-layer single-line"