aggte_from_influence

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

The readOnlyHint annotation already signals a safe read operation; the description adds valuable context beyond that: it states no refit occurs, no original data is needed, and it lists failure modes and validation tiers. It also explains the workflow linkage to influence_functions, giving the agent a clear mental model of side-effect-free operation. No contradiction with 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 every sentence earns its place: it front-loads the core action, then adds pre-conditions, failure modes, alternatives, and a typical N in a compact, scannable format. There is no filler or redundant restating of the tool name. The structure uses clear separators (periods, hyphens) that aid parsing.

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, the description covers the essential context: pre-conditions, failure modes, alternatives, and typical sample size. An output schema exists, so return-value details are not needed. It leaves out explicit pagination or caching behavior, but the as_handle parameter description in the schema covers that, and the annotation covers safety. Overall, it is sufficiently complete for an agent to call it correctly.

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 parameters, including the 'type' enum and 'source' format details. The description mentions the summary types and the source provenance, but this largely mirrors schema content. It does not add deeper semantics about parameter interactions or format specifics beyond what the schema already documents, so it holds at the baseline 3.

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-resource pair ('Aggregate Callaway-Sant'Anna group-time ATTs') and enumerates the exact summary types (event-study, group, calendar, overall) and inference method (multiplier-bootstrap). It names direct siblings (sp.aggte, sp.influence_functions) and distinguishes itself by stating 'no refit and no original data required', making the tool's scope 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?

It provides explicit pre-conditions ('source was produced by sp.influence_functions'), failure modes ('missing required columns -> Re-export'), and alternatives ('Alternatives: sp.aggte, sp.influence_functions'). It frames itself as 'the post-hoc half of the Stata csdid saverif() workflow', which clearly indicates when to use it. It stops short of an explicit 'do not use when...' clause, but the context strongly implies it.

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