Career Scout MCP demonstrates solid tool design with clear naming, comprehensive descriptions, and well-structured schemas. All four tools follow verb_noun conventions (rescore_, tag_, query_, regenerate_). Descriptions are detailed (100-200 chars typical) and explain WHAT, WHEN, and consequences. Input schemas are complete with types and descriptions. Output models are pydantic-based with documented fields. However, error handling lacks recovery guidance (e.g., 'ValueError if posting not found' but no suggestion for next steps), and tool annotations (readOnlyHint, destructiveHint) are absent despite clear read/write semantics. Parameter descriptions could be more prescriptive about constraints (e.g., date_after format, reason length).

• Add tool annotations to tool registration: mark rescore_posting, tag_mismatched_score, regenerate_digest with destructiveHint=true; mark query_postings with readOnlyHint=true. This enables agents to reason about side effects.
• Enhance error descriptions with recovery paths. E.g., 'ValueError if posting not found: try query_postings(min_score=0) to list available postings' or 'ScoringError on LLM failure: check LLM provider status and retry'.
• Specify parameter constraints explicitly: date_after format (ISO 8601, e.g. '2024-01-15'), reason min length (e.g. 10 chars), limit bounds (1-100). Add these to parameter descriptions.
• Document idempotency guarantees. If rescore_posting is idempotent (same posting_id + rubric = same score), state it. If tag_mismatched_score creates a new row on each call, warn agents not to retry blindly.
• Expand regenerate_digest description: 'Renders top-20 postings by score as a self-contained HTML file. Output: single .html file at settings.digest_output_path with inline CSS, no external dependencies. Returns path, count, and bytes written.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry