Skip to main content
Glama
JGCoelho

simple-sage-mcp

by JGCoelho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

exec

Execute Sage/Python code in a persistent kernel session and return stdout plus the last expression's repr, enabling stateful computations and manageable long-running jobs.

Instructions

Run Sage/Python in the long-lived kernel: stdout, then the repr of the last expression (or '(no output)'). Code runs on the kernel's main thread, one job at a time, so cysignals Sage code works; state persists per session. timeout_s is NOT a computation limit: on expiry you get the partial output and a job id, and the job keeps running (collect it with poll). timeout_s=0 returns at once. A submitted job waits behind the running one ("[queued: another job is running]"); if that one holds the GIL the submit itself is refused after ~10 s ("[kernel busy ...]", the job was not submitted) -- check status or interrupt, then retry.

Input Schema

NameRequiredDescriptionDefault
codeYesCode to execute.
sessionNoNamespace to run in. State persists per session between exec calls.default
preparseNoApply the Sage preparser (2^10 -> 1024, R.<x> = ...). false runs raw Python (2^10 is XOR).
timeout_sNoSeconds to wait for the result; 0 = return at once. Never cancels the job.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.3/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 it well: discloses single-threaded one-job-at-a-time execution, per-session state persistence, that timeout is never a cancellation, partial-output-plus-job-id semantics, queueing behavior, and the ~10s GIL refusal message. This is exactly the operational context an agent needs before calling.

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?

Front-loaded with what the tool does and what it returns, then behavioral detail. Dense but nearly every clause carries operational information; the long em-dash-heavy paragraph is slightly harder to scan than separate sentences would be.

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?

No output schema exists, yet the description spells out the return format (stdout, last-expression repr, or '(no output)'). Combined with the timeout/queue/retry semantics, nothing an agent needs in order to call or recover from 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?

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: timeout_s is explicitly not a computation limit and yields partial output plus a job id, and session persistence across calls is reinforced. It does not further explain preparse beyond the schema.

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?

States a specific verb and resource ('Run Sage/Python in the long-lived kernel') and even defines the output shape (stdout then last-expression repr). It distinguishes itself from poll/status/interrupt in the failure path, though it never contrasts itself with the run_file sibling, keeping it short of a full 5.

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?

Gives concrete conditions: timeout_s=0 returns at once, on expiry you get partial output plus a job id and use poll to collect, and what to do when the kernel is busy ('check status or interrupt, then retry'). It lacks explicit guidance on when to prefer run_file over exec.

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

Deploy Server

Other Tools