mediate

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

Beyond the readOnlyHint annotation, the description discloses statistical assumptions, failure modes, and a required companion sensitivity analysis. It also warns about assumption violations and provides a minimum sample size, adding substantial behavioral context 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.

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

The description is dense but well organized: purpose, assumptions, pre-conditions, failure modes, alternatives, and sample-size guidance. The core function is front-loaded in the first sentence, and each subsequent section supports correct invocation or routing to a sibling tool.

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 high-complexity causal mediation tool, the description is remarkably complete: it covers identification assumptions, pre-conditions, failure modes, alternatives, and a minimum N. The output schema already handles return-value details, so the description need not repeat them. An agent has enough context to select and call this tool appropriately.

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?

The schema already covers all 12 parameters at 100% coverage, so the baseline is 3. The description adds meaning beyond the schema by clarifying that treatment must be binary 0/1, the mediator must be post-treatment and causally between treatment and outcome, and covariates must capture confounding for T-Y, M-Y, and T-M. This is useful extra context, though most parameter-level details are left to the schema.

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 states a specific verb and resource: 'Decomposes the total effect into natural direct effect (NDE) and natural indirect effect (NIE)' via a named identification strategy. It also distinguishes itself from siblings by explicitly listing alternatives such as sp.mediate_sensitivity, sp.mediate_interventional, sp.four_way_decomposition, and sp.proximal.

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 gives explicit pre-conditions (binary treatment, post-treatment mediator, pre-treatment covariates) and when-to-use alternatives for common failure modes. For example, it directs users to sp.four_way_decomposition when a post-treatment confounder is suspected and always recommends reporting sp.mediate_sensitivity.

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