sc_estimate

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

The annotations already declare readOnlyHint true, so the safety profile is known; the description adds meaningful behavioral context beyond that: key assumptions that must hold, failure symptoms such as large pre-treatment RMSPE or non-extreme placebo estimates, and recommended mitigations. It does not discuss computational cost or server-side caching, but those are at least partly covered by the schema and 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: Assumptions, Pre-conditions, Failure modes, Alternatives, and Typical minimum N. It avoids filler and each block carries actionable information for an expert user. The opening line is weak and the overall text is long, so it is not a 5, but it is far from bloated.

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 econometric tool, the description covers assumptions, data requirements, failure modes, and fallback tools, while the output schema handles return values. However, it never states in plain language what the estimator computes, and the failure-mode advice to 'add predictors' is not clearly mapped to any input-schema parameter. This leaves an agent with some uncertainty about the exact interface and purpose despite the rich context.

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 baseline is 3. The description contributes high-level context about panel structure, donor pool, and pre-treatment length, but it does not explain parameter-specific semantics such as how treat_time or treat_unit should be encoded, or whether multiple treated units are supplied as a list. The schema's own treat_time/treat_unit descriptions are tautological, and the description does not fill that gap at the parameter level.

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 identifies sc_estimate only as an 'R-style alias' for synthdid::sc_estimate and then moves into assumptions and pre-conditions about donor units and pre-treatment paths. An agent can infer it performs synthetic-control estimation, but the core action ('estimates the synthetic control treatment effect') is never explicitly stated, and it is not clearly distinguished from siblings like synthdid_estimate, sdid, or synth.

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 Assumptions and Pre-conditions sections effectively define when the tool is appropriate: SUTVA, no anticipation, a donor pool, and enough pre-periods. Failure modes give actionable redirects, such as using sdid/augsynth when pre-treatment RMSPE is large, and the Alternatives list names nearby estimators. It stops short of a 5 because the alternatives are listed without explicit selection rules beyond those failure-mode hints.

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