Evaluation Types | TutorFlow Agent Platform Docs

Overview

TutorFlow supports three evaluation types, each optimized for different assessment scenarios. Set the evaluationType field when creating an evaluation.

Type	Best For	Pricing
`open_ended`	Essays, free-form responses	`evaluation.default`, $0.02 per request
`rubric_short_answer`	Structured assessments with grading criteria	`evaluation.default`, $0.02 per request
`exact`	Factual answers with known correct responses	`evaluation.default`, $0.02 per request

Open-Ended Evaluation

Best for essay-style answers, short-answer questions, and free-form responses. The AI evaluates the answer holistically and provides detailed feedback.

curl -X POST https://api.tutorflow.io/v1/platform/evaluations \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "evaluationType": "open_ended",
    "questionText": "Explain why the sky is blue",
    "learnerAnswer": "Light scatters in the atmosphere...",
    "maxScore": 10
  }'

Example Response

{
  "id": "2f4ad455-1e8e-4b6c-9f3a-7ebf4cf6f483",
  "status": "COMPLETED",
  "evaluationType": "open_ended",
  "tier": "default",
  "score": 7,
  "maxScore": 10,
  "normalizedScore": 70,
  "confidence": 0.88,
  "strengths": [
    "Correctly explains Rayleigh scattering",
    "Uses relevant scientific vocabulary"
  ],
  "mistakes": [
    "Does not mention the wavelength of blue light"
  ],
  "suggestions": [
    "Explain why shorter wavelengths scatter more",
    "Mention the role of the Sun's position at sunset"
  ],
  "feedbackSummary": "Good understanding of the basic principle, but the explanation lacks depth on wavelength specifics.",
  "nextStep": "Study the electromagnetic spectrum and how wavelength affects light scattering.",
  "isTerminal": true,
  "createdAt": "2026-03-29T10:00:00Z",
  "completedAt": "2026-03-29T10:00:02Z"
}

Rubric-Based Evaluation

Evaluates answers against specific criteria defined in a rubric. Ideal for standardized assessments and assignments with clear grading guidelines.

curl -X POST https://api.tutorflow.io/v1/platform/evaluations \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "evaluationType": "rubric_short_answer",
    "questionText": "Write a persuasive essay about climate change",
    "learnerAnswer": "Climate change is the most pressing...",
    "rubric": {
      "criteria": [
        {
          "name": "Thesis statement",
          "description": "Clear thesis and position",
          "maxScore": 2
        },
        {
          "name": "Evidence",
          "description": "Relevant supporting evidence",
          "maxScore": 3
        }
      ]
    },
    "maxScore": 10
  }'

Example Response

The rubricBreakdown array provides per-criterion scores and feedback.

{
  "id": "3a5bc678-9d0e-1f2a-3b4c-5d6e7f8a9b0c",
  "status": "COMPLETED",
  "evaluationType": "rubric_short_answer",
  "tier": "default",
  "score": 4,
  "maxScore": 10,
  "normalizedScore": 40,
  "confidence": 0.91,
  "rubricBreakdown": [
    {
      "criterion": "Thesis statement",
      "score": 2,
      "maxScore": 2,
      "feedback": "Clear thesis with a well-defined position on climate change."
    },
    {
      "criterion": "Evidence",
      "score": 2,
      "maxScore": 3,
      "feedback": "Some supporting evidence provided, but lacks specific data or citations."
    }
  ],
  "strengths": [
    "Strong thesis statement",
    "Logical argument structure"
  ],
  "mistakes": [
    "Evidence lacks citations",
    "Conclusion does not revisit key arguments"
  ],
  "suggestions": [
    "Include specific data from reputable sources",
    "Strengthen the conclusion by summarizing key points"
  ],
  "feedbackSummary": "Solid argument framework but needs stronger evidence to be persuasive.",
  "nextStep": "Practice finding and citing statistical evidence to support claims.",
  "isTerminal": true,
  "createdAt": "2026-03-29T10:05:00Z",
  "completedAt": "2026-03-29T10:05:03Z"
}

Exact Match Evaluation

Compares the learner's answer against a known correct answer using a local deterministic strategy. TutorFlow trims leading and trailing whitespace, lowercases both values, and then requires an exact string match. It does not perform semantic matching, partial credit, synonym matching, or numeric tolerance. Always send referenceAnswer; if it is omitted, the current matcher compares the learner answer against an empty string.

curl -X POST https://api.tutorflow.io/v1/platform/evaluations \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "evaluationType": "exact",
    "questionText": "What is the chemical formula for water?",
    "learnerAnswer": "H2O",
    "referenceAnswer": "H2O",
    "maxScore": 1
  }'

Example Response

{
  "id": "4b6cd789-0e1f-2a3b-4c5d-6e7f8a9b0c1d",
  "status": "COMPLETED",
  "evaluationType": "exact",
  "tier": "default",
  "score": 1,
  "maxScore": 1,
  "normalizedScore": 100,
  "confidence": 1.0,
  "strengths": [
    "Answer matches the expected response."
  ],
  "mistakes": [],
  "suggestions": [],
  "feedbackSummary": "Correct! Your answer matches the expected response.",
  "isTerminal": true,
  "createdAt": "2026-03-29T10:10:00Z",
  "completedAt": "2026-03-29T10:10:00Z"
}

Language Support

Open-ended and rubric-based evaluations support feedback in any language the AI model can handle. Pass the language field with any language code (e.g., en, ko, ja, zh, es, fr, de, pt, vi).

If omitted, feedback defaults to English (en). Exact-match evaluation is deterministic and currently returns fixed English feedback strings.