# Deterministic Quiz Scorer MCP

> Deterministic EdTech Quiz Scorer automatically grades quizzes by cross-referencing user answers against weighted answer keys. It generates deep performance metrics instantly, providing category weakness breakdowns and calculating average time per question for detailed student analysis.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** grading-automation, performance-metrics, weighted-scoring, edtech, data-processing

## Description

Grading assessments shouldn't require writing complex scripts just to compare arrays or calculate weighted averages. This MCP handles the entire grading pipeline using a hyper-optimized engine. You simply feed it the answer key, the user responses, and optionally the total time taken. The tool doesn't just give a final score; it breaks down performance by subject category—like isolating whether a student struggles with 'Math' versus 'Science.' This granular view reveals exactly where knowledge gaps exist. Because this MCP is hosted on Vinkius, you connect once from any compatible agent and get immediate access to advanced educational evaluation tools for your application.

The resulting data includes the max possible score calculation, percentage accuracy, and even derives a critical metric: the average time spent per question. This saves developers hours of writing complex scoring logic.

## Tools

### score_quiz
Cross-references a user's submitted answers against weighted keys and generates detailed EdTech metrics, including category accuracy percentages.

## Prompt Examples

**Prompt:** 
```
Score this 10-question Math exam for the student.
```

**Response:** 
```
Using the score_quiz tool: The student scored 8.5 out of 10.0 (85% accuracy). They missed questions #3 and #7.
```

**Prompt:** 
```
Give me a category breakdown of the student's weaknesses.
```

**Response:** 
```
Using the score_quiz tool: The category breakdown shows the student excels in 'Algebra' (100%), but is struggling in 'Geometry' (only 40% correct).
```

**Prompt:** 
```
Calculate the average time per question if they finished in 180 seconds.
```

**Response:** 
```
Using the score_quiz tool (totalTimeSeconds=180): The performance metrics show an average of 18 seconds spent per question.
```

## Capabilities

### Calculate weighted final scores
The MCP automatically compares provided answers to an answer key while applying custom point values to generate a total score.

### Identify category weaknesses
It breaks down the overall exam result by specified subject categories, pinpointing exactly which area needs more focus.

### Determine performance percentage
The tool calculates and reports the student's accuracy as a precise percentage relative to the maximum possible score.

### Track average time metrics
By accepting total completion time, it derives the critical metric showing how many seconds were spent on each question.

## Use Cases

### A corporate compliance training module needs testing.
The trainer runs a batch of quizzes where certain sections are weighted more heavily than others. They use score_quiz to generate reports that show not just the overall pass rate, but also which specific regulatory categories (e.g., 'HIPAA Compliance') were missed most often.

### A student is prepping for a standardized test.
The tutor feeds the practice exam keys and the student's answers into score_quiz, along with the time it took. The resulting metrics give the student an average time per question, letting them know if they are spending too much time on simple recall questions.

### An LMS needs to grade a mixed-subject final exam.
The developer calls score_quiz, providing answers and keys that include different weights for 'Algebra' versus 'Literature.' The tool returns the precise weighted total and percentage accuracy needed for the student transcript.

### A curriculum team needs to assess content gaps.
The team runs historical assessment data through score_quiz, grouping failures by category. This quickly shows that 70% of low scores originate from the 'Chemistry' module, pointing directly to a needed content update.

## Benefits

- Stop calculating weighted averages manually. Just send the keys and answers to score_quiz, and it calculates the total score using defined point weights automatically.
- You get more than a single number. The scoring report breaks down performance by 'Math' or 'Science,' immediately telling you which subject area needs revision.
- It handles time tracking too. By passing in the total seconds spent, the tool derives averageTimePerQuestionSeconds, which is crucial for standardized test prep analysis.
- The process doesn't depend on massive external libraries. The MCP uses pure JS runtime execution, meaning you get lightning-fast scoring results every single time.
- It guarantees reliable assessment reporting. You don't have to worry about formula errors or inconsistent data types when calculating scores.

## How It Works

The bottom line is you feed it raw quiz data, and it spits out a detailed, actionable performance report.

1. First, provide the MCP with three required inputs: the full answer key (as a stringified JSON array), the user's submitted answers (also as a stringified JSON array), and an optional total time taken.
2. The engine runs these inputs through its weighted scoring algorithm. It cross-references every user response against the correct key, applying all specified point weights simultaneously.
3. You get back a structured report containing the final score, percentage accuracy, category breakdowns of strengths/weaknesses, and average time per question.

## Frequently Asked Questions

**How does score_quiz handle different point weights?**
score_quiz supports dynamic weighting. You define the weight for each question, and the tool accurately calculates the total possible score and the student's weighted achievement against it.

**Can I get category weakness reports using score_quiz?**
Yes, the MCP generates granular analytics. It breaks down performance by predefined categories (like 'Math' or 'Science'), showing exactly which subject area needs improvement.

**Does score_quiz track how long students take to finish?**
The tool accepts total time in seconds. From that figure, it automatically derives the average time spent per question, giving you a valuable performance metric for analysis.

**Is score_quiz only for multiple choice quizzes?**
No. While it handles multiple-choice structure, its power is in its ability to analyze structured data across different academic categories and complex point systems.

**How does the `score_quiz` handle malformed or incomplete input data?**
The tool validates all required strings before processing. If you pass a JSON array that's improperly structured or missing keys, it throws an explicit error detailing exactly which string failed validation and why.

**Is `score_quiz` limited to objective questions, or can I grade subjective answers?**
The tool is designed for deterministic scoring based on comparison to a weighted key. For open-ended text entries, you must map the expected concepts and keywords into your answer keys; it does not run natural language checks.

**How fast is `score_quiz`? Is it suitable for live, real-time grading?**
It runs with microsecond speed. Because it leverages a pure JS runtime and avoids massive external dependencies, the latency is minimal, making it ideal for integrating into live assessment workflows.

**Does `score_quiz` require specific EdTech libraries or complex setup beyond its environment?**
No. The MCP guarantees a zero-dependency architecture using pure JS runtime execution. This means you don't need to worry about installing large, external EdTech NPM packages.

**Why should I use an MCP instead of asking the AI to grade it?**
LLMs hallucinate math. If you give an LLM 50 questions, it will often miscount the correct answers, fail to apply fractional weights, or hallucinate the final percentage. This MCP uses deterministic V8 loops, guaranteeing 100% mathematical accuracy.

**How does the weighting system work?**
In your `answerKey` JSON array, you can add a `weight` parameter (e.g., `weight: 2.5`). The engine automatically tallies the `maxPossibleScore` and evaluates the user's earned points against it, rather than just doing a flat 1-point-per-question calculation.

**Does it track which questions the user got wrong?**
Yes. The output payload includes an array called `incorrectQuestionIds`, which isolates the exact IDs the user failed, allowing your AI to instantly provide targeted tutoring on those specific topics.