Causal Decision Agent

Overview Schema Source Related Servers Discussions Admin

sun_abraham

Read-only

Fixes contamination in two-way fixed-effects event-study coefficients by estimating cohort-specific interaction-weighted dynamic treatment effects.

Instructions

Sun-Abraham (2021) interaction-weighted event-study. Fixes the contamination in dynamic event-study TWFE coefficients from other relative-time bins by using cohort-specific interaction weights. Canonical companion to Callaway-Sant'Anna for event studies. Validation: certified parity evidence. Do NOT use when: all units adopt treatment simultaneously -- the cohort x relative-time interactions collapse; use sp.did(method='2x2'); cohorts are very small (a handful of units each) -- interaction-weighted estimates become noisy and the cohort-share weights unstable. Cost: Builds a saturated cohort x relative-time interaction design: columns grow as (cohorts x event-time window), so a wide window on a many-cohort panel produces a large dense design matrix. Trim via event_window=. Assumptions: Parallel trends across cohorts; No anticipation within event_window lead horizon; SUTVA. Pre-conditions: panel with unit x time x outcome; g is the first-treatment period (int), 0 / NaN for never-treated; >= 2 pre-periods per cohort for event-study leads. Failure modes: No never-treated cohort when control_group='nevertreated' -> Pass control_group='notyettreated' or add never-treated units; Pre-tren...

Input Schema

TableJSON Schema

Name	Required	Description	Default
`g`	Yes	First-treatment period (0 = never-treated)
`i`	Yes	Unit identifier
`t`	Yes	Time period column
`y`	Yes	Outcome variable column name or outcome array.
`alpha`	No	Significance level for confidence intervals and tests.
`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
`cluster`	No	Cluster variable (defaults to i)
`pretest`	No	Report the joint pre-trend Wald test ('joint') or skip it ('none').	joint
`weights`	No	Unit-level sampling/population weights omega. Enters the fixed-effect projection, the least-squares solve, the cluster-robust variance, and the interaction weights (which become shares of omega-mass). Changes the target parameter, not the precision.
`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.
`covariates`	No	Covariate matrix, DataFrame, or column names.
`aggregation`	No	Headline summary convention: 'event_time' (equal weight per relative time) or 'fixest_att' (cohort-size weighted, matching fixest agg='att').	event_time
`data_columns`	No	Optional column projection. Parquet/Feather/Stata loaders honour this for fast partial reads.
`event_window`	No	(lead, lag) window for event-study coefficients
`control_group`	No	Control arm	nevertreated
`data_sample_n`	No	Optional uniform random subsample size (seed=0, deterministic) — useful on huge panels.
`control_cohort`	No	Nominate the reference cohort explicitly: a 0/1 indicator column (Stata eventstudyinteract's control_cohort()) or a cohort value from g.
`share_variance`	No	Carry the cohort-share estimation term of Sun & Abraham (2021, Prop. 3) in the event-study variance (True: Stata eventstudyinteract convention) or treat the interaction weights as fixed (False: fixest::sunab convention). The two coincide at single-cohort relative times; point estimates are unaffected.
`pretest_periods`	No	Restrict the pre-trend test to the k estimated leads closest to treatment.

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

Behavior5/5

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

Beyond the readOnlyHint, the description discloses computational cost scaling (columns grow as cohorts x event-time window), statistical assumptions, data preconditions, and failure modes with remedies. It also warns about noisy estimates and unstable weights with small cohorts and notes the impact of weighting choices. This goes far beyond what the annotations alone convey.

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 long but well-structured with clear labeled sections (Validation, Do NOT use when, Cost, Assumptions, Pre-conditions, Failure modes) and front-loads the core definition. It earns most of its length, though phrases like 'certified parity evidence' add little and the overall length approaches the limit of conciseness.

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?

The description is remarkably complete: purpose, contraindications, alternatives, cost, assumptions, data preconditions, and failure modes. However, it is truncated mid-word at 'Pre-tren...', so the failure-mode list is incomplete. Return-value details are reasonably covered by the output schema, so no deduction is made there.

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?

The schema covers all 21 parameters at 100%, so the baseline is 3. The description adds meaningful extras: it clarifies that g should be an integer first-treatment period with 0/NaN for never-treated, and advises trimming via event_window to control the size of the saturated design. These details go slightly beyond the schema's descriptions.

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 description identifies the exact method (Sun-Abraham interaction-weighted event-study), states the problem it solves (contamination in dynamic TWFE coefficients from other relative-time bins), and explicitly frames it as a canonical companion to Callaway-Sant'Anna. This clearly differentiates it from both TWFE-family estimators and its closest sibling, callaway_santanna.

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 provides an explicit 'Do NOT use when' section covering simultaneous adoption and very small cohorts, with a concrete alternative for simultaneous adoption (sp.did(method='2x2')). Failure modes even suggest fixes such as switching control_group to 'notyettreated' when no never-treated cohort exists. This is unusually actionable guidance.

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

Deploy Server