feat(server): lazy-load Pydantic outputSchema generation to avoid storyboard readiness flake

[bokelley]

Context

_apply_pydantic_schemas in src/adcp/server/mcp_tools.py runs at import time and generates output schemas for every tool. This coincides with a multi-PR batch of storyboard "Agent unreachable" failures observed across PRs #391, #405, #406, #407.

Deferring schema generation to the first tools/list call should restore predictable boot times and eliminate the readiness race.

Acceptance Criteria

• _apply_pydantic_schemas is invoked lazily (first tools/list call), not at import
• Measured import-time delta documented in PR description
• Storyboard runs no longer flake with "Agent unreachable" on the affected PRs

Refs

• src/adcp/server/mcp_tools.py (_apply_pydantic_schemas)
• PRs feat(validation): ADCP_VALIDATION_MODE env var + outputSchema on tools/list #391, feat(decisioning): MockAdServer Protocol + /_debug/traffic counters (#383) #405, feat(server): /.well-known/adcp-agents.json discovery endpoint (#381) #406, feat(buyer-agent-registry): caching + rate-limit + audit emission (#380) #407 (all hit this flake)

[bokelley]

Triage

Classification: Bug (performance / reliability — import-time readiness race)
Bucket(s): handlers
Status: drafting-pr
Milestone: omitted (no version target specified)

What the experts said:

• code-reviewer: approved — get_tools_for_handler is the correct call site; schemas are applied before _register_handler_tools reads outputSchema; .update() mutation is safe; no blockers
• dx-expert: approved — change is fully transparent to SDK adopters; one blocker found and fixed (stale error message in test_spec_coverage.py); conftest scope="session" autouse fixture is the right approach for test coverage

My take: Clear non-breaking fix — defers ~4.5s of Pydantic schema generation from module import to first create_mcp_tools() call, eliminating the readiness probe race. PR #435 ships the change with 2816 tests passing.

PR summary: Move _generate_pydantic_schemas() + _apply_pydantic_schemas() behind a _ensure_pydantic_schemas_applied() lazy guard called from get_tools_for_handler; add session-scoped conftest fixture so schema-reading tests keep working.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01NnoQN3c6Wi5LY5DEUBp8W2

---

Generated by Claude Code