Skip to main content
Glama
youngsu-Kim

macaulay2-mcp

by youngsu-Kim
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

macaulay2-mcp

Why?

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 and the code needs to be fully reviewed. 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.

you   > Compute a Groebner basis of the ideal $I = (x^3 - y, x^4 - z)$ in
        $\mathbb{Q}[x,y,z]$, and a free resolution of $S/I$ with Betti table
AI    > m2_evaluate: R = QQ[x,y,z]; I = ideal(x^3 - y, x^4 - z)
        m2_evaluate: print generators (gb I)
        m2_evaluate: G = res I; betti G
        The Groebner basis is {xy - z, x^2 z - y^2, y^3 - x z^2, x^3 - y}
        and the total Betti numbers are (1, 4, 4, 1).

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

30-second setup

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

On macOS the official uv script (curl -LsSf https://astral.sh/uv/install.sh | sh, installing to ~/.local/bin) works equally well — snippets below use plain uvx, so either install route is fine.

Both commands add a package repository maintained by the Macaulay2 developers (a Homebrew tap / an APT PPA) — needed because macaulay2 is not in Homebrew core and Ubuntu's own package is outdated. Recent Homebrew versions ask to trust a third-party tap before installing from it; trust entries live in ~/.homebrew/trust.json and are reversible at any time: brew untrust --tap Macaulay2/tap (drop trust), brew untap Macaulay2/tap (remove the tap entirely, after brew uninstall macaulay2), or sudo add-apt-repository --remove ppa:macaulay2/macaulay2 (PPA).

Then, one line for your client:

  • 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"]
    }
  }
}

  • Claude Desktop — add to claude_desktop_config.json:

    {
  "mcpServers": {
    "macaulay2": {
      "command": "uvx",
      "args": ["macaulay2-mcp"]
    }
  }
}

    (If that doesn't work, use the absolute path from which uvx.)

  • Gemini CLI — gemini mcp add macaulay2 -- uvx macaulay2-mcp (or add an mcpServers entry to ~/.gemini/settings.json).

  • LM Studio (GUI chat) — one-click "Add to LM Studio" button and setup in Use it in a GUI.

uvx downloads and runs the server in an isolated environment on first use — there is nothing else to install, and no configuration required.

Check that everything is wired up:

uvx macaulay2-mcp selftest
macaulay2-mcp 0.1.1 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.

Try this now

With the server connected, just ask (in Claude Code / opencode / ...). These are real tested prompts; the exact outputs are in examples/example-prompts.md:

  • “Create R = QQ[x,y,z] and I = ideal(x^3 - y, x^4 - z). Compute the Groebner basis and a graded free resolution; show the Betti table.”

  • “What are the dimensions of R and of R/I?” (→ 3 and 1: the monomial curve is a curve)

  • “Load the BoijSoederberg package and decompose the Betti diagram of res I into pure diagrams (decomposeBetti).”

  • “Look up the documentation for hilbertPolynomial and compute it for the twisted cubic (x*z - y^2, y*w - z^2, x*w - y*z).” (→ 3T + 1. Note the lowercase h: M2's CamelCase doc pointer HilbertPolynomial is an empty stub.)

  • “Compute the primary decomposition of ideal(x^2, x*y).”

  • “Work through Macaulay2's official Getting Started examples — the rational quartic monomialCurveIdeal(R,{1,3,4}): dimension, degree, Hilbert polynomial, resolution, Betti table.” (see examples/official-tutorial-run.md)

  • “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.”

  • “Same family, but fan the work out across several subagents as independent batch jobs and collect the results.” (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: examples/groebner-demo.md.

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.

What the server provides

Eight tools, one shared M2 session:

Tool

What it does

m2_evaluate(code, timeout_s?, stop_on_error?)

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.

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_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 (latest stable) 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).

  • 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.

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.

Installing Macaulay2 (details)

OS

Command

macOS (Homebrew)

brew install Macaulay2/tap/macaulay2 (the tap also exposes M2 as an alias; brew trust Macaulay2/tap first on very recent Homebrew)

Ubuntu (official M2 PPA — always latest)

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

Windows

Not supported in v0.1 (macOS and Ubuntu are the tested platforms; WSL2 untested)

If M2 lives in a non-standard place, set M2_BIN=/path/to/M2 in the client's environment for the server. The only other settings are MACAULAY2_MCP_JOURNAL (journal location / off) and MACAULAY2_MCP_OS_ALLOW (comma-separated M2 OS-symbols to unblock); v0.1 intentionally has no others.

Use it in a GUI: LM Studio (macOS, Apple Silicon)

LM Studio (≥ 0.3.17) is itself an MCP host: add this server and local models can call Macaulay2 straight from the chat window — no terminal agent involved. This section targets Apple Silicon Macs with Homebrew; Intel Macs follow the same steps with /usr/local paths, and on Linux the CLI clients above are the documented route.

Prerequisites (one line each):

brew install Macaulay2/tap/macaulay2   # M2 1.26 (LM Studio's GUI env is minimal — see note)
brew install uv                        # provides /opt/homebrew/bin/uvx

Install: switch to the Program tab (right sidebar) → Install → Edit mcp.json → paste:

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

Add MCP Server macaulay2 to LM Studio

If nothing happens, your browser did not hand the lmstudio:// link to the app — copy the JSON snippet above into mcp.json instead. (The https://lmstudio.ai/install-mcp redirector that older docs advertise is currently broken client-side.)

Why the snippet looks different from the CLI ones (each choice is yours to change):

  • "uvx" plain works on current LM Studio (it resolves your shell PATH; same notation your other servers use). If some client fails to launch the server, replace it with the absolute path from which uvx — ~/.local/bin/uvx for the official script install, /opt/homebrew/bin/uvx for brew.

  • No M2_BIN needed — the server looks for Macaulay2 in the standard Homebrew locations automatically, which is exactly what a minimal GUI PATH requires. Non-standard installs: add "M2_BIN": "/path/to/M2" to env.

  • Explicit MACAULAY2_MCP_JOURNAL — GUI-launched servers have an unpredictable working directory, so the journal's default ./.m2-mcp/ would land somewhere mysterious; the snippet pins it to ~/.local/share/macaulay2-mcp/journals (the XDG data standard — the server expands ~ to your home directory, and rm -rf ~/.local/share/macaulay2-mcp deletes everything the server ever wrote). "MACAULAY2_MCP_JOURNAL": "off" also works.

Then enable the server in the Program tab, pick a tool-calling-capable model, and try:

Compute a Groebner basis of the ideal $I = (x^3 - y, x^4 - z)$ in $\mathbb{Q}[x,y,z]$ and print its elements.

You should see a m2_evaluate tool call in the chat's tool activity, then the basis. Measured in our E2E and bench runs: small local models vary a lot at tool calling and at transcribing tables. The server provides built-in M2 idioms, error menus, and an auditable journal (LM Studio appears there as the connected client); these assist weaker models but do not make every model complete every task. If a computation is refused by the OS gate, the same MACAULAY2_MCP_OS_ALLOW env applies here.

The install button and every uvx macaulay2-mcp command go live when the package is published to PyPI; until then, from a checkout you can point the command at uv with --directory /path/to/m2_mcp_project and ["run", "macaulay2-mcp"] as a preview.

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

Symptom

Fix

selftest says Macaulay2 was not found

Install M2 (table above) or set M2_BIN.

Found Macaulay2 1.22.05, but ... only supports 1.26.x

Upgrade: brew tap Macaulay2/tap && brew update && brew upgrade macaulay2 or sudo apt update && sudo apt install macaulay2 (with the M2 PPA added).

Server doesn't appear in the client

Restart the client; run uvx macaulay2-mcp selftest manually to see errors; check claude mcp list (Claude Code) or opencode mcp list (opencode).

A computation times out

Retry with a larger timeout_s (ask your assistant to), or write a script and use m2_run_script. To cancel a running computation while keeping session state, have the assistant call m2_interrupt.

Something about an unbalanced }

Your (or the assistant's) code was missing a closing bracket — the error message says so; just fix and resend.

A .m2-mcp/ folder appeared in your project

That is the audit journal (every M2 exchange, one JSONL file per server run). Add it to .gitignore, relocate with MACAULAY2_MCP_JOURNAL=<dir>, or disable with MACAULAY2_MCP_JOURNAL=off.

BLOCKED: ... gatekeeper refuses '...'

The assistant tried an M2 function that touches the OS (process/file/network). Nothing ran. If you trust the code, set MACAULAY2_MCP_OS_ALLOW=<symbol>,<symbol> in the server's environment and restart the client.

Server won't start in a GUI app (LM Studio, Claude Desktop)

try plain uvx first (recent versions resolve your shell PATH); if it won't start, put the absolute path from which uvx in the command field. For LM Studio you can watch the server's log in the Program tab's server detail view.

Running on Windows

v0.1 supports macOS and Ubuntu only; Windows is untested and unsupported. Open an issue if you need it — demand shapes the roadmap.

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.

  • Memory track (persist and reuse session state across runs).

  • 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

8 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. 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).

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYes
timeout_sNo
stop_on_errorNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/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 state persists, errors appear in output without breaking the session, timeouts restart the session, and stop_on_error changes execution semantics. These are exactly the behavioral traits an agent needs to know and go well beyond basic 'evaluates code'.

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-organized with a lead summary followed by parameter details, and almost every sentence adds value. It loses a point due to a slightly garbled phrase ('sends the code input by input') and a couple of parenthetical asides that slow reading.

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 tool with session persistence, timeouts, error handling, and three parameters, the description is essentially complete. It covers output as text, error inclusion, state persistence, restart behavior, and parameter semantics. Since an output schema exists, the lack of detailed return-value formatting 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 description coverage is 0%, so the description must compensate for all three parameters. It explains code with a concrete example, timeout_s with default, max, and consequence (session restart), and stop_on_error with default, REPL semantics, and line-format requirements. This fully covers what the schema lacks.

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 that the tool evaluates Macaulay2 code in a persistent session and returns its output. This is specific about the verb, resource, and session context, but it does not explicitly mention sibling tools to differentiate them. An agent can still infer the distinction from the 'persistent session' phrasing.

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 rich usage context: it explains persistent state, statement separation, trailing semicolons, timeout behavior, and stop_on_error semantics. However, it never explicitly says when to use this tool versus m2_run_script or other siblings, leaving the timing to inference rather than explicit guidance.

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_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. 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
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 8 tools

Disambiguation4/5

The tools are largely distinct: evaluating code, interrupting, resetting, getting help, running scripts, and managing packages each have clear roles. The only mild overlap is between m2_evaluate, m2_import_file, and m2_run_script, but their descriptions clearly separate persistent-session evaluation, file import into the session, and isolated batch execution.

Naming Consistency4/5

All tools share the m2_ prefix and most follow a verb_noun pattern like run_script, list_packages, load_package, and import_file. Minor deviations include m2_session_reset (object before verb instead of reset_session) and verb-only names like m2_evaluate, m2_interrupt, and m2_help, but the overall style is readable and predictable.

Tool Count5/5

Eight tools is a well-scoped size for an interactive computation server. Each tool covers a necessary operation—evaluation, interrupt, reset, help, script execution, package listing, package loading, and file import—without redundancy or bloat.

Completeness5/5

The tool surface covers the full lifecycle of an interactive Macaulay2 session: evaluate code, interrupt long runs, reset state, load packages, import files, run standalone scripts, and access documentation. There are no obvious dead ends or missing operations for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers