| mathA | Run mathematical operations (unified Mathematica-style tool)
═══════════════════════════════════════════════════════════════════════
SymKit's core tool — supports ~25 mathematical operations.
One tool handles derivation, calculation, solving, and transformation.
═══════════════════════════════════════════════════════════════════════
**Supported operations (operation):**
| Category | Operation | Description |
|------|------|------|
| Parse | `parse` | Parse expression and extract symbols |
| Simplify | `simplify` | General simplification |
| | `expand` | Expand polynomial |
| | `factor` | Factorization |
| | `collect` | Collect like terms (requires variable) |
| | `cancel` | Cancel rational function |
| | `apart` | Partial fraction expansion (requires variable) |
| | `together` | Combine over common denominator |
| | `trigsimp` | Trigonometric simplification |
| | `powsimp` | Power simplification |
| | `radsimp` | Radical simplification |
| | `combsimp` | Combinatorial simplification |
| Solve | `solve` | Solve for variable (requires variable) |
| Substitute | `substitute` | Substitute variables (requires substitution dict) |
| Calculus | `diff` | Differentiate (requires variable; order optional) |
| | `integrate` | Integrate (variable, lower/upper optional) |
| | `limit` | Limit (variable, point, direction) |
| | `series` | Series expansion (variable, point, order) |
| ODE | `dsolve` | Solve ODE (variable=function name, with_respect_to=independent variable) |
| Vector | `gradient` | Gradient (variable="x,y,z" comma-separated coordinates) |
| | `divergence` | Divergence |
| | `curl` | Curl |
| | `laplacian` | Laplacian |
| Matrix | `det` | Determinant |
| | `inv` | Inverse matrix |
| | `eigenvals` | Eigenvalues |
| | `eigenvects` | Eigenvectors |
| Transform | `laplace` | Laplace transform (variable=time, with_respect_to=s) |
| | `ilaplace` | Inverse Laplace transform (variable=s, with_respect_to=t) |
| | `fourier` | Fourier transform |
| | `ifourier` | Inverse Fourier transform |
Args:
operation: Operation name (see table above)
expression: Mathematical expression (SymPy or LaTeX format)
variable: Differentiation/integration/solving variable (for vector operations can be comma-separated like "x,y,z")
with_respect_to: Second variable (independent variable for ODE, target variable for transforms)
substitution: Substitution mapping {"var": "replacement", ...}
point: Limit point / series expansion point (default "0")
direction: Limit direction "+-", "+", "-"
order: Differentiation order / number of series terms (default 1)
lower: Definite integral lower bound
upper: Definite integral upper bound
assumptions: Symbolic assumptions ["x is positive", "t is real"]
method: Simplification method "auto", "trig", "radical", "expand_then_simplify"
session: True=record to derivation session, False=stateless computation
description: Description of this step (used when recording to session)
notes: Human insight (used when recording to session)
Returns:
Result dict containing expression, latex, operation
Examples:
# Stateless quick calculation
math("diff", "x**3", variable="x")
→ {"expression": "3*x**2", "latex": "3 x^{2}"}
# Substitute
math("substitute", "m*a", substitution={"m": "2", "a": "9.8"})
→ {"expression": "19.6", ...}
# Laplace transform
math("laplace", "exp(-k*t)", variable="t", with_respect_to="s")
→ {"expression": "1/(k + s)", ...}
# Vector calculus
math("gradient", "x**2 + y**2 + z**2", variable="x,y,z")
→ gradient in vector form
# Solve ODE
math("dsolve", "diff(y,t) - k*y", variable="y", with_respect_to="t")
|
| assumeB | Set symbolic assumptions (affecting subsequent math() calculations)
Assumptions are recorded in MathContext and passed to SymPy, and also written
to the current session's multi-level assumption engine (session level).
Args:
variables: Mapping from variable to properties
e.g., {"x": "positive real", "n": "integer"}
Returns:
All current assumptions
Example:
assume({"x": "positive", "t": "real"})
# Afterwards, math("simplify", "sqrt(x**2)") returns x instead of Abs(x)
|
| show_assumptionsB | Show all symbolic assumptions in the current scope
Returns:
Assumptions in the current MathContext
|
| session_startC | Start a new derivation session
Args:
name: Derivation name
description: Derivation description
domain: Math/physics domain tag
pattern: Derivation pattern
goal: Natural-language goal (optional)
author: Author
Returns:
Session information
|
| session_resumeC | Resume a suspended derivation session
Args:
session_id: Session ID
Returns:
Session status
|
| session_statusA | Get the current session status. |
| session_showA | Show the current derivation state and formula
⚠️ Must be called after each derivation operation to show the user the result!
Args:
show_steps: Whether to show all step history
Returns:
Current formula LaTeX and derivation state
|
| session_explainA | 🗣️ Explain the current derivation in natural language.
Generates a human-readable summary of the derivation so far, including:
- The overall goal (session name/description)
- What formulas were loaded
- What operations were performed and why
- Key assumptions and limitations recorded
- The current result
Args:
level: Detail level — "short", "medium" (default), or "detailed"
focus: Optional aspect to focus on ("assumptions", "steps", "result")
Returns:
Natural-language summary and structured metadata
|
| session_completeC | Complete the derivation and auto-save
Args:
description: Formula description (physical/mathematical meaning)
application_context: Usage context (when to use this formula)
assumptions: Derivation assumptions
limitations: Usage limitations
references: References
tags: Tags
auto_save: Whether to auto-save (default True)
require_target_match: If True, the derivation will only be saved as
completed when the current expression matches the goal target.
Default is False for backward compatibility, but a warning is
still returned if the target is not reached.
Returns:
Complete derivation record
|
| session_rollbackA | Roll back to the specified step
Keep steps up to and including the specified step, and delete steps after it.
After rolling back, you can continue the derivation from that step (taking a different path).
Args:
to_step: Step number to roll back to (1-based); 0 = clear all
Returns:
Rollback result
|
| session_abortA | Suspend the current derivation (session is saved to disk)
Returns:
Operation result
|
| session_add_noteB | Add a human knowledge note to the derivation (non-computational step)
Args:
note: Note content
note_type: "assumption", "limitation", "observation",
"correction", "interpretation", "application", "reference"
related_variables: Related variables
Returns:
Record result
|
| session_listA | List all saved derivation sessions. |
| session_load_formulaA | Load a formula into the current session. Correct workflow for derivation from an external source:
1. formula_search("<concept>", domain="<domain>")
2. formula_get(result["id"], source=result["source"], load_into_session=True)
3. math(..., session=True) to derive or transform
4. session_complete(...) to finalize and save
Args:
expression: Formula or expression string (e.g. "rho * v * L / mu" or
a LaTeX string). For formulas loaded via formula_get, you can
pass formula["sympy_str"] or formula["latex"].
formula_id: Optional custom formula ID.
source: Source label (e.g. "user_input", "scipy", "wikidata").
Returns:
Load result with formula_id, expression and LaTeX.
|
| session_set_goalA | Set a natural-language derivation goal for the current session. Args:
goal: Natural-language goal text.
target_expression: Optional explicit target expression (e.g.
"v = sqrt(2*G*M/R)"). When provided, it overrides the
automatically-extracted target expression.
Returns:
Parsed goal and session status.
|
| session_suggest_formulasA | Suggest formulas that may help reach the current session goal. Args:
top_k: Maximum number of suggestions.
Returns:
List of recommended formulas with rationale.
|
| session_record_stepA | Manually record a derivation step (e.g. a result computed outside the tool). The ``expression`` argument is parsed through the unified parser, which
supports SymPy strings, natural equations (``A = B``), Leibniz derivative
notation (``dX/dY``), Greek/Unicode math, and LaTeX.
Args:
expression: Result expression string (SymPy or LaTeX).
description: Human-readable step description.
operation: Ignored. Manual steps are always recorded as OperationType.CUSTOM
to prevent a user-supplied operation label (e.g. "simplify") from being
falsely reported as automatically verified.
notes: Human insight / observation.
assumptions: Step-specific assumptions.
limitations: Step-specific limitations.
Returns:
Recorded step details.
|
| session_get_stepsA | Return all recorded steps in the current session. Returns:
List of steps with metadata.
|
| session_verify_stepA | Re-verify a single step in the current session. Args:
step_number: 1-based step number. Defaults to -1 (last step).
Returns:
Verification result.
|
| session_verify_sessionA | Verify the entire derivation chain in the current session. Returns:
Summary with total, verified, failed and inconclusive counts.
|
| formula_searchA | Search the local formula library. Retrieve accurate mathematical/physical formulas from the local, editable
YAML library. This is deterministic, fast, and does not require network
access.
The query and domain are normalized automatically, so you can pass
free-form text such as "Navier–Stokes equations" or "fluid_dynamics".
Args:
query: Search keyword
- English name: "Reynolds number", "Arrhenius equation"
- Domain terms: "fluid dynamics", "quantum", "thermodynamics"
source: Data source
- "local": Local YAML library (default, recommended)
- "scipy": Physical constants only (no local search)
- "legacy": Search local, then Wikidata, BioModels, SciPy
- "all": Alias for "legacy" (kept for compatibility)
- "wikidata", "biomodels", "scipy": Legacy source only
domain: Restrict domain (optional)
- "mechanics", "thermodynamics", "electromagnetism"
- "fluid_dynamics", "fluid_mechanics", "quantum_mechanics"
limit: Maximum number of results to return
Returns:
{
"success": true,
"results": [...],
"total": 1,
"query": "navier-stokes equations",
"domain": "fluid",
"sources_searched": ["local"],
"next_steps": [...]
}
Example:
# Search the local library
formula_search("Reynolds number")
# Search by domain
formula_search("diffusion", domain="thermodynamics")
Correct workflow for derivation:
1. formula_search("<concept>", domain="<domain>")
2. formula_get(result["id"])
3. session_load_formula(formula["sympy_str"] or formula["latex"], ...)
4. math(..., session=True) to derive or transform
|
| formula_getA | Get detailed formula information from the local library. Args:
formula_id: Formula identifier (e.g., "reynolds_number")
source: Data source
- "local": Local YAML library (default, recommended)
- "wikidata", "biomodels", "scipy": Legacy sources
load_into_session: If True, load the formula into the current derivation session.
Requires an active session started with session_start().
Returns:
{
"success": true,
"formula": {
"id": "reynolds_number",
"name": "Reynolds number",
"latex": "Re = \frac{\rho v L}{\mu}",
"sympy_str": "rho * v * L / mu",
"variables": {...},
"source": "local"
},
"session_loaded": true
}
Example:
# Get a local formula
formula_get("reynolds_number")
# Get and immediately load into a derivation session
formula_get("reynolds_number", load_into_session=True)
|
| formula_addA | Add or update a formula in the local library. This lets you (and the LLM) extend the local formula collection manually.
Formulas are persisted as YAML files under ``formulas/library/<category>/``.
Args:
id: Unique identifier for the formula (e.g., "custom_drag_force").
Used as the file name and lookup key.
name: Human-readable formula name.
sympy_str: SymPy-compatible expression, e.g. "F_d == 1/2 * rho * v**2 * C_d * A".
latex: LaTeX representation, e.g. "F_d = \frac{1}{2} \rho v^2 C_d A".
variables: Mapping of symbol names to metadata, e.g.
{"rho": {"description": "density", "unit": "kg/m^3"}}.
domain: Optional domain tag (e.g., "fluid_dynamics").
category: Optional category folder name (e.g., "fluid_dynamics").
description: Optional longer description of the formula.
aliases: Optional list of alternative names.
tags: Optional list of tags.
references: Optional list of references / URLs.
library_path: Optional custom library directory. Defaults to ``formulas/library``.
Returns:
{
"success": true,
"formula_id": "custom_drag_force",
"file_path": "formulas/library/fluid_dynamics/custom_drag_force.yaml",
"message": "Formula added to local library."
}
Example:
formula_add(
id="custom_drag_force",
name="Drag force",
sympy_str="F_d == 1/2 * rho * v**2 * C_d * A",
latex="F_d = \frac{1}{2} \rho v^2 C_d A",
domain="fluid_dynamics",
category="fluid_dynamics",
description="Drag force on a body in a fluid.",
variables={
"F_d": {"description": "drag force", "unit": "N"},
"rho": {"description": "density", "unit": "kg/m^3"},
"v": {"description": "velocity", "unit": "m/s"},
"C_d": {"description": "drag coefficient"},
"A": {"description": "reference area", "unit": "m^2"}
},
aliases=["drag force", "fluid drag"],
tags=["drag", "force"],
)
|
| formula_categoriesA | List available formula categories. Get the categories currently present in the local formula library.
Args:
source: Data source
- "local": Local YAML library (default)
- "all": Local + legacy sources
- "wikidata", "biomodels", "scipy": Legacy source only
Returns:
{
"success": true,
"categories": {
"local": ["fluid_dynamics", "mechanics", "thermodynamics"],
"wikidata": [...]
}
}
|
| register_symbolA | 🏷️ Register the semantic meaning of a symbol in the current session.
Args:
name: Symbol name (e.g., "R", "hbar", "k")
meaning: Human-readable meaning (e.g., "Universal gas constant")
domain: Domain this meaning belongs to
unit: Default physical unit
assumptions: Common assumptions (e.g., ["positive"])
aliases: Alternative names for this symbol
Returns:
Registration result
|
| lookup_symbolB | 🔍 Look up the semantic meaning of a symbol.
Args:
name: Symbol name
domain: Optional domain to prefer
Returns:
Symbol meaning and all known definitions
|
| list_domain_symbolsB | 📋 List default symbols for a given domain.
Args:
domain: Domain name
Returns:
List of symbols with meanings and units
|
| check_symbol_conflictsA | ⚠️ Check for ambiguous symbols in the current session.
A conflict occurs when the same symbol name has multiple meanings
or appears in multiple domains.
Returns:
Conflict report with suggested disambiguation
|
| generate_python_functionA | Generate a Python function from VERIFIED derivation steps.
═══════════════════════════════════════════════════════════════════════
⚠️ PREREQUISITE: All expressions must be verified with SymPy-MCP first!
═══════════════════════════════════════════════════════════════════════
Correct workflow:
1. Use SymPy-MCP to derive and verify each expression
2. Use print_latex_expression() to show results to user
3. User confirms the derivation is correct
4. Call this tool with the verified expressions
The generated code assembles the provided expressions into a Python
function; it does not perform new symbolic calculations. The expressions
must already be verified before calling this tool.
Args:
name: Function name (e.g., "calculate_seatbelt_tension")
description: Function docstring description
parameters: List of {"name": str, "type": str, "description": str}
steps: List of {"description": str, "expression": str, "result_var": str}
return_vars: Variables to return
Returns:
dict with keys ``success``, ``code`` (the generated Python function),
``function_name``, ``parameters``, and ``returns``.
Example:
generate_python_function(
name="calculate_tension",
description="Calculate seatbelt tension from collision",
parameters=[
{"name": "M1", "type": "float", "description": "Vehicle 1 mass (kg)"},
{"name": "M2", "type": "float", "description": "Vehicle 2 mass (kg)"},
{"name": "v", "type": "float", "description": "Initial velocity (m/s)"},
{"name": "m", "type": "float", "description": "Person mass (kg)"},
{"name": "k", "type": "float", "description": "Seatbelt constant (N/m)"},
],
steps=[
{"description": "Final velocity after collision",
"expression": "M1 * v / (M1 + M2)",
"result_var": "v_f"},
{"description": "Velocity change",
"expression": "v - v_f",
"result_var": "delta_v"},
{"description": "Maximum tension",
"expression": "delta_v * sqrt(m * k)",
"result_var": "T_max"},
],
return_vars=["v_f", "delta_v", "T_max"]
)
|
| generate_latex_derivationA | Generate LaTeX documentation for a derivation.
Args:
title: Derivation title
steps: List of {"description": str, "latex": str}
final_result: Final result in LaTeX
Returns:
LaTeX document string
|
| generate_derivation_reportC | Generate a complete derivation report in Markdown.
Args:
problem: Problem description
given: Given parameters {"symbol": "value with unit"}
steps: Derivation steps
results: Final results {"symbol": "expression"}
verification: Optional verification status
Returns:
Markdown report
|
| generate_sympy_scriptA | Generate a standalone SymPy script for a computation.
This generates a complete, runnable Python script that can be
executed independently to reproduce the derivation.
Args:
expressions: List of {"name": str, "expr": str, "description": str}
operations: List of operations to perform
{"op": "simplify|solve|diff|integrate", "input": str, ...}
Returns:
Complete Python script
Example:
generate_sympy_script(
expressions=[
{"name": "momentum", "expr": "m1*v1 + m2*v2", "description": "Total momentum"},
],
operations=[
{"op": "solve", "input": "momentum = (m1+m2)*v_f", "for": "v_f"},
]
)
|
| deriveA | 🚀 High-level derivation entry point — start a derivation from a goal.
Args:
goal: Natural-language description of what to derive
given: Base formulas or expressions to load as starting points
assumptions: List of assumptions (e.g., ["rho is positive"])
domain: Math/physics domain (e.g., "fluid_dynamics")
pattern: Derivation pattern. If None, auto-selected from goal.
target_expression: Expected final SymPy expression (optional)
auto_load: If True, load the given formulas into the session
external_sources: External formula sources to include in recommendations
(e.g., ["wikidata", "biomodels", "scipy"] or ["all"]).
Defaults to all sources; network failures are silently ignored.
Returns:
Session info + goal + derivation plan + recommended formulas + next steps
|
| intent_executeA | 🎯 Natural-language intent router — map a request to the right tool chain.
Understands common math/derivation intents and returns the recommended
tool(s) to call. The agent can then execute the recommended tool(s) directly.
Args:
intent: Natural language request
(e.g., "derive NS equations", "simplify this", "verify derivative", "solve for x")
expression: Optional expression to operate on
variable: Optional variable for differentiation/solving
session: Whether to use session-based derivation (default True)
Returns:
intent_type, recommended tool chain, and examples
Example:
intent_execute("derive the temperature corrected elimination rate",
expression="C0 * exp(-k*t)")
|
| list_patternsA | 📋 List all available derivation patterns.
Returns:
Descriptions, typical steps, and suggested operations for each pattern.
|
| tool_categoriesB | 🧰 List SymKit tools organized by category.
Returns:
Categorized tool index with descriptions and examples.
|
| tool_recommendA | 💡 Recommend the best tool(s) for a given task.
Args:
task: Brief description of what you want to do
domain: Optional domain context
Returns:
Recommended tool with rationale and example
|
| assume_for_stepB | 📋 Set assumptions for the current derivation step only.
Args:
*args: Alternating symbol and property strings
(e.g., "x", "positive", "y", "real")
Returns:
Updated step-level assumptions and any conflicts
|
| list_assumptionsA | 📐 List assumptions at a specific level or merged across all levels.
Args:
level: "global", "domain", "session", "step", or None for merged
Returns:
Assumptions at the requested level
|
| check_assumption_conflictsA | ⚠️ Detect conflicts across all assumption levels.
A conflict occurs when a symbol is assigned contradictory properties
(e.g., both positive and negative).
Returns:
Conflict report
|
| clear_step_assumptionsA | 🧹 Clear step-level assumptions.
Useful when moving to a new sub-derivation or branch.
Returns:
Operation result
|
