rd_distributional_design

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

Annotations already declare readOnlyHint=true, and the description adds substantial context beyond that: statistical assumptions, data preconditions, and common failure modes such as manipulation at the cutoff and bandwidth sensitivity. This helps the agent anticipate invalid results and plan diagnostic follow-ups without contradiction. Output mechanics are not discussed, but that is covered by the output schema.

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 organized into labeled segments (Assumptions, Pre-conditions, Failure modes, Alternatives, Typical minimum N) and front-loads the core method. It is dense but every segment carries decision-relevant information for a complex statistical tool. Some redundancy and technical jargon could be trimmed, but the structure makes it navigable.

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?

The description covers assumptions, preconditions, failure modes, alternatives, and a minimum sample size, which is strong for a complex estimator. However, it mentions fuzzy designs without the schema exposing any parameter to specify a fuzzy treatment variable, leaving an important ambiguity for an agent trying to call the tool correctly. Combined with the output schema and full parameter coverage, this is adequate but not fully complete.

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 input schema has 100% description coverage for all 12 parameters, so the baseline is 3. The free-text description does not add per-parameter semantics beyond alluding to running variable, cutoff, and bandwidth in the preconditions and failure modes. It neither corrects nor enriches schema-level parameter documentation.

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 opening sentence names a specific method family (joint RDD + RKD) and the target object (conditional distribution of Y), which is enough to separate it from mean-RD tools like rdrobust or from distributional DID tools. It lacks an explicit action verb like 'estimates' or 'tests', but the domain-specific phrasing is still informative.

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 provides pre-conditions, assumptions, and failure modes that tell an agent when the design is valid and what checks to run if assumptions fail. Alternatives are named (sp.rdrobust, sp.rdrandinf, sp.rdbwselect), but without explicit conditions for when to choose each alternative, so the when-not guidance remains somewhat implicit. The 'sp.' prefix also does not exactly match the sibling names, adding minor friction.

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