Skip to main content
Glama
youngsu-Kim

macaulay2-mcp

by youngsu-Kim

m2_evaluate

Evaluate Macaulay2 code in a persistent session, returning output while preserving state across calls and including errors without breaking the session.

Instructions

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.

Input Schema

NameRequiredDescriptionDefault
codeYes
timeout_sNo
show_memoryNo
stop_on_errorNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.4
    • addedInput schema / properties / show_memory
      Added value: +{
      +  "default": true,
      +  "title": "Show Memory",
      +  "type": "boolean"
      +}
  2. First observedv0.1.0

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.