Learning Optimizer

Spaced-Repetition Schedule & Exam Plan

learning_optimizer

Read-only

Rebuilds each learner's memory of each item from a review log (who answered what, when, how well) and returns: today's review list per learner, most-at-risk first; chance of remembering each item now, in 7 and 30 days; the next review date for a retention target; a day-by-day plan to an exam date within a daily limit, with the daily effort needed if the limit is too low; items that keep slipping; questions most learners miss; neglected topics; and how much daily work 85/90/95% retention costs. Memory models: FSRS-6 (matches py-fsrs 6.3.2 exactly), a per-learner personalised version, half-life regression and SM-2 — the schedule is chosen by measured accuracy on the most recent answers. Output starts with plain decision cards (REVIEW TODAY, CATCH UP, STUDY MORE, ON TRACK FOR EXAM, SHORTER GAPS, TRY ANOTHER WAY, REWRITE ITEM, REVISE TOPIC, PROTECT PRIVACY ...). Up to 2,000 review rows; larger logs: learning_get_engine.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "reviews": "<reviews>"
    },
    "name": "learning_optimizer"
  }
}

Input Schema

Name	Required	Description	Default
`as_of`	No	Today's date (YYYY-MM-DD). Defaults to the latest review.
`items`	No	Optional item bank: item_id (+ topic), including items not studied yet.
`reviews`	Yes	One row per answer: learner_id (anonymous code), item_id, timestamp, grade. Optional: topic, duration_seconds. Always the full history.
`learners`	No	Only these learner codes (others ignored).
`exam_date`	No	Exam date YYYY-MM-DD, to get a day-by-day plan.
`scheduler`	No	auto = the model measured most accurate on recent answers.	auto
`exam_target`	No	Chance of remembering each item on exam day to aim for.
`grade_scale`	No		auto
`leech_lapses`	No	Times forgotten before an item counts as 'keeps slipping'.
`max_items_listed`	No
`min_test_reviews`	No
`target_retention`	No	Chance of remembering to schedule for (0.85-0.95 typical).
`new_items_per_day`	No
`daily_review_limit`	No	Most items a learner can do per day (reviews + new).
`seconds_per_review`	No	Override time per review (seconds).
`include_item_states`	No	List every learner-item state (auto: up to 2,000).	auto
`max_learners_listed`	No
`max_learners_planned`	No
`min_reviews_for_pace`	No
`maximum_interval_days`	No

Output Schema

Name	Required	Description
`alerts`	No
`status`	Yes	1 = ok, 0 = nothing could be scheduled
`content`	No
`message`	No
`learners`	No
`metadata`	Yes
`decisions`	Yes	Plain-language cards, priority order. Relay these first.
`assumptions`	No
`item_states`	No
`model_evaluation`	No
`data_quality_report`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/openWorldHint=false/destructiveHint=false, and the description adds real behavioural detail beyond that: a hard 2,000-row input ceiling, deterministic fidelity to py-fsrs 6.3.2, model selection by measured accuracy on recent answers, and the fact that output is front-loaded with named decision cards (including PROTECT PRIVACY). It omits runtime/compute cost and whether results are cached, which matters for a 20-parameter analytics job.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core capability is front-loaded and every element maps to a real output, but the description is a dense multi-clause wall of enumerations. The trailing decision-card list ending in '...' adds noise without telling the agent how to use those labels, and it sits far from the actual invocation guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 20-parameter analytics tool with an output schema present, the description covers purpose, scale limits, model selection, and output shape (decision cards first). Since the return values are described in the output schema, the remaining gap is mostly operational — no note on expected compute time or failure modes for malformed review rows — but nothing essential to calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 60%, so several of the 20 parameters carry no prose anywhere. The description does add meaning for a few — the retention target behind next-review computation, the daily limit and the fallback 'daily effort needed if the limit is too low', and the auto scheduler's accuracy-based selection. The remaining knobs (leech_lapses, min_test_reviews, maximum_interval_days, the max_*_listed caps) are left entirely to the schema, so this lands at the baseline-plus level rather than compensating for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening clause names a specific verb and resource ('rebuilds each learner's memory of each item from a review log') and then enumerates the concrete outputs: today's review list, recall probabilities at 7/30 days, next review date, exam plan, leeches, missed questions. The named model families (FSRS-6, personalised, HLR, SM-2) and the explicit hand-off to the sibling 'learning_get_engine' make it unmistakable which tool this is.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear routing rule against the sibling — 'Up to 2,000 review rows; larger logs: learning_get_engine' — plus the implicit condition that a day-by-day plan requires exam_date and that scheduling mode is auto-selected unless overridden. It does not state when this tool should be avoided for other reasons (e.g. single-item lookups or non-review-log input), so it stops short of full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Learning Optimizer tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.