hdfe_ols

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

The description goes well beyond the readOnlyHint/openWorldHint annotations by disclosing concrete behavioral traits: dense O(n^2) memory for vce='conley' (~80 GB at n=100,000), linear-cost absorption, the singleton-group bias mechanism and the drop_singletons mitigation, and a non-convergence failure mode for the alternating-projections absorber with maxiter/tol remedies. This is rich behavioral context an agent needs before calling.

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 long but well-structured with labeled sections (Validation, Cost, Assumptions, Pre-conditions, Failure modes) and front-loads the core purpose before caveats. The cost discussion is slightly verbose, but each sentence carries operational information, and the structure makes it easy to scan.

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 22-parameter econometric tool, the description covers the essential decision factors: memory scalability, statistical assumptions, input pre-conditions, known failure modes with mitigations, and routing guidance for large datasets. Since an output schema exists, the absence of return-value documentation is acceptable, and the mention of suggested_functions in the detail parameter shows awareness of downstream planning.

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 for this dimension is 3, but the description adds value beyond the schema by explaining the cost implications of vce='conley', characterizing cr2/cr3 as 'per-cluster and cheap,' and linking drop_singletons, maxiter, and tol to specific failure modes. It does not rename or restate parameter syntax, but the behavioral context for key parameters exceeds what the structured fields provide.

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 phrase "reghdfe-style OLS with high-dimensional fixed effects" names a specific verb and resource and clearly identifies it as an OLS estimator with HDFE, which separates it from the many poisson/GLM siblings like feglm, fepois, and ppmlhdfe. It does not explicitly name a sibling tool to differentiate itself, so it falls just short of a 5, but the identity is 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 states explicit when-not-to-use guidance: 'Do NOT use when: vce=conley on more than ~20,000 rows' and names the alternative — 'use sp.conley on the fitted result instead.' It also gives conditions for safe use through pre-conditions (continuous outcome, FE factor variables) and warns when to avoid via failure modes.

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