Legacy framework terminology causing documentation confusion in migrated codebase

Documentation inconsistencies persisted in a codebase after migrating from the legacy ‘fast-agent’ framework to FastMCP 2.0, creating confusion about framework capabilities and architecture. The issue affected 11 files, causing misidentification of framework components and features.

Issue

The documentation contained pervasive references to the deprecated ‘fast-agent’ framework, leading to three critical problems:

1. Framework misidentification: Developers believed the system still used legacy components.
2. Feature misunderstanding: FastMCP 2.0’s advanced capabilities (tools, validation, middleware) were described as a basic ‘evaluator loop’.
3. Migration confusion: Documentation incorrectly implied migration from FastMCP rather than to it.

Culprit

The root cause was incomplete documentation updates during the migration period (September-October 2025). Key issues included:

• Unupdated version references: Files still listed outdated versions like fast-agent-mcp==0.3.15 instead of fastmcp==2.13.0.
• Architectural misdescriptions: Critical components like the ‘6-layer middleware stack’ and ‘Double Bookkeeping’ were omitted from framework descriptions.
• Persistent legacy terms: Files contained outdated terms like ‘Fast-Agent evaluator-optimizer’ instead of FastMCP 2.0’s comprehensive feature set.

Solution

A comprehensive terminology cleanup was performed across:

• Architecture documentation (7 files), ensuring accurate descriptions of FastMCP 2.0’s tools, validation, and guardrails.
• Code files (2 files), updating version references and removing legacy framework terms.
• Configuration files, aligning permission scopes and dependencies with the new framework.

Key Updates

1. Terminology Standardization: Replaced all ‘fast-agent’ references with accurate FastMCP 2.0 terminology, including:

   • ‘Fast-Agent hybrid architecture’ → ‘FastMCP 2.0 orchestration framework with tools, validation, and guardrails’.
   • ‘fast-agent-mcp==0.3.15’ → ‘fastmcp==2.13.0’.

2. Feature Documentation Expansion: Added detailed descriptions of FastMCP 2.0’s features, including:

   • MCP Tools: Database operations, Pydantic schema validation.
   • Guardrails: Double Bookkeeping (AI guess + DB sanity checks), checksum hashing.
   • Middleware: 6-layer stack with evaluator-optimizer loop.
   • Client Features: Core tools/resources/prompts and advanced elicitation/logging.

3. Version Pinning: Updated Python version to 3.14 (FastMCP 2.0 requirement) and pinned FastMCP to ==2.13.0, with explicit references to gofastmcp.com.

The cleanup ensured consistency across documentation, code, and configurations, aligning all references with the latest FastMCP 2.0 framework and eliminating legacy framework confusion.