Causal Decision Agent

Overview Schema Source Related Servers Discussions Admin

mixed

Read-only

Fit linear mixed-effects models to analyze clustered or nested data, estimating fixed and random effects with selectable covariance structures.

Instructions

Fit a linear mixed-effects model. Validation: certified parity evidence. Assumptions: Continuous outcome, linear in fixed effects; Random effects (intercepts/slopes) normally distributed with the chosen covariance structure; Residuals normal and homoscedastic conditional on random effects; random effects independent of covariates. Pre-conditions: Continuous outcome; Grouping variable (or nested list of grouping levels) for random effects. Failure modes: REML/ML optimizer fails to converge with rich random-slope covariance -> Switch cov_type to 'diagonal' or 'identity', or drop random slopes; Singular covariance (boundary variance estimate) -> Simplify the random-effects covariance or remove the offending random term; Binary or count outcome passed to a linear model -> Use a generalized mixed model for the appropriate family. Alternatives: sp.regress, sp.melogit, sp.feols. Typical minimum N: 200.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`y`	Yes	Dependent variable column.
`tol`	No	Optimiser controls and inference significance level. The defaults use a tight likelihood tolerance so REML variance components and ICC agree with R ``lme4`` / Stata ``mixed`` on parity fixtures.
`alpha`	No	Optimiser controls and inference significance level. The defaults use a tight likelihood tolerance so REML variance components and ICC agree with R ``lme4`` / Stata ``mixed`` on parity fixtures.
`group`	Yes	Grouping variable. Pass a list like ``["school", "class"]`` to estimate a three-level nested model -- the innermost level is used as the cluster for the random slopes/intercept; the outer levels enter as additional random-intercept blocks.
`detail`	No	Payload depth: 'minimal' (~150 tokens) for sub-step calls where only the point estimate is needed; 'standard' (~1K tokens) for diagnostics + coefficient table; 'agent' (~2K tokens, default) adds violations / next_steps / suggested_functions so the LLM can plan its next call without another round-trip.	agent
`method`	No	``'reml'`` (default) or ``'ml'``.	reml
`maxiter`	No	Optimiser controls and inference significance level. The defaults use a tight likelihood tolerance so REML variance components and ICC agree with R ``lme4`` / Stata ``mixed`` on parity fixtures.
`x_fixed`	Yes	Fixed-effect regressors (intercept is added automatically).
`cov_type`	No	Parameterisation of the random-effect covariance matrix G: ``'unstructured'`` (default), ``'diagonal'``, or ``'identity'``.	unstructured
`x_random`	No	Random-slope variables. ``None`` => random intercept only.
`as_handle`	No	If true, cache the fitted result on the server and return result_id + result_uri alongside the JSON payload so a subsequent tools/call can chain without re-running.
`data_path`	Yes	Absolute path or URL to a data file. Supported: .csv / .tsv / .txt (delimited), .parquet / .pq, .feather / .arrow, .xlsx / .xls, .dta (Stata), .json / .jsonl. Schemes: file://, s3://, gs://, https://.
`result_id`	No	Optional handle to a previously-fitted result (returned by an earlier call when as_handle=true). Tools that operate on a fitted object accept this in place of re-supplying data_path + columns.
`data_columns`	No	Optional column projection. Parquet/Feather/Stata loaders honour this for fast partial reads.
`data_sample_n`	No	Optional uniform random subsample size (seed=0, deterministic) — useful on huge panels.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 15, 2026

TDQS

A4/5.0

Behavior1/5

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

Annotations declare readOnlyHint=true, but the description says 'Fit' a model and the as_handle parameter 'cache[s] the fitted result on the server' and returns a result_id for chaining. This implies server-side state mutation, directly contradicting the read-only annotation.

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 fairly long but well-organized into labeled blocks (Validation, Assumptions, Pre-conditions, Failure modes, Alternatives, Typical N). The purpose is front-loaded, and each block serves a distinct decision-making purpose for an agent.

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 15-parameter statistical tool with full schema descriptions and an output schema, the description covers assumptions, preconditions, failure modes, alternatives, and minimum sample size. Return-value details are legitimately left to the output schema.

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 the baseline is 3. The description adds value by linking failure modes to parameter choices (cov_type, x_random) and warning against outcome types that violate the model, which is guidance beyond the schema.

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 first sentence states a specific verb and resource: 'Fit a linear mixed-effects model.' The failure-modes section explicitly distinguishes linear from generalized mixed models for binary/count outcomes, and the alternatives list names sp.melogit and sp.feols, giving clear sibling differentiation.

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?

Pre-conditions are explicit (continuous outcome, grouping variable), failure modes include concrete remediation steps (e.g., switch cov_type to 'diagonal' or 'identity', drop random slopes), and alternatives are named. This provides clear when-to-use and when-not-to-use guidance.

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

Deploy Server