causal_forest

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

Beyond the readOnlyHint annotation, the description discloses validation scope ('validated against grf on clean-overlap designs only'), a known limitation (inflated standard error under severe propensity-overlap loss), statistical assumptions, and failure modes. It even tells the agent to inspect the overlap diagnostic before interpreting the ATE. No contradiction with annotations.

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

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

The description is dense but organized into labeled sections (Validation, Known limitations, Assumptions, Pre-conditions, Failure modes), with the purpose front-loaded. Some phrasing is jargon-heavy and the failure-modes list is long, but nearly every sentence carries decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex causal-estimation tool with an output schema and read-only annotation, the description covers what is estimated, required assumptions, formula syntax, known inference limitations, and failure responses. This is sufficient for an agent to decide whether and how to call the tool correctly.

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

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 specifying the formula contract: pipe separator, binary treatment, numeric covariates, and encoded categoricals. It also connects n_trees to calibration-failure remediation ('increase n_trees'), going beyond the schema descriptions without restating every parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific estimator and target: 'Causal Forest for heterogeneous treatment effect estimation (CATE).' It also disambiguates scope by stating that treatment must be binary and pointing to sp.multi_arm_forest for multi-valued treatments, which helps distinguish this tool from related CATE and forest-family tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The Pre-conditions section gives explicit exclusion criteria and a named alternative: 'treatment is binary 0/1 (use sp.multi_arm_forest for multi-valued)'. The Failure modes section adds remedial routing: switch to a DR-Learner if calibration fails, or consider GATE on discrete subgroups when variance is too large. This is concrete when/alternative guidance.

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