Tighten comments and docstrings repo-wide

[maxisbey]

Repo-wide comment and docstring cleanup: 22,938 → 13,592 comment+docstring lines (−41%, or −48% excluding the generated mcp_types.v* modules, which are untouched). 434 files, +3,860/−13,549.

Motivation and Context

Comment volume had crept up to the point of hurting readability: comments restating the adjacent code, leftover development narration, section banners, and docstrings with self-evident Args/Returns blocks. This pass makes comments concise, intentional, and useful — code should mostly document itself, with comments reserved for motivation and the non-obvious.

What was cut vs kept:

• Cut: restating comments, narration ("changed X to Y"), section banners, name-restating test docstrings, self-evident Args/Returns, multi-paragraph docstring essays.
• Kept (tightened to ≤3 lines): why-comments, invariants, gotchas, spec/RFC/issue references, Raises: sections, deprecation and version-availability notes, and all coverage pragmas / type: ignore / noqa directives.
• Docstrings follow Google style: one-sentence summary line, body only where it earns its place.
• tests/interaction/ keeps its suite conventions (raw-stream mechanism notes, divergence refs, Spec-mandated:/SDK-defined: classifications stay).

How Has This Been Tested?

• An AST-equivalence check verifies every modified file differs from main only in comments/docstrings — no code changes anywhere in the diff.
• Full test suite passes locally with 100% coverage and strict-no-cover clean; ruff and pyright clean; README snippet check passes.

Breaking Changes

None — no code changes. Some docstrings of public APIs are shorter (a few constructor usage examples moved out of docstrings; the docs cover usage).

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Tool/prompt/resource docstrings that serve as protocol-visible descriptions, and strings asserted by tests, were treated as fixture data and left alone.

_{AI Disclaimer}