Causal Decision Agent

Overview Schema Source Related Servers Discussions Admin

compare_event_study_conventions

Read-only

Compare difference-in-differences event-study estimators against a TWFE benchmark, decomposing gaps into shift and residual to flag convention mismatches.

Instructions

Run several DiD estimators on one non-staggered panel and measure how far each event-study path departs from the dynamic TWFE benchmark. Splits the difference into a common vertical shift within each half of the path and a residual, so a symmetric estimator scores zero asymmetry while the kink (Callaway-Sant'Anna varying base period), the jump (BJS pre-trend convention) and the N0/N attenuation (fect / did2s in-sample residuals) each get their own signature. Warns when the recorded convention disagrees with what the data show. Assumptions: The comparison is descriptive: it measures construction differences, not which estimator is correct. Pre-conditions: panel with unit x time x outcome; exactly one treated cohort (non-staggered design); at least one never-treated unit. Failure modes: Staggered adoption (more than one treated cohort) -> Restrict to one cohort plus never-treated units; with staggered timing a gap against TWFE mixes the reference convention with forbidden comparisons; No never-treated units -> The TWFE benchmark path needs untreated units. Alternatives: sp.event_study_convention, sp.bacon_decomposition. Typical minimum N: 50.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`y`	Yes	Outcome variable column name or outcome array.
`time`	Yes	Time period column
`unit`	Yes	Unit identifier
`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
`window`	No	Relative-time window; defaults to the widest the panel supports.
`cluster`	No	Cluster identifier column for clustered standard errors.
`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.
`tolerance`	No	Threshold for the matches_twfe verdict; defaults to a scale-free 1e-6 * max(1, max\|beta_twfe\|).
`estimators`	No	Registry keys to run; defaults to every estimator with a runner.
`first_treat`	Yes	First-treatment period; 0 = never-treated
`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.7/5.0

Behavior5/5

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

Beyond the readOnlyHint=true annotation, the description discloses the decomposition into vertical shift and residual, the distinct signatures of kink/jump/N0-N attenuation, and the warning behavior when recorded convention disagrees with data. This tells the agent what the tool computes and what kind of output to expect without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Although long, the description is structured into Assumptions, Pre-conditions, Failure modes, and Alternatives, and every sentence adds distinct information. The core purpose is front-loaded, and the technical decomposition detail justifies the length for a complex comparison tool.

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?

Given the tool's complexity, the 14-parameter schema, annotations, and output schema, the description provides all selection-relevant context: data requirements, failure modes, alternatives, and minimum sample size. Nothing an agent needs to decide whether and how to call it is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema already documents all 14 parameters in detail, so the baseline applies. The description adds preconditions about the data (one treated cohort, never-treated units) but does not add parameter-level details 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 description opens with a specific verb and resource: 'Run several DiD estimators on one non-staggered panel and measure how far each event-study path departs from the dynamic TWFE benchmark.' It identifies the analyzed object (event-study conventions) and names alternatives (sp.event_study_convention, sp.bacon_decomposition), so an agent can distinguish this tool from sibling comparison tools.

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?

It explicitly states assumptions ('not which estimator is correct'), pre-conditions (non-staggered panel, exactly one treated cohort, at least one never-treated unit), failure modes with remedies (restrict staggered adoption; require never-treated units), and alternatives. This is the strongest possible guidance for when to call it vs. other estimators.

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

Deploy Server