Skip to main content
Glama
youngsu-Kim

macaulay2-mcp

by youngsu-Kim
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

macaulay2-mcp

Motivation

The goal for the Macaulay2-MCP project is to leverage large-language-models when working with Macaulay2. Especially, it should lower the entry point for newcomers or test a few lines of code. It is still under development; use it at your own risk and share your thoughts with me.

The current version is under testing. This early version is published on GitHub to test other components such as PyPI, LM Studio linking, and Binder.

Related MCP server: scicompute-mcp

Philosophy

  • Nearly all commands and programs below are non-invasive and reversible.

  • The program is not designed to make decisions but inform the users of options.

  • At some point, this MCP should work together with Lean-LSP.

  • It will be updated on an as-needed basis.

Acknowledgments

The project is largely developed under the author's guidance by Qwen 3.8 models hosted at National Research Platform. Also, the author thanks Dr. Mary Thomas and other leaders at the San Diego Supercomputer Center. The author learned a large portion of the skills used in this project from their CyberInfrastructure Professional Development Training Program.

Introduction

Use Macaulay2 from your AI coding assistant.

macaulay2-mcp is an MCP (Model Context Protocol) server that gives Claude Code, opencode, LM Studio, and any other MCP client a persistent Macaulay2 session: ask your assistant to compute Groebner bases, resolutions, Betti tables, primary decompositions, Hilbert polynomials — and it runs the computations in a real M2 kernel, with state (rings, ideals, your definitions) preserved across calls.

Three notations, one kernel — raw M2 syntax, plain English, LaTeX. Each ask is self-contained (paste any one into a fresh session), and the trailing memory line is genuine output (every m2_evaluate result ends with the kernel's resident/peak):

macaulay2-mcp in a real opencode v2 session — 40 s, three README examples run live

you   > compute the Groebner basis of ideal(x^3 - y, x^4 - z) in QQ[x,y,z]
AI    > m2_evaluate: R = QQ[x,y,z]; I = ideal(x^3 - y, x^4 - z)
        m2_evaluate: print generators (gb I)
        The reduced Groebner basis is
        {xy - z, x^2 z - y^2, y^3 - x z^2, x^3 - y}.
        (M2 memory: 118.5 MB resident, peak 103.0 MB)

---

you   > In the polynomial ring in x, y, z over the rationals, let J be
        the ideal generated by x squared plus y squared minus z squared.
        Use macaulay2-mcp to verify: is J prime? What are the dimension
        and degree of the quotient?
AI    > m2_evaluate: S = QQ[x,y,z]; J = ideal(x^2 + y^2 - z^2)
        m2_evaluate: isPrime J; dim (S/J); degree (S/J)
        J is prime; S/J is a surface (dimension 2) of degree 2.
        (M2 memory: 119.3 MB resident, peak 103.0 MB)

---

you   > For the twisted cubic $C \subset \mathbb{P}^3$, whose ideal is
        $I_C = (xz - y^2, yw - z^2, xw - yz)$, compute a free resolution
        of $S/I_C$ with Betti table, and the Hilbert polynomial of $C$,
        in Macaulay2
AI    > m2_evaluate: A = QQ[w,x,y,z]
                     C = ideal(x*z - y^2, y*w - z^2, x*w - y*z)
        m2_evaluate: betti res C
        m2_evaluate: hilbertPolynomial (A^1/C)
        Totals (1, 3, 2) — three quadrics, two linear syzygies — and the
        Hilbert polynomial 3T + 1.
        (M2 memory: 118.5 MB resident, peak 103.0 MB)

M2 syntax helps weak AI models, LaTeX/plain words usually suffice for strong ones — your assistant does the translating; verify its input lines.

Two design notes for local models: on multi-part asks, heavy-thinking models can spend minutes and many self-correcting tool calls — correct but slow (real transcripts: Case study 2 in examples/latex-decomposition-test.md); and a famous object invites answering from memory without calling the tool at all — hence ask 1 speaks M2's own syntax while asks 2 and 3 state it outright ("Use macaulay2-mcp to verify…", "…in Macaulay2"). And note that graded invariants (Betti tables, Hilbert polynomials) are asked only of a homogeneous ideal — where M2's table is minimal and unarguable.

Installation

Prerequisites (one line each):

You need

macOS

Ubuntu

Macaulay2 (latest stable, 1.26)

brew install Macaulay2/tap/macaulay2

sudo add-apt-repository ppa:macaulay2/macaulay2 && sudo apt install macaulay2

uv (runs the server, no install)

brew install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Why a tap/PPA, how to undo it, the alternative uv installer, and the full list of environment settings: docs/installation.md.

Add it to your AI client (harness):

  • Claude Code

    claude mcp add macaulay2 -- uvx macaulay2-mcp

  • opencode — add to your opencode.json (or project opencode.json):

    {
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "macaulay2": {
      "type": "local",
      "command": ["uvx", "macaulay2-mcp"]
    }
  }
}

  • LM Studio (GUI chat) — LM Studio (≥ 0.4.24) is itself an MCP host: Program tab → Install → Edit mcp.json → paste, then enable the server and pick a tool-calling-capable model (start it with the in-chat 1+1 check under Check the MCP below).

    {
  "mcpServers": {
    "macaulay2": {
      "command": "uvx",
      "args": ["macaulay2-mcp"],
      "env": { "MACAULAY2_MCP_JOURNAL": "~/.local/share/macaulay2-mcp/journals" }
    }
  }
}

    The env line just pins the history file to a known folder — see Reading the journal to relocate or turn it off. Setup details and fixes: Troubleshooting.

Check the MCP:

uvx macaulay2-mcp selftest
macaulay2-mcp 0.1.4 self-test

[OK] found Macaulay2: /opt/homebrew/bin/M2
[OK] supported version (1.26.x): 1.26.06
[OK] started session: prompt received
[OK] evaluated 1 + 1: 1 + 1 / o1 = 2

Self-test passed. The MCP server is ready to use.

If anything above fails: M2 not on PATH → set M2_BIN=/path/to/M2 in the client's environment; both prereq commands add third-party repos (reversible — see docs/installation.md); more symptoms and fixes: Troubleshooting.

From inside the chat — checks that your model can reach the server (and wakes a lazily-started one). Paste as your first message:

Before any real math: use the Macaulay2 tool to evaluate 1 + 1, then report
the tool's last line verbatim. If you don't see a Macaulay2 tool, say so
plainly — don't invent an answer.

Examples

With the server connected, just ask (in Claude Code / opencode / ...). All of these are tested prompts:

  • “Create R = QQ[x,y,z] and I = ideal(x^3 - y, x^4 - z). Compute the Groebner basis and a free resolution; show the Betti table, and the dimensions of R and R/I.” (→ basis xy - z, x^2 z - y^2, y^3 - x z^2, x^3 - y; M2 prints totals 1 4 4 1; dims 3 and 1 — the monomial curve is a curve)

  • “Use M2's own library: load the BoijSoederberg package and decompose the Betti diagram of res I into pure diagrams (decomposeBetti); also look up hilbertPolynomial and compute it for the twisted cubic (x*z - y^2, y*w - z^2, x*w - y*z).” (→ a positive sum of 3 pure diagrams; 3T + 1, printed - 2*P₀ + 3*P₁. Note the lowercase h: M2's CamelCase doc pointer HilbertPolynomial is an empty stub.)

  • “Compute the primary decomposition of ideal(x^2, x*y). Then work through Macaulay2's official Getting Started example — the rational quartic monomialCurveIdeal(R,{1,3,4}): dimension, degree, Hilbert polynomial, resolution, Betti table.” (→ (x) ∩ (x², y); quartic: degree 4, Hilbert 4T + 1, totals (1, 4, 4, 1) — straight from the tutorial itself; it works over MCP unchanged)

  • “For the family I_k = (x^(k+2) - y, x^(k+3) - z) in QQ[x,y,z], loop over k = 1..6 and tabulate the reduced Groebner basis sizes and the dimensions of R/I_k — then fan the same family out across several subagents as independent batch jobs and collect the results.” (→ sizes k+3, dim 1 throughout; the batch jobs are real parallel M2 processes)

  • “Here is my mycode.m2 file — import it into the session and call myFunction.” (state is kept between calls)

A full genuine transcript of the first prompt's Groebner/resolution ask: examples/groebner-demo.md. How the server itself handles long runs, stops, parallel batches, and errors: examples/example-prompts.md (§§2–5).

Want to benchmark your own model the way a real user types math? examples/latex-decomposition-test.md gives you two ready prompts, a rubric with known-true answers, and what we measured.

The companion macaulay2-skills repo ships machine-verified M2 1.26 know-how as an Agent Skill (npx skills add youngsu-Kim/macaulay2-skills) — it pairs with this server but is not bound to it, and installs into Claude Code, OpenCode, or LM Studio. Measured here on the three Introduction examples: a thinking-disabled model went from ~22 kernel calls with 8 error/retry events to 5 clean calls, and across all four thinking levels the skill held 3–8 calls with zero errors; its FINDINGS.md carries the full grid.

From your own code (no LLM required)

The server is an ordinary MCP stdio process, so plain Python can drive the same persistent kernel: examples/drive_with_python.py (uv run python examples/drive_with_python.py) shows state surviving between separate tool calls, times each call client-side, and reports kernel memory two ways — the per-call resident/peak line and the on-demand m2_memory() tool, with a computation that visibly moves the peak.

What the server provides

Nine tools, one shared M2 session:

Tool

What it does

m2_evaluate(code, timeout_s?, stop_on_error?, show_memory?)

Evaluate M2 code in the persistent session. State carries over between calls; stop_on_error=True halts at the first error instead of running the rest. Results end with a kernel-memory line (resident + peak; swap when paging) unless show_memory=False.

m2_interrupt()

Stop a running computation: M2 aborts at a safe checkpoint and keeps all earlier definitions (unlike a timeout, which restarts the kernel).

m2_memory()

Report the kernel's resident memory (RSS), peak, swap, pid, and uptime — an unprivileged OS read of the server's own child process; works while a computation runs, so you can watch before deciding to interrupt.

m2_session_reset()

Restart the kernel — a clean slate.

m2_help(topic)

M2 documentation lookup (help "topic").

m2_run_script(path, timeout_s?)

Run a .m2 file in a fresh, isolated M2 process (batch mode; use print for output).

m2_list_packages()

List packages currently loaded in the session.

m2_load_package(name, reload?)

Load a package (e.g. HilbertSchemes, CommutativeAlgebra).

m2_import_file(path)

Import a local .m2 file into the session — newly defined or updated commands are picked up without a restart.

How it works (and the safety limits)

The server keeps one Macaulay2 kernel alive and sends your code to it, exactly like Emacs does. Results, M2 errors, and warnings all come back in the tool output, so your assistant can read and react to them.

  • Version pin. v0.1 supports Macaulay2 1.26.x (the current latest stable at release time) only. Other versions produce a clear error with the upgrade command.

  • Timeout guard. m2_evaluate and m2_run_script are guarded by an author-set default of 120 seconds (raise per call up to 3600) against runaway or infinite computations. A timeout is not an M2 error: the message says so, and explains how to retry with a larger timeout_s (self-contained code, since the session is restarted).

  • Stopping on demand. m2_interrupt sends a real software interrupt (SIGINT): M2 aborts the current computation at a safe checkpoint and the running call returns with error: interrupted — all earlier definitions survive. Only the timeout backstop (for computations that ignore the interrupt) restarts the kernel and loses state.

  • Parallelism. The shared session serializes evaluations by design (one kernel = consistent state; safe for concurrent requests from subagents). Genuine concurrency today: every m2_run_script spawns its own M2 process and multiple jobs run in parallel — e.g. one subagent per slice of an ideal family. First-class job submission (m2_submit_job, status/wait/cancel over a kernel pool) is planned.

  • Errors inform, they don't decide. M2 is a REPL: a runtime error does not stop the remaining lines from running, and there is no rollback. When that happens, the tool result appends an explicit menu — CONTINUE (fix and resend just the failing statement), RESTART (session reset — irreversible, all definitions lost), or INSPECT (see what survived) — and your assistant is instructed to put those choices to you. To prevent the cascade up front, run blocks with stop_on_error=True.

  • Unbalanced input (e.g. a missing }) is rejected up front instead of hanging, and syntax errors that desynchronize the session trigger an automatic restart.

  • OS-access gate. M2 functions that run programs, touch the filesystem, reach the network, or kill the kernel (runProgram, lines, openOut, makeDirectory, installPackage, quit, …) are refused before anything executes — the session stays untouched and the message explains how the user can enable a specific symbol (MACAULAY2_MCP_OS_ALLOW=lines,openOut in the server's environment). The gate is friction against accidents, not a sandbox: M2's value("...") string-evaluation is not blocked (blocking it breaks legitimate metaprogramming). For real isolation, run the server in a container/VM.

  • Audit journal. Every MCP↔M2 exchange is appended to a JSONL file at ./.m2-mcp/session-<UTC>-<pid>.jsonl in your project: the code, M2's output, timings, refused gate attempts, and the MCP client (LLM host) that connected. Relocate with MACAULAY2_MCP_JOURNAL=<dir>, disable with =off; for GUI clients a single central location is recommended, e.g. ~/.local/share/macaulay2-mcp/journals. Add .m2-mcp/ to your .gitignore (the server never reads it back in v0.1; checkpoint/replay is planned). Full guide: Reading the journal.

  • Long results are excerpted. A tool result past ~120 lines / 32 KB comes back as its first 100 and last 10 lines with a notice naming where the full text was saved (the journal); nothing is silently lost, and chats stay readable. Prefer narrowing in M2 (take, drop, smaller examples) over dumping huge results.

  • Memory reporting. Every m2_evaluate result ends with the kernel's resident memory and its peak — pass show_memory=False to omit that line — and m2_memory() answers on demand, including while a long computation is running (a cheap watchdog: watch, then decide whether m2_interrupt is worthwhile). When the kernel starts paging to swap, the line names the swap amount and a note lays out the options; nothing is ever killed automatically. The journal records rss_bytes, peak_rss_bytes and swap_bytes per evaluation regardless of the flag, and a kernel killed by a timeout is probed just before the restart, so its last measurement survives. Peak uses kernel-tracked counters (VmHWM on Linux; footprint's phys_footprint_peak on macOS), not sampling; swap is per-process on Linux, and the system-wide growth since the kernel started on macOS (Apple exposes no unprivileged per-process swap counter).

  • Security. This remains a local tool: your assistant can run arbitrary M2 computation on your machine. Both Claude Code and opencode ask for your approval per tool call by default — keep it that way.

Tested environments

Behaviour (including the golden outputs) is pinned against Macaulay2 1.26 on:

Environment

Machine

Memory relevant to the swap guidance

Development

Apple-silicon Mac, macOS 27

—

CI

GitHub Actions ubuntu-latest (24.04)

16 GB

Binder demo

Container / hosted VM

Low single-digit GB, host-dependent

The OS-access gate

Why some perfectly normal-looking code is blocked, and where this safeguard's honest limits are: the full rationale lives in docs/os-access-gate.md. In one line: M2 functions that run programs, touch the filesystem, reach the network, or kill the kernel are refused before anything executes — and since the check matches words rather than call positions, a plain variable named lines is refused too (rename it, or allowlist the symbol via MACAULAY2_MCP_OS_ALLOW). It is friction against accidents, not a sandbox.

Design principles

  1. Local-first. The server runs on your machine against your Macaulay2 installation. No accounts, no telemetry, no network calls.

  2. Messages inform, never direct. Every message states what it does and whether (and how) it is reversible; we explain decisions instead of telling you to click through them.

  3. Errors carry their own fix. "Not found" ships with install commands; "wrong version" ships with the exact upgrade line; timeouts explain the retry recipe.

  4. Safety limits are explicit. Timeouts are author-set, labeled as such, distinguishable from real errors, and adjustable per call.

Try it in your browser (no install)

Launch on Binder

The companion repo m2-mcp-binder launches a JupyterLab session (first launch ~2–4 min) where a plain Python notebook drives this very server over MCP — a zero-install way to see the tools in action.

Troubleshooting

Symptoms and fixes: docs/troubleshooting.md.

Todos/Plans

  • Remote/HTTP mode (Streamable HTTP + API key) so the server can be hosted and connected to services such as ChatGPT web; deployment recipes (Docker, Cloudflare Tunnel).

  • Multi-user sessions, support for older/newer M2 versions, MCP prompts for common workflows (e.g. "analyze an ideal"), a package availability search, and more — after community feedback.

  • Session-state persistence across restarts.

  • Dedicated dataset to train an LLM.

Feedback

Please file issues and PRs on GitHub. Once the software has stabilized, it is expected to be announced in the Macaulay2 Zulip first.

License

This program is free software under the GNU General Public License v3 or later: use it freely, including commercially — but if you distribute it, or a program built on top of it, the same freedoms must travel with your copy.

Available Tools

9 tools
m2_evaluateA

Evaluate Macaulay2 code in the persistent session and return its output.

    State (rings, variables, ideals, ...) persists across calls. M2 errors
    are included in the returned text and do not break the session.
    Separate statements with newlines: a trailing ";" suppresses that
    statement's result (use an explicit "print" to force output).

    Args:
        code: Macaulay2 code, e.g. "R = QQ[x,y,z]

I = ideal(x^3 - y, x^4 - z) print generators (gb I)" timeout_s: Author-set safety limit (default 120, max 3600). Raise it for heavy computations (large Groebner bases, Hilbert polynomials, ...). On timeout the session is restarted, so the retried code must include all setup again. With stop_on_error=True the budget applies PER INPUT. stop_on_error: Default False = REPL semantics (an error does not stop later lines from running). True sends the code input by input and halts at the first error, leaving later inputs unexecuted. Requires each line to be a self-contained statement (do not break a line after a binary operator). show_memory: True (default) appends one line naming the kernel's memory (resident + peak; swap when it is paging) to the result; False omits it. The values are recorded in the journal either way.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYes
timeout_sNo
show_memoryNo
stop_on_errorNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior5/5

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

No annotations exist, so the description carries the full burden and does so: state persists across calls, M2 errors are returned in the text without breaking the session, a trailing ';' suppresses output, timeouts restart the session (losing state), and stop_on_error changes REPL semantics. These are exactly the non-obvious behaviors an agent must know before invoking.

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

Conciseness4/5

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

Well front-loaded: operation, persistence, then per-argument notes. The multi-line code example is the longest element but is genuinely instructive for a code-evaluation tool; slightly dense overall but every section is load-bearing.

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

Completeness5/5

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

An output schema exists so return-value explanation is unnecessary, and the description still covers persistence, error handling, timeout/restart behavior, and all arguments. Nothing material is missing for correct invocation.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate — and it documents all four parameters in depth: code syntax and examples, timeout_s default/max/restart consequence, stop_on_error semantics and its line-continuation constraint, and show_memory's output effect and journal recording.

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

Purpose4/5

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

It states a specific verb+resource: evaluate Macaulay2 code in a persistent session and return output. That cleanly separates it from m2_memory, m2_session_reset, etc., but it never distinguishes itself from the obvious sibling m2_run_script, which an agent may reasonably confuse it with.

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

Usage Guidelines3/5

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

The description gives situational hints (raise timeout for heavy computations, use stop_on_error for halting on errors) but never says when to choose this tool over m2_run_script or m2_run_script's stateless variant. Usage is implied rather than instructed.

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

m2_helpA

Look up Macaulay2 documentation for a function, class, or concept.

Args: topic: Documentation entry point, e.g. "groebnerBasis", "resolution", "HilbertPolynomial", "Package".

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It communicates a read-only documentation lookup, but does not mention what the output looks like, whether it returns text or opens a viewer, or whether any side effects (e.g., session state changes) occur. For a simple help tool this is a minor gap, but it is still undisclosed behavior.

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

Conciseness5/5

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

The description is compact and front-loaded with the core purpose, followed immediately by a parameter explanation with examples. Every sentence contributes information, and there is no redundant or filler content.

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 single-parameter help tool, the description covers the main needs: what it does and what the argument means. It lacks explicit return-value information, but the presence of an output schema partially fills that gap. Overall it is nearly complete for such a simple tool.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate. It defines the only parameter 'topic' as a 'documentation entry point' and gives concrete examples ('groebnerBasis', 'resolution', 'HilbertPolynomial', 'Package'). This adds meaningful guidance beyond the bare schema, though it does not enumerate all valid entries or format rules.

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 description states a specific verb ('Look up'), a clear resource ('Macaulay2 documentation'), and the scope of topics ('function, class, or concept'). This unambiguously distinguishes it from siblings like m2_evaluate or m2_run_script, which are about execution rather than documentation.

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

Usage Guidelines3/5

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

Usage is implied by the purpose: use this when you need documentation for a Macaulay2 symbol. However, the description does not explicitly state when to prefer this over alternatives, nor does it mention any exclusion criteria or context such as 'use m2_list_packages to discover available packages'.

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

m2_import_fileA

Import a local .m2 file INTO the persistent session.

Reads the file and evaluates its contents in the session, so newly defined or updated functions/variables become available immediately — no session restart needed. This is the M2 equivalent of what Emacs does when you "load" a file into a running kernel. Re-importing re-defines the file's symbols.

Args: path: ABSOLUTE path to the .m2 file to import.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

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

With no annotations provided, the description carries the behavioral disclosure burden. It clearly discloses that the file is read and evaluated, that new/updated definitions become available immediately, that no restart is needed, and that re-importing redefines symbols. This is meaningful behavioral context beyond the schema.

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

Conciseness4/5

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

The description is well structured and front-loaded with the core purpose, followed by behavioral details and a clear Args section. The Emacs analogy adds helpful context without bloating the text, though it could be trimmed slightly.

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 simple one-parameter tool with an output schema, the description provides enough information about what the tool does, how it behaves, and what the parameter means. It does not discuss failure modes or return values, but the output schema handles return-value expectations and the operation is straightforward.

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

Parameters5/5

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

Schema description coverage is 0%, and the schema only names the parameter 'path' as a string. The description compensates fully by specifying that path is an ABSOLUTE path to the .m2 file to import, adding essential semantic meaning for correct invocation.

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

Purpose4/5

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

The description clearly states the tool imports a local .m2 file into the persistent session and evaluates its contents, which is a specific verb and resource. It does not explicitly contrast with siblings like m2_run_script or m2_load_package, but the persistent-session framing and Emacs load analogy give enough differentiation.

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

Usage Guidelines3/5

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

The description implies the intended use case: when you need to load a .m2 file into the running session without restarting. It does not state when to avoid this tool or explicitly name alternatives, so the usage guidance is present but only implied.

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

m2_interruptA

Interrupt the Macaulay2 computation currently running in the session.

Use this when the user wants to cancel or stop a long-running m2_evaluate. It sends a software interrupt (SIGINT), which M2 handles at safe checkpoints: the running m2_evaluate call returns with an "error: interrupted" message, and everything defined by statements that completed BEFORE the interrupted one stays available — the session does not restart.

If nothing is running, this is a harmless no-op. In the rare case of a computation that ignores the interrupt (deep engine loops), the running m2_evaluate's own timeout_s remains the backstop: it kills and restarts the kernel on expiry.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the full burden, and it does exceptionally well. It discloses the SIGINT mechanism, safe-checkpoint handling, the returned error message, preservation of completed statements, the no-op behavior when nothing is running, and the timeout backstop that kills and restarts the kernel. This is comprehensive behavioral disclosure.

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

Conciseness5/5

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

The description is front-loaded with the core purpose, then covers usage, behavior, edge cases, and fallback behavior in a compact way. Every sentence adds meaningful information without redundancy.

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

Completeness5/5

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

For a zero-parameter interrupt tool with no annotations, the description is fully complete. It covers the normal case, the no-op case, the failure case, and the session-state implications, leaving an agent with everything needed to invoke and predict the outcome. An output schema exists, so return-value details need not be spelled out here.

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

Parameters4/5

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

The tool has zero parameters, so the input schema is complete and there is no parameter semantics for the description to add. The baseline of 4 applies because no compensation is needed.

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 description opens with a specific verb and resource: 'Interrupt the Macaulay2 computation currently running in the session.' It is immediately clear what the tool does and how it differs from siblings like m2_evaluate or m2_session_reset.

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?

The description explicitly states when to use it: 'Use this when the user wants to cancel or stop a long-running m2_evaluate.' It also clarifies the no-op case. It does not explicitly name alternative tools or say when not to use it, but the usage context is clear enough.

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

m2_list_packagesA

List the Macaulay2 packages currently loaded in the session.

Returns the package names, e.g. {Varieties, Complexes, PrimaryDecomposition, Core, ...}.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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

No annotations are provided, so the description carries the behavioral disclosure burden. It clearly indicates this is a read-only listing operation and specifies the output shape (package names). It does not discuss errors or empty sessions, but the behavior is sufficiently transparent for this simple tool.

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

Conciseness5/5

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

Every sentence earns its place: the first states what the tool does, and the second gives a concrete example. The description is short, front-loaded, and free of filler.

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

Completeness5/5

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

For a parameterless list operation with an output schema, the description is complete. It tells the agent what is listed, where it is listed from, and what the return value looks like.

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

Parameters4/5

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

The tool has zero parameters, so there is nothing for the description to clarify here. The schema already documents this fully, and the baseline for a zero-parameter tool is appropriately 4.

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 description uses a specific verb ('List') and resource ('the Macaulay2 packages currently loaded in the session'), making the tool's function immediately clear. The example output further disambiguates the return value. It is clearly distinct from siblings like m2_load_package or m2_evaluate.

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?

The description establishes clear context: it reports session state rather than performing an action. It does not explicitly name alternatives or state when not to use it, but for a simple introspection tool this is not a significant gap.

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

m2_load_packageA

Load a Macaulay2 package into the session.

Packages stay loaded until the session is reset (M2 has no unload operation). Loading an already-loaded package is a harmless no-op: the tool reports that and changes nothing. Use reload=True ONLY when the package's source on disk changed and must be re-read (M2's reload machinery is fragile for packages with dependencies).

Args: name: Package name as it appears on the M2 search path, e.g. "HilbertSchemes", "CommutativeAlgebra", "BoijSoederberg". reload: Re-read the package from disk even if already loaded (package-development workflow; leave False otherwise).

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes
reloadNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden and does so well. It discloses that packages persist until session reset, that there is no unload operation, that reloading an already-loaded package is a harmless no-op, and that M2's reload machinery is fragile for dependent packages.

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

Conciseness5/5

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

The description is well-structured with a clear first sentence, lifecycle context, targeted reload guidance, and an Args section. Every sentence adds useful information without repetition or filler.

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

Completeness5/5

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

Given the tool's session-state side effects, the description covers the essential behavioral nuances: persistence, no-op behavior, reload semantics, and dependency fragility. An output schema exists, so not detailing return values is acceptable.

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

Parameters5/5

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

Schema coverage is 0%, so the description fully compensates. It explains that name must match the M2 search path and gives concrete examples, and it clarifies reload's meaning, default-appropriate usage, and the package-development workflow where it is needed.

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 description opens with a specific verb and resource: "Load a Macaulay2 package into the session." It clearly distinguishes this tool from siblings by explaining package lifecycle behavior (no unload, no-op when already loaded), making its purpose unambiguous.

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?

The description gives explicit usage guidance for the reload parameter: use reload=True only when the disk source changed, leave False otherwise. It doesn't explicitly name alternatives among sibling tools, but the unique loading purpose and session-persistence note make the intended context clear.

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

m2_memoryA

Report the persistent Macaulay2 kernel's memory: RSS, peak, swap, pid, uptime.

Reads the operating system's bookkeeping for the kernel child process — an unprivileged read; nothing is sent to M2 and the session is untouched. Peak comes from kernel-tracked counters (no sampler involved); swap is M2's own swapped pages on Linux, or the system-wide swap growth since this kernel started on macOS (no unprivileged per-process counter exists there). The probe is lock-free: call it WHILE a long m2_evaluate runs to watch memory live before deciding whether m2_interrupt is worthwhile. RSS reads as a high-water mark because M2 rarely returns freed pages to the OS.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.9/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses that the probe is an unprivileged read, sends nothing to M2, leaves the session untouched, is lock-free, and explains how peak and swap values are obtained on Linux versus macOS.

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

Conciseness5/5

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

The description is front-loaded with the tool's purpose and return metrics, then uses remaining space for genuinely useful behavioral context. Platform-specific swap details and the lock-free note each earn their place by helping the agent interpret the output.

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

Completeness5/5

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

An output schema exists, so the description does not need to explain return formatting, yet it still adds necessary interpretation guidance such as RSS being a high-water mark and swap differences across platforms. It is complete for a zero-parameter, read-only diagnostic tool.

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

Parameters4/5

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

The tool takes zero parameters, so there are no parameter semantics to clarify in the schema. The description appropriately omits parameter discussion, though with no parameters there is nothing extra it could add.

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 description names a specific verb and resource: report the persistent Macaulay2 kernel's memory. It immediately lists the five metrics returned (RSS, peak, swap, pid, uptime), making it unmistakably distinct from siblings like m2_evaluate, m2_interrupt, and m2_session_reset.

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

Usage Guidelines5/5

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

It gives explicit when-to-use guidance: call it while a long m2_evaluate runs to watch memory live. It also routes the agent toward the alternative decision point by saying this helps decide whether m2_interrupt is worthwhile.

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

m2_run_scriptA

Run a .m2 file in a FRESH, isolated Macaulay2 process.

Does not touch the persistent session (and its state is not visible afterwards). Use for long or self-contained computations, or when a repeated m2_evaluate timeout suggests a heavy job. This is batch mode: only explicit print output is returned — the script must print its own results.

Args: path: ABSOLUTE path to the .m2 file, e.g. "/tmp/compute.m2". timeout_s: Author-set safety limit (default 120, max 3600). On timeout the process is killed and any partial output is returned.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
timeout_sNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A5/5.0
Behavior5/5

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

With no annotations provided, the description carries the full behavioral disclosure burden. It fully discloses the isolated-process semantics, non-persistence of state, batch-mode output constraints, the requirement that the script print its own results, and timeout behavior including process termination and partial output return.

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

Conciseness5/5

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

The description is concise and well-structured: the primary purpose is front-loaded, followed by usage context, behavioral details, and then clearly separated parameter explanations. Every sentence adds useful information without redundancy.

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

Completeness5/5

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

Given only two simple parameters and no annotations, the description is complete enough for an agent to invoke the tool correctly. It covers path requirements, timeout semantics, isolation behavior, output expectations, and the appropriate use case, leaving no critical gap.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate, and it does. It explains path must be an absolute path with an example, and fully documents timeout_s as an author-set safety limit with default 120, max 3600, and the consequence of a timeout.

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 description states a specific verb and resource: 'Run a .m2 file in a FRESH, isolated Macaulay2 process.' It also clearly differentiates from sibling tools by emphasizing the isolated process and batch-mode behavior, so an agent can distinguish it from m2_evaluate and the other related tools.

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

Usage Guidelines5/5

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

The description explicitly says when to use this tool: 'Use for long or self-contained computations, or when a repeated m2_evaluate timeout suggests a heavy job.' It also implies when not to use it by noting it does not touch the persistent session and that output is only explicit print output, which gives clear routing guidance.

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

m2_session_resetA

Restart the Macaulay2 kernel, discarding ALL session state.

Use before starting a fresh line of computation, or whenever the session seems corrupted. After a reset, rings and definitions from earlier calls no longer exist.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly warns that resetting discards ALL session state and explicitly states that rings and definitions from earlier calls no longer exist. This accurately conveys the destructive nature of the operation, which is the most critical behavioral trait for an agent to know.

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

Conciseness5/5

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

Three sentences with zero waste: the first sentence states the action and its primary consequence, the second gives usage triggers, and the third reinforces the permanent loss of prior state. It is front-loaded and every sentence earns its place.

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

Completeness5/5

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

For a zero-parameter, self-contained reset tool with an output schema, the description covers the action, when to use it, and the key side effect. Nothing an agent needs to decide whether to invoke this tool is missing.

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

Parameters4/5

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

The tool has zero parameters and the schema is empty, so there are no parameter semantics to clarify. Baseline 4 applies because nothing is missing; the description naturally requires no parameter discussion.

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 description uses a specific verb 'Restart' with a clear resource ('the Macaulay2 kernel') and explicitly states the core effect: discarding ALL session state. It is immediately distinguishable from siblings like m2_evaluate or m2_interrupt because it focuses on kernel lifecycle, not computation or interruption.

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?

The description provides concrete when-to-use guidance: 'before starting a fresh line of computation' or 'whenever the session seems corrupted.' It does not explicitly name alternatives or exclusion cases, but the use cases are clear enough to route an agent correctly, especially with sibling names providing context.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.4
    • Changedm2_evaluate1 field changed
      • addedInput schema / properties / show_memory
        Added value: +{
+  "default": true,
+  "title": "Show Memory",
+  "type": "boolean"
+}
    • Addedm2_memory
  2. 8 tool updatesv0.1.0
    • First observedm2_evaluate
    • First observedm2_help
    • First observedm2_import_file
    • First observedm2_interrupt
    • First observedm2_list_packages
    • First observedm2_load_package
    • First observedm2_run_script
    • First observedm2_session_reset
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.4/5.0

Scored across 9 tools

Disambiguation5/5

Each tool targets a clearly distinct operation: persistent evaluation vs. isolated script execution vs. file import, package management, help, memory, and interrupt. The few potential overlaps (e.g., m2_evaluate vs. m2_import_file) are well-separated by input source and session-state semantics.

Naming Consistency4/5

All tools use the same m2_ prefix and snake_case, making the set highly readable. Minor deviations from a strict verb_noun pattern appear in m2_session_reset (noun_verb) and single-word tools like m2_help, m2_memory, and m2_interrupt.

Tool Count5/5

The 9 tools are well-scoped for controlling a Macaulay2 session. Each tool covers a discrete need (execute, batch, import, packages, help, reset, memory, interrupt) without redundancy.

Completeness5/5

The surface covers the full session lifecycle: code evaluation, batch execution, file import, package listing/loading, documentation lookup, kernel reset, memory monitoring, and interruption. No obvious gaps exist for the stated domain, and noted M2 limitations (e.g., no unload) are appropriately handled.

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers