Query a 1,038,963-problem competition/olympiad math database — search it, sample practice sets from it, and pull full problem records with answers, hints, solutions, and reasoning traces.
Get stats (arquimedes_stats) — summary counts by dataset, category, competition, and solution kind; takes no arguments.
Search problems (arquimedes_search) — full-text search over keywords, theorem names (e.g. Cauchy-Schwarz, pigeonhole), or LaTeX snippets; required query, optional filters on dataset, category, competition, and min_mohs/max_mohs (1.0–10.0); returns 1–50 results (default 10).
Sample problems (arquimedes_sample) — uniform random draw (default 5, max 50) with optional seed for reproducibility, plus filters for year, has_choices (multiple-choice vs free-response/proof), has_diagram (SVG/JPG figures), difficulty, category, dataset, and competition; suited to practice sets, mock olympiads, and eval benchmarks.
Fetch a problem by ID (arquimedes_get_problem) — returns the full LaTeX statement, answer choices, verified answer, progressive hints, written proof solutions, and diagram references, with include_solutions (default true) and include_traces for deepmath long-CoT R1 reasoning traces.
Safety profile — every tool is read-only, non-destructive, and closed-world; all are idempotent except arquimedes_sample, which varies unless a seed is supplied.
A structured, deduplicated database of competition and benchmark mathematics:
1,038,963 problems across 9 datasets, each with a normalized LaTeX statement,
calibrated Mohs difficulty (1.0 to 10.0), answer metadata, and solutions in a
uniform JSON schema (v2).
1,038,963 problems with full statements and 99.98% domain categorization
797,671 written solutions: proof-sketch (797,631), strategy (22), answer-only (18)
277,002 model-reasoning traces (deepmath dataset, JSONL shards)
1,219 diagram images (SVG and JPG), content-addressed by hash
Unified Mohs difficulty (1.0–10.0) populated across all 1,038,963 records
Fast CLI & MCP Server: installable via uv (arquimedes CLI and arquimedes-mcp server)
Decontaminated Train/Eval Splits: one-command export (972,458 decontaminated train / 10,533 canonical eval)
Interactive Web Explorer: minimalistic browser catalog in site/ ready for GitHub Pages
dataset | contents | problems | notable fields |
| NuminaMath problems, the largest dataset | 840,924 | origin tags per problem, Mohs difficulty |
| DeepMath problems with R1 reasoning traces | 92,334 | three model-reasoning traces per problem, difficulty rating |
| Big-Math-RL-Verified problems with verified answers | 77,527 | Llama-8B solve-rate difficulty note, hierarchical domain tags |
| MATH benchmark problems | 12,401 | difficulty levels |
| curated competition problems (AMC program, IMO, HMMT, and more) | 10,645 | concept tags, course/source difficulty ratings, progressive hints, solve time |
| Omni-MATH olympiad problems | 2,640 | difficulty rating from |
| OlympiadBench olympiad problems | 1,389 | diagram images (JPG), answer-type tags |
| CEMC multiple-choice contests (Gauss, Pascal, Cayley, Fermat) | 792 | five answer choices per problem, reference URLs |
| competition problems with community-written solutions | 311 | collection, year, and problem code per record |
Related MCP server: mathlas
category | problems | share |
| 386,699 | 37.22% |
| 243,231 | 23.41% |
| 183,930 | 17.70% |
| 129,482 | 12.46% |
| 38,809 | 3.74% |
| 35,493 | 3.42% |
| 19,935 | 1.92% |
| 1,225 | 0.12% |
| 159 | 0.02% |
Per-dataset category breakdowns and field notes: docs/datasets.md.
The source.collection field labels records that come from a named
competition or benchmark:
AMC program (core): AHSME 1,810 · AMC 8 1,025 · AMC 10A 625 · AMC 10B 625 · AMC 10 50 · AMC 12A 625 · AMC 12B 625 · AMC 12 50 · AIME I 405 · AIME II 405 · AIME 255 · USAMO 153 · USA TST 45 · USA TSTST 48
IMO (core): 156
HMMT (core): February 2,606 · November 1,072 · Invitational 65
CEMC (cemc): Gauss (Grade 7) 174 · Gauss (Grade 8) 166 · Pascal (Grade 9) 134 · Cayley (Grade 10) 150 · Fermat (Grade 11) 168
AoPS (aops): IMO Shortlist 102 · USAJMO 91 · Canadian MO 83 · APMO 28 · Putnam 7
OlympiadBench (olympiadbench): 1,389
MATH (math): 12,401
Records in omnimath, deepmath, numina, and bigmath carry origin and domain labels in source.tags.
uv)arquimedes ships a zero-dependency Python package with both a fast CLI (arquimedes) and a Model Context Protocol server (arquimedes-mcp) backed by SQLite + FTS5 (with automatic JSONL shard fallback when SQLite is absent).
# Build the local 1.7 GB SQLite + FTS5 database (~50 seconds)
uv run arquimedes build
# or a 0.8 GB index that reads solutions from the shards
uv run arquimedes build --lean
# Show corpus summary
uv run arquimedes stats
# Sub-20ms full-text search across 1,038,963 problems
uv run arquimedes search "Cauchy-Schwarz" --min-mohs 7.0 -n 5
# Sample calibrated problems by competition, category, or Mohs difficulty
uv run arquimedes sample --competition IMO --category geometry -n 3
# Inspect a full problem record with choices, answer, hints, and proof
uv run arquimedes show prob.ahsme-1950-p10Add to your mcp.json or claude_desktop_config.json:
{
"mcpServers": {
"arquimedes": {
"command": "uv",
"args": ["--directory", "/path/to/arquimedes", "run", "arquimedes-mcp"]
}
}
}Exposed MCP tools (all read-only; arguments in docs/usage.md):
arquimedes_get_stats: dataset, category, competition, and solution counts
arquimedes_search_problems: full-text search with category, dataset, competition, and min_mohs/max_mohs filters
arquimedes_sample_problems: uniform random draw among problems matching the filters, repeatable with a seed
arquimedes_get_problem: full LaTeX statement, choices, answer, hints, solutions, and optional deepmath reasoning traces by id
From 1.0.0 on, these interfaces only change in backward-compatible ways until a 2.0.0 release:
the v2 problem record schema in docs/schema.md: fields
are not removed or renamed, and their types do not change
the MCP tool names, their arguments, and the shape of their results
the arquimedes CLI commands and flags, and their --json output
the SQLite tables and columns built by arquimedes build
the ArquimedesEngine methods get_stats, search, sample, and
get_problem
New fields, tools, flags, and data fixes can arrive in minor and patch
releases. Corrections to individual records (a wrong answer, a mislabeled
category) are data fixes, not breaking changes. Counts and difficulty.mohs
values can change as records are corrected; mohs is a calibration, not a
measured difficulty. Changes are listed in CHANGELOG.md.
For LLM post-training and RLVR (Reinforcement Learning with Verifiable Rewards), tools/export_splits.py (or uv run arquimedes splits) produces a decontaminated training set and a canonical evaluation benchmark:
uv run arquimedes splits --out-dir splits/Evaluation split (splits/eval.jsonl.gz — 10,533 problems): math test split (4,974), omnimath (2,640), olympiadbench (1,389), core 2023+ contests (931), aops (311), and cemc 2023+ contests (288).
Decontaminated training split (splits/train.jsonl.gz — 972,458 problems): filters out 46,057 unverifiable records and strips 9,915 near-duplicate benchmark leaks detected via 5-gram token shingle overlap across numina, bigmath, core, math, deepmath, and cemc.
Read a problem directly from a shard with the Python standard library:
import gzip, json
with gzip.open("problems/core/shard-00000.jsonl.gz", "rt", encoding="utf-8") as fh:
prob = json.loads(fh.readline())
print(prob["title"], "Mohs:", prob["difficulty"]["mohs"])
print(prob["statement"]) # raw LaTeX with \( \) delimiters
print(prob["answer"]) # {'letter': 'd', 'value': '3+\\sqrt6'}
print(prob["solutions"][0]["text"][:200])Query SQLite + FTS5 directly:
SELECT p.id, p.title, p.difficulty_mohs, p.answer_value
FROM problems_fts f
JOIN problems p ON p.rowid = f.rowid
WHERE problems_fts MATCH '"pigeonhole"'
AND p.difficulty_mohs BETWEEN 5.0 AND 8.5
LIMIT 10;problems/<dataset>/shard-*.jsonl.gz gzipped JSON Lines, one v2 problem record per line
images/<hash>.svg, images/<hash>.jpg 1,219 content-addressed diagram files
data/index.json summary index (counts by dataset, category, competition)
data/problems.sqlite queryable SQLite + FTS5 database (build locally)
arquimedes/ uv-installable CLI and MCP server package
site/ minimalistic interactive web explorer (GitHub Pages)
tools/ converters, shard normalizer, split exporter, DB builder
docs/ schema, usage, and dataset documentationdocs/schema.md: full v2 record reference, shard format, SQLite + FTS5 schema, LaTeX convention, image store
docs/usage.md: CLI, MCP server, SQL & FTS5 queries, reasoning traces, decontaminated splits
docs/datasets.md: per-dataset contents, field notes, category distributions, deduplication rules
Problem data, images, and derived files are available under CC BY 4.0. The code and tools under arquimedes/ and tools/ are available under the MIT License. See LICENSE.
Fetch one problem by its id, as returned by arquimedes_search_problems or arquimedes_sample_problems (e.g. 'prob.ahsme-1950-p10', 'prob.numina-000369'). Returns the full record: LaTeX statement, answer choices, answer, written solutions with progressive hints, difficulty, source, and diagram references. Ids cannot be guessed; an unknown id returns an error, so discover ids with search or sample first.
| Name | Required | Description | Default |
|---|---|---|---|
| problem_id | Yes | Problem id from a search or sample result (e.g. 'prob.ahsme-1950-p10', 'prob.aops-000000'). | |
| include_traces | No | Also include the three long model-reasoning traces stored with deepmath problems (default false; each trace is typically over 10,000 characters). | |
| include_solutions | No | Include written solutions and their hints (default true). Set false to quiz without spoilers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is the id-discovery requirement and the error behavior on unknown ids, plus a preview of what the record contains. It stops short of describing trace/solution cost implications beyond the schema, but this is solid added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the action and then the prerequisites and return shape. No filler; every clause carries information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates the returned record (statement, choices, answer, solutions with hints, difficulty, source, diagrams). Combined with the id-discovery guidance and annotations, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters are already documented in the schema, including the include_traces size warning and the include_solutions spoiler note. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ('Fetch one problem by its id') with the id format exemplified ('prob.ahsme-1950-p10'). It clearly separates this single-record fetch from the sibling list tools arquimedes_search_problems and arquimedes_sample_problems.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states that ids cannot be guessed and that discovery must happen through search or sample first, naming both sibling tools as the route. It also gives the failure condition ('an unknown id returns an error'), which tells the agent when this call will not work.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize what the Arquimedes math problem database holds: 1,038,963 problems across 9 datasets, with problem counts by dataset, category, and competition, and written-solution counts by kind. Call it first to learn which category, dataset, and competition values exist before filtering arquimedes_search_problems or arquimedes_sample_problems. Takes no arguments.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: 'Takes no arguments' and a breakdown of what the summary contains (counts by dataset, category, competition, and solution kind), which is valuable since there is no output schema. It stops short of mentioning response size or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler: the resource scope comes first, then the routing guidance. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-argument, read-only stats tool with no output schema, the description supplies exactly what is missing: the contents of the return payload and the sequencing relative to sibling tools. Nothing an agent needs to call it correctly is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so the baseline is 4; the schema is empty and the description correctly states 'Takes no arguments', leaving no ambiguity about invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('Summarize') plus a precisely scoped resource ('what the Arquimedes math problem database holds'), with concrete content listed: problem counts by dataset/category/competition and written-solution counts by kind. It is immediately distinguishable from the search/get/sample siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to 'Call it first' and names the reason (to learn which category, dataset, and competition values exist) before filtering arquimedes_search_problems or arquimedes_sample_problems. This is a textbook when-to-use plus named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Draw random problems from 1,038,963 competition and olympiad math problems, uniformly among those matching optional filters: category, dataset, competition, contest year, Mohs difficulty range (1.0 to 10.0), multiple-choice only, or with a diagram. Use it to build practice sets, mock contests, or evaluation samples; pass the same seed to repeat a draw. Results are summaries without solutions; pass an id to arquimedes_get_problem for solutions. To find problems about a specific topic or keyword, use arquimedes_search_problems.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | Optional random seed for reproducible sampling. | |
| year | No | Optional contest year filter (e.g. 2024). | |
| limit | No | Number of problems to sample (default 5). | |
| dataset | No | Optional dataset filter. | |
| category | No | Optional subject category filter. | |
| max_mohs | No | Maximum Mohs difficulty rating (1.0 to 10.0). | |
| min_mohs | No | Minimum Mohs difficulty rating (1.0 to 10.0). | |
| competition | No | Optional competition name (e.g. 'IMO', 'USAMO', 'AIME I', 'AMC 10A', 'Putnam'). | |
| has_choices | No | If true, only multiple-choice problems; if false, only free-response/proof problems. | |
| has_diagram | No | If true, only problems with SVG/JPG geometry diagrams. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description still adds real behavioral context beyond them: results are summaries without solutions, sampling is uniform over the filtered pool, and the same seed reproduces a draw (consistent with, not contradicting, idempotentHint=false since unseeded draws vary). It doesn't state pagination or performance characteristics, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tightly packed sentences with no filler: capability and filters first, then use cases, then return shape, then the disambiguation pointer to a sibling. Every sentence carries distinct information and the routing-critical content is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description steps in and explains what comes back (summaries without solutions) and how to get the full content (pass an id to arquimedes_get_problem). Combined with the filter list and seed semantics, an agent has everything needed to call this correctly without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented, and the description's filter list (category, dataset, competition, year, Mohs range, multiple-choice, diagram) largely restates the schema. It adds only marginal semantics, such as the Mohs range being 1.0–10.0 and the seed's repeatability, which the schema field descriptions already convey. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('Draw random problems') plus the exact scale of the corpus (1,038,963 competition/olympiad problems) and the sampling rule (uniform among matching filters). It also distinguishes itself from both siblings by naming arquimedes_get_problem and arquimedes_search_problems, so an agent can route without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit use cases ('build practice sets, mock contests, or evaluation samples') and explicit exclusions with named alternatives: use arquimedes_search_problems for topic/keyword lookup, use arquimedes_get_problem for solutions. The when-to-use and when-not-to-use conditions are both spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find problems by keyword in 1,038,963 competition and olympiad math problems. Full-text search returns problems whose statement or title contains all the query words: a topic, a theorem name such as 'Cauchy-Schwarz', or a LaTeX fragment. Optional filters narrow by category, dataset, competition, and Mohs difficulty (1.0 to 10.0). Results are summaries (id, title, competition, year, difficulty, answer, statement) without solutions; pass an id to arquimedes_get_problem for solutions and hints. To get random problems instead of keyword matches, use arquimedes_sample_problems.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of problems to return (1-50, default 10). | |
| query | Yes | Search keywords, theorem name (e.g. 'Cauchy-Schwarz', 'pigeonhole'), or LaTeX snippet. | |
| dataset | No | Optional source dataset slug filter. | |
| category | No | Optional subject category filter. | |
| max_mohs | No | Maximum Mohs difficulty rating (1.0 to 10.0). | |
| min_mohs | No | Minimum Mohs difficulty rating (1.0 = elementary, 5.0 = AIME, 8.5+ = IMO/Putnam). | |
| competition | No | Optional competition name (e.g. 'IMO', 'USAMO', 'AIME I', 'AMC 12A', 'HMMT February', 'Putnam'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower, and the description adds valuable context: results are summaries only (id, title, competition, year, difficulty, answer, statement) with no solutions, and an id must be passed to arquimedes_get_problem for solutions/hints. It does not mention pagination or rate limits, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tightly packed sentences with no filler; scope and query semantics are front-loaded, followed by output shape and sibling routing. Every clause carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by describing the returned fields and their limits (no solutions). For a 7-parameter read-only search tool, everything an agent needs to invoke it and follow up correctly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds semantic detail the schema lacks: the query matches all words, accepts theorem names like 'Cauchy-Schwarz' or LaTeX fragments, and the Mohs range maps to levels (1.0 elementary, 5.0 AIME, 8.5+ IMO/Putnam). Filter names are largely repeated from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (find/search) and resource (competition and olympiad math problems), plus corpus size. It explicitly differentiates from siblings by naming arquimedes_get_problem for solutions and arquimedes_sample_problems for random retrieval, so an agent can route without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly defines the query semantics (returns problems whose statement or title contains ALL query words) and names the alternative tool for the random-use case. The condition selecting each sibling is stated, leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
arquimedes_get_problem3 fields changedInput schema / properties / include_solutions / descriptionPrevious value: -"Include written solutions and hints (default true)."New value: +"Include written solutions and their hints (default true). Set false to quiz without spoilers."Input schema / properties / include_traces / descriptionPrevious value: -"Include long-CoT R1 reasoning traces for deepmath records."New value: +"Also include the three long model-reasoning traces stored with deepmath problems (default false; each trace is typically over 10,000 characters)."Input schema / properties / problem_id / descriptionPrevious value: -"Unique problem identifier (e.g. 'prob.ahsme-1950-p10', 'prob.aops-000000')."New value: +"Problem id from a search or sample result (e.g. 'prob.ahsme-1950-p10', 'prob.aops-000000')."arquimedes_get_statsarquimedes_samplearquimedes_sample_problemsarquimedes_searcharquimedes_search_problemsarquimedes_statsv0.2.0arquimedes_get_problemarquimedes_samplearquimedes_searcharquimedes_statsScored across 4 tools
Each tool has a clearly distinct purpose: get_stats (metadata survey), search_problems (keyword lookup), get_problem (fetch by id), and sample_problems (random draw). Descriptions explicitly cross-reference each other, telling the agent when to prefer search over sample and vice versa. There is no meaningful overlap that could cause misselection.
All four tools follow a uniform arquimedes_verb_noun pattern (get_stats, search_problems, get_problem, sample_problems) in consistent snake_case. Verb choice maps cleanly to action, and the server prefix is applied uniformly. No convention mixing.
Four tools is compact but each earns its place in a read-only database workflow: discover facets, search, retrieve, and sample. Nothing feels redundant or padded. The scope (browsing a problem corpus) is fully served without bloat.
The surface covers the core read lifecycle: facet discovery via stats, keyword search with filters, id-based full retrieval including solutions/hints, and random sampling. Minor gaps exist (e.g., no bulk multi-id fetch or explicit pagination controls), but these are workarounds an agent can handle. No single-purpose dead ends.
Search Luogu problems, fetch statements, explore problem sets and get practice recommendations.
Search Codeforces problems and inspect public problem metadata through the official Codeforces API.
Search AtCoder problems and fetch public problem statements through MCP.
Read-only search and lookup over the Chertov & Vorobyov physics problem solutions (chertov.org.ua).