check_absorbing

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

Annotations declare readOnlyHint=true, and the description aligns with that by describing a detection/check operation. The description adds valuable behavioral context beyond the annotation: it explains that cohort-based estimators silently return biased estimates (0.71 vs true ATT of 1.5) under reversal, that the tool 'never sees the time-varying indicator' in those estimators, and that it can raise MethodIncompatibility when strict=true. It also discloses validation evidence tier and pre-conditions. Minor gap: it doesn't explicitly state the return shape, but an output schema exists, so that burden is reduced.

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 well-organized: it front-loads the core purpose, then provides a concrete failure example, then usage guidance, validation, pre-conditions, and alternatives. Every sentence adds information. It is longer than the typical description, but the length is justified by the complexity of the statistical concept and the need to warn against silent bias. Slight deduction for density—an agent may need to parse carefully—but no wasted words.

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?

Given the tool's complexity (10 params, output schema present, subtle statistical failure mode), the description is remarkably complete. It covers what the tool does, why it matters, when to run it, what inputs are valid, what alternatives exist, and what validation evidence supports it. The output schema handles return-value documentation, so the description doesn't need to. An agent has everything needed to decide whether and how to call this tool.

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 description coverage is 100%, so the schema already documents all 10 parameters. The description adds crucial semantic context for the key parameter 'treat': it explains that a cohort/first-treatment column cannot express reversal and passing one makes the check meaningless. It also clarifies the meaning of 'detail' levels in terms of token payloads and downstream planning. This goes beyond the schema's field-level descriptions, though the schema already does most of the work.

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 verb and resource: 'Detect non-absorbing (reverting) treatment in a panel.' It clearly distinguishes itself from sibling DiD estimators by explaining that cohort-based estimators are lossless only when treatment never turns off, and that this tool checks for reversal. It also names the exact estimators it guards against (callaway_santanna, sun_abraham, etc.), making its purpose unmistakable.

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 description explicitly states when to use the tool: 'Run this on the raw panel before picking an estimator.' It also lists pre-conditions (long panel with unit x time x time-varying treatment; numeric 0/1 treatment) and names alternatives (sp.did_multiplegt, sp.lp_did, sp.did_multiplegt_dyn). It even explains the failure mode it prevents, so an agent knows exactly when this check is needed versus when it is not.

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