Causal Decision Agent

Overview Schema Source Related Servers Discussions Admin

ppmlhdfe

Read-only

Estimates pseudo-Poisson maximum likelihood models with high-dimensional fixed effects, producing robust and clustered standard errors for panel and gravity analyses.

Instructions

Pseudo-Poisson Maximum Likelihood with high-dimensional fixed effects. Validation: certified parity evidence. Do NOT use when: vce='conley' on more than ~20,000 rows -- dense O(n^2) memory (see cost); vce='conley' with high-dimensional fixed effects -- the conleyreg-matching construction is dummy-based and raises MethodIncompatibility past 1,000 dummy columns; use cluster= (CRV1) there. Cost: IRLS is linear in n. vce='conley' builds the FE-as-dummies design plus dense n x n great-circle distance and kernel matrices (glm_conley_vcov) -- ~0.8 GB at n=10,000 and ~80 GB at n=100,000 -- and it refuses designs with >= n or > 1,000 dummy columns. Use cluster= (CRV1) instead at that scale.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`x`	No	Independent variable names (alternative to formula).
`y`	No	Dependent variable name (alternative to formula).
`ssc`	No	Small-sample factor applied to the heteroskedasticity-robust sandwich. ``"stata"`` multiplies by ``N/(N-1)``, the Stata ``glm``/``ppmlhdfe vce(robust)`` convention (matches ``ppmlhdfe`` at machine precision). ``"fixest"`` multiplies by ``(N-1)/(N-K)`` with ``K`` counting the slopes plus the absorbed fixed-effect levels (minus one per additional fixed-effect dimension for collinearity), the ``fixest::fepois`` default ``ssc(adj = TRUE, fixef.K = "full")``. ``"none"`` applies no factor. The three differ by less than ``sqrt(N/(N-K))`` and are documented, not competing, conventions; point estimates are unaffected. Clustered variances keep the ``G/(G-1)`` factor.	stata
`tol`	No	Convergence tolerance.
`vce`	No	Canonical SE-menu keyword. ``"robust"``/``"hc1"``/``"hc0"`` alias the ``robust=`` parameter. ``"wild"`` (with ``cluster=``) runs the boottest-convention score wild cluster bootstrap on the FE-absorbed design -- exact at any FE dimensionality (the weighted-FWL reduction of the score numerator is exact) and byte-identical to ``sp.fepois(vce="wild")`` on low-dimensional FE. ``"CR2"``/``"CR3"``/``"jackknife"`` (with ``cluster=``) compute the clubSandwich glm bias-reduced SEs on the FE-as-dummies design (guarded against high-dimensional FE).
`seed`	No	RNG seed for sampled (non-enumerated) wild draws.
`alpha`	No	Significance level for confidence intervals.
`absorb`	No	Fixed effects to absorb, e.g. ``"origin + destination + year"``. Overrides any FE specification in the formula.
`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
`robust`	No	Default is robust SE (as in Stata's ppmlhdfe). Options: "robust"/"hc1" (sandwich with the ``ssc`` small-sample factor), "hc0" (sandwich, no factor), "nonrobust".	robust
`cluster`	No	Variable name for clustered standard errors (recommended for gravity models, e.g. cluster on country-pair). A pair ``cluster=["a", "b"]`` requests two-way clustering (Cameron-Gelbach-Miller 2011 inclusion-exclusion with the single ``G_min/(G_min-1)`` small-sample factor -- byte-identical to Stata ``ppmlhdfe ..., cluster(a b)``).
`formula`	No	Model formula. Fixed effects can be specified via ``\|``: ``"trade ~ dist + contig \| origin + destination + year"``
`maxiter`	No	Maximum IRLS iterations.
`weights`	No	Weight variable name.
`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`	No	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.
`wild_reps`	No	Replications for ``vce="wild"`` (enumerates the 2^G grid when ``2**G <= wild_reps``).
`conley_lat`	No	conley_lat parameter (Optional[str]).
`conley_lon`	No	conley_lon parameter (Optional[str]).
`separation`	No	If True, check for separation (perfect prediction of zeros) and warn. Observations causing separation are not dropped automatically.
`data_columns`	No	Optional column projection. Parquet/Feather/Stata loaders honour this for fast partial reads.
`conley_cutoff`	No	conley_cutoff parameter (Optional[float]).
`data_sample_n`	No	Optional uniform random subsample size (seed=0, deterministic) — useful on huge panels.
`wild_weight_type`	No	Wild weight distribution.	rademacher

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.4/5.0

Behavior5/5

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

Beyond the readOnlyHint annotation, the description discloses substantial behavioral traits: dense O(n^2) memory for vce='conley' with concrete GB estimates, refusal when designs exceed n or 1,000 dummy columns, MethodIncompatibility with high-dimensional FE, and linear IRLS cost in n. This is rich, concrete behavioral context that annotations do not provide.

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 front-loaded with purpose and then gives actionable exclusions and cost information in a compact form. However, 'Validation: certified parity evidence' is cryptic and not clearly actionable, and the 'use cluster= (CRV1)' recommendation appears twice, creating minor redundancy.

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?

Given the tool's complexity and the very detailed input schema, the description adds the most safety-critical information: memory usage, scale limits, and incompatibility warnings. It does not explicitly compare with fepois/poisson for ordinary PPML use, but combined with the schema and output schema, an agent has enough context to invoke this tool correctly in most cases.

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 100%, so the baseline is 3. The description adds useful meaning for vce='conley' and cluster= by explaining their cost, refusal behavior, and the recommended CRV1 alternative. This helps an agent choose among parameter values beyond what the schema alone states.

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 names the estimator and resource — Pseudo-Poisson Maximum Likelihood with high-dimensional fixed effects — so an agent knows what model this tool fits. It also differentiates from plain poisson/glm siblings by emphasizing high-dimensional FE, but it does not state an explicit action verb such as 'fits' or 'estimates' and does not contrast with closely related tools like fepois.

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 gives explicit 'Do NOT use when' conditions for vce='conley' on large data and with high-dimensional fixed effects, with concrete reasons and a prescribed alternative: use cluster= (CRV1). This is exactly the kind of conditional routing guidance an agent needs. It does not cover every possible sibling comparison, but the exclusions are specific and actionable.

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

Deploy Server