Skip to main content

Tools reference

The server exposes three tools. Each one has a JSON Schema for its input (inputSchema) and for its output (outputSchema). Every successful call returns the output twice: as structuredContent (JSON for programs) and as a JSON string in content (text for the model).

ToolTitleRead-onlyIdempotent
generate_problemGenerate a practice problemYesYes
check_answerCheck a student's answerNo (counts attempts)No
get_hintGet a hintYesYes

Idempotent means that calling the tool twice with the same input has the same effect as calling it once.

generate_problem​

Create a CAT-style quantitative aptitude or reasoning practice problem. Returns the problem statement and a problem_id, but never the answer. Show the statement to the student and let them attempt it.

Annotations: readOnlyHint: true, idempotentHint: true, openWorldHint: false.

Input​

NameTypeRequiredDefaultConstraintsDescription
topicstringYes—One of the 13 topics belowQuant, reasoning or VARC topic to practise.
difficultystringNo"medium"easy, medium, hardHow challenging the problem should be.
seedinteger or nullNonull0 to 999999Seed for a reproducible problem. Omit for a random one.

Every topic is offered at every difficulty:

TopicSectionEasyMediumHard
percentagesquantp% of a numberSuccessive increase then decreasePrice rise: percentage cut in consumption to keep spending the same
profit_lossquantSelling price from cost price and profit or loss %Marked price for a target profit after a discountPrice for a gain %, given a selling price at a loss %
ratio_proportionquantDivide an amount in a ratioCombine A:B and B:C, then find a shareWater to add to a milk-water mixture to reach a new ratio
time_speed_distancequantTrain passing a pole (km/h to m/s)Average speed for a round tripTwo trains crossing, same or opposite directions
time_workquantTwo people working togetherOne person's time from the pair's timeTwo filling pipes and one emptying pipe
interestquantSimple interestCompound interest for 2 yearsPrincipal from the CI - SI difference for 2 years
linear_equationsquantTwo numbers from their sum and differencePair of linear equations: find xPresent age from two age ratios
quadraticsquantx² + bx + c = 0, two positive whole-number rootsx² + bx + c = 0, at least one negative rootax² + bx + c = 0 (a from 2 to 5) with one fractional root
number_systemquantHCF or LCM of two numbersUnits digit of a powerNumber of factors of a number
number_seriesreasoningNext term of an arithmetic seriesGeometric series or series with growing gapsMultiply-and-add series, or two interleaved series
para_jumblesvarc4 sentences with clear time or cause links4 sentences joined by pronouns and connectors5 sentences with a longer argument
odd_sentence_outvarc5 sentences, the odd one on a nearby but different subjectThe odd one shares keywords with the paragraphThe odd one is on the same subject but makes a different point
para_summaryvarcShort passage, 4 optionsPassage with a claim and a conditionPassage with a balanced or qualified conclusion

Numbers are chosen so that every answer is exact: a whole number, a short decimal such as 37.5, or (for quadratics) a simple fraction.

VARC items come from a small bank of original passages written for this project: 9 items per type (3 per difficulty), 27 in all. The seed picks the item and shuffles it, so the same seed always gives the same sentence order or option order. A para jumble is never shown already in the right order.

Full inputSchema
{
"type": "object",
"title": "generate_problemArguments",
"properties": {
"topic": {
"description": "Quant, reasoning or VARC topic to practise.",
"enum": [
"percentages", "profit_loss", "ratio_proportion", "time_speed_distance", "time_work",
"interest", "linear_equations", "quadratics", "number_system", "number_series",
"para_jumbles", "odd_sentence_out", "para_summary"
],
"title": "Topic",
"type": "string"
},
"difficulty": {
"default": "medium",
"description": "How challenging the problem should be.",
"enum": ["easy", "medium", "hard"],
"title": "Difficulty",
"type": "string"
},
"seed": {
"anyOf": [{"maximum": 999999, "minimum": 0, "type": "integer"}, {"type": "null"}],
"default": null,
"description": "Optional seed for a reproducible problem. Omit for a random one.",
"title": "Seed"
}
},
"required": ["topic"]
}

Output: GeneratedProblem​

FieldTypeDescription
problem_idstringStable ID, for example pl-hard-42. Pass it to check_answer and get_hint.
sectionstringExam section: quant, reasoning or varc.
topicstringThe topic.
difficultystringThe difficulty.
seedintegerSeed used. The same topic, difficulty and seed give the same problem.
statementstringThe question to show the student.
answer_formatstringHow the student should write their answer.
max_hint_levelintegerAlways 3.

The answer is deliberately not included. See Security model.

Example​

arguments
{"topic": "profit_loss", "difficulty": "hard", "seed": 42}
structuredContent
{
"problem_id": "pl-hard-42",
"section": "quant",
"topic": "profit_loss",
"difficulty": "hard",
"seed": 42,
"statement": "By selling an article for Rs 800, a trader loses 20%. At what price, in rupees, should he sell it to gain 30%?",
"answer_format": "a number, for example 450 (no units, % or Rs sign needed)",
"max_hint_level": 3
}

Problem IDs​

A problem ID encodes everything needed to rebuild the problem:

pl-hard-42
│ │ └── seed (0–999999)
│ └─────── difficulty
└────────── topic code
TopicCodeTopicCode
percentagespctinterestint
profit_losspllinear_equationslin
ratio_proportionratioquadraticsquad
time_speed_distancetsdnumber_systemnum
time_workworknumber_seriesseries
para_jumblespjodd_sentence_outodd
para_summarysum

IDs must match ^(pct|pl|ratio|tsd|work|int|lin|quad|num|series|pj|odd|sum)-(easy|medium|hard)-(\d{1,6})$ and be at most 32 characters.

check_answer​

Mark a student's answer and give feedback. A wrong answer never reveals the correct one on the first attempts. The worked solution appears only once the student is correct, or after 3 wrong attempts.

Annotations: readOnlyHint: false, destructiveHint: false, openWorldHint: false. The tool is not read-only because it counts attempts in memory. It changes nothing outside the server process.

Input​

NameTypeRequiredConstraintsDescription
problem_idstringYesProblem ID pattern, max 32 charactersID returned by generate_problem.
answerstringYes1 to 300 charactersThe student's answer, for example 1300, Rs 1,300, 37.5, 2, -5, 2-4-1-3 (para jumbles), 3 (odd sentence out) or B (para summary).

Accepted answer formats. The checker reads numbers from free text and uses the last one, so 1300, SP = Rs. 1300 and Rs 1,300 are equivalent. Digit grouping with commas works in both styles (1,200,000 and 12,00,000). A % sign, units such as km/h, fractions (75/2), decimals (37.5) and negative numbers (-3, or −3 with a Unicode minus) all work. For quadratics, give both roots in any order: 3/4, 3 or x = 3 or x = 0.75. There, commas separate the roots.

VARC answer formats.

  • Para jumbles: every sentence number once, in order. 2-4-1-3, 2413, 2 4 1 3 and 2, 4, 1, 3 are equivalent. A missing or repeated number is a tool error, not a wrong answer.
  • Odd sentence out: one number from 1 to 5, such as 3 or Sentence 3.
  • Para summary: a letter (B, b, (B), Option B) or the full text of the option pasted back. Case and punctuation are ignored.

Output: AnswerCheck​

FieldTypeDescription
problem_idstringThe problem ID.
correctbooleanWhether the answer is right.
attemptintegerHow many times this problem has been checked since the server started.
feedbackstringEncouraging, specific feedback. Never contains the answer before the reveal.
solutionstring or nullThe worked solution. null unless the answer is correct or this is attempt 3 or later.

Feedback rules​

Situationfeedbacksolution
Correct"Correct! Well done. Now try to solve the next one faster." (for quadratics: "Correct! Both roots are right. Substitute each one back in to see why.")Worked solution
Wrong, matches a known misconceptionTargeted, for example "The gain % is worked out on the cost price, not on the old selling price."null
Wrong, no known misconception"Not quite. Re-check each step, or ask for a hint."null
Wrong, attempt 2Feedback plus " Tip: call get_hint for a nudge before the next try."null
Wrong, attempt 3 or laterFeedback plus " You have tried this a few times, so here is the worked solution. Read it, then try a new problem."Worked solution
Quadratic, only one root given and it is right"One root is right. A quadratic like this has two roots; find the other one."null
Quadratic, one root right and one wrong"One of your roots is right, but the other is not. Check that bracket again."null
VARC, correctPraise that names what worked, for example "Correct! That option keeps the main claim without adding or dropping anything."Correct order, sentence or option, with the reason
Para summary, wrong optionNames the kind of trap: covers only one detail, goes beyond the passage, or changes what the passage saysnull
Para jumbles or odd sentence out, wrongA general nudge that never names a sentence numbernull

Example​

arguments
{"problem_id": "pl-hard-42", "answer": "1040"}
structuredContent
{
"problem_id": "pl-hard-42",
"correct": false,
"attempt": 1,
"feedback": "The gain % is worked out on the cost price, not on the old selling price.",
"solution": null
}

get_hint​

Give a progressive hint for a problem. Start at level 1 and only go higher if the student is still stuck. Hints guide the student's thinking and never state the final answer.

Annotations: readOnlyHint: true, idempotentHint: true, openWorldHint: false.

Input​

NameTypeRequiredDefaultConstraintsDescription
problem_idstringYes—Problem ID pattern, max 32 charactersID returned by generate_problem.
levelintegerNo11 to 31 = gentle nudge, 2 = key step, 3 = last step before the answer.

Output: Hint​

FieldTypeDescription
problem_idstringThe problem ID.
levelintegerThe level returned.
max_levelintegerAlways 3.
hintstringThe hint text. Never states the final answer.
next_stepstringWhat the student should do next.

Example: all three levels for pl-hard-42​

Levelhint
1Find the cost price first. A loss of 20% means Rs 800 is 80% of the cost price.
2To get the cost price, divide Rs 800 by 80 and multiply by 100.
3Now find 130% of that cost price.

At level 3, next_step is "That was the last hint. Have a go and use check_answer to see how you did." The design is explained in The pedagogy behind hints.

Errors​

There are two kinds of error. Hosts handle them differently, so it helps to know which is which.

Tool errors (isError: true)​

The call succeeds at the protocol level, but the result has "isError": true and a text message. The model can read the message and correct its next call.

CauseExample message
Answer contains no numberError executing tool check_answer: I could not find a number in that answer. Expected format: a number, for example 450 (no units, % or Rs sign needed).
VARC answer in the wrong shape… Give each of the 4 sentence numbers exactly once, in order. Expected format: …, … Give one sentence number. … or … I could not match that to an option. …
Fraction with zero denominatorError executing tool check_answer: A fraction cannot have 0 as its denominator. Expected format: …
Argument fails the schema (wrong type, out of range, bad pattern, empty)Error executing tool get_hint: 1 validation error for get_hintArguments followed by level and Input should be less than or equal to 3 [type=less_than_equal, input_value=5, input_type=int]
Unknown topic or difficulty… topic Input should be 'percentages', 'profit_loss', 'ratio_proportion', …, 'number_series', 'para_jumbles', 'odd_sentence_out' or 'para_summary' [type=literal_error, …]
Invalid problem ID, such as ../etc/passwd… problem_id String should match pattern '^(pct|pl|ratio|tsd|work|int|lin|quad|num|series|pj|odd|sum)-(easy|medium|hard)-(\d{1,6})$' [type=string_pattern_mismatch, …]

Schema validation runs before the tool's code. An invalid argument never reaches the problem engine.

Protocol errors (JSON-RPC error)​

The request itself is rejected, and the response has an error object instead of a result. The Python client raises MCPError.

CodeNameWhen
-32602Invalid paramsReading an unknown resource such as syllabus://section/gk, or invalid arguments to the socratic_tutor prompt.
-32601Method not foundCalling a method the server does not implement.

Full request and response pairs are in the JSON-RPC examples.