Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The Anki MCP server has a moderate foundation with clear tool names that follow the verb_noun convention (anki_get_*, anki_set_*, etc.), which helps LLMs parse intent. However, descriptions are inconsistent in depth and completeness. Many parameter descriptions are adequate but generic. All 17 tools have input schemas with proper JSON Schema types and descriptions visible in the source, which is a significant strength. Tool annotations (READ_ONLY_ANNOTATIONS, IDEMPOTENT_WRITE_ANNOTATIONS, etc.) are implemented, a modern best practice. However, output schemas are not explicitly documented in the source, parameter relationships are undocumented, and error handling guidance is absent, critical gaps for production-grade agents. The tool set is well-composed with single responsibilities and batch operations (array parameters), but lacks recovery guidance and confirmation patterns for destructive operations.
Output schemas are not documented in tool descriptions or source. LLMs cannot plan downstream calls or extract results correctly without knowing what fields to expect (e.g., anki_get_cards_info returns what structure?). This violates pattern:tool-description and pattern:response-shaper.
No error handling guidance. Tools lack descriptions that tell LLMs what to do on failure, classify errors as retryable/user-fixable/fatal, or suggest recovery paths. This violates pattern:recovery-guide and pattern:error-classification.
Document output schemas explicitly in each tool description or in a separate 'returns' field. E.g., 'Returns: {cards: [{card_id: int, ease_factor: int}], total: int}'. This allows LLMs to plan chaining calls and extract results reliably.
Add error handling guidance to every tool description that modifies state. E.g., 'On error: if card not found, returns an error indicating invalid card ID, verify the ID is correct and the card exists. If Anki is not running, the service will return a connection error, ensure Anki-Connect is running.'
For destructive operations (anki_forget_cards, anki_answer_cards), add a 'dry_run' boolean parameter (default: false) so agents can preview impact before committing. Or document that agents should call anki_get_cards_info before these operations to let the user confirm.
Expand anki_set_specific_value_of_card documentation: 'Valid keys: flags (0-4), odue (null or integer), due (integer). Keys odue, did, and queue require warning_check=true due to potential data loss risk. Example: to flag a card red, call with keys=["flags"], newValues=["1"], warning_check=false.'
Replace vague parameter descriptions with enum constraints. For anki_set_card_due_date, change 'days' description to: 'Due date specification as string. Format: a single integer (e.g., "0" for today, "1" for tomorrow) or a range (e.g., "3-7") or with modifiers (e.g., "1!" to set as new). Refer to Anki documentation for full syntax.'
Add a return-field-naming section to the README showing how downstream tools chain with output. E.g., 'anki_find_cards returns card_id; use it directly with anki_get_cards_info(cards=[<returned_id>]).'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↑ 58 points across a rubric change (v1 → v2)
58/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
D
58
<=2025-11-25
v2
2026-03-09
F
0
-
v1
85/100
Returns intervals for given cards. Negative: seconds, Positive: days.
Parameter relationships undocumented. anki_set_specific_value_of_card has parameters 'keys', 'newValues', and 'warning_check', but no documentation of which keys require warning_check=true or what values are valid for each key. This forces LLMs to guess. Violates review:param-relationships.
Some descriptions too generic and lack context. E.g., 'Forget cards, making them new again' does not explain the impact (resets progress, makes cards appear new in the learning queue) or when to use it vs relearn_cards. Violates pattern:tool-description.
anki_set_card_due_date parameter 'days' is described as a string with vague format ('e.g., "0", "1!", "3-7"'). This is underspecified, LLMs will hallucinate invalid formats. Needs explicit enum or regex pattern with clear documentation of what each format means. Violates pattern:constrained-input.
anki_answer_cards 'ease' parameter description mentions values 1-4 (Again, Hard, Good, Easy) but does not state whether other values are rejected or what the behavior is if an LLM passes an invalid ease. Violates review:actionable-errors.
anki_answer_cards
Implement per-item error reporting for batch operations. E.g., anki_set_ease_factors should return [{card_id: 1, success: true}, {card_id: 2, success: false, reason: 'card not found'}] instead of a blanket error, so agents can retry only failed items.
Add dependency hints in tool descriptions. E.g., 'If you have a search query, call anki_find_cards first to get card IDs, then pass those IDs to anki_get_cards_info for detailed data.' This guides multi-step planning.
Define and document which operations are idempotent vs non-idempotent. E.g., 'anki_set_ease_factors is idempotent: calling it twice with the same ease factors has the same effect as calling once. anki_answer_cards is NOT idempotent: each call increments the card's review count and may change its due date differently.' This helps agents decide whether to retry on transient failures.