build_research_package

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

Annotations provide readOnlyHint=true and openWorldHint=true, so the description's mention of 'build' might imply creation, but the readOnlyHint indicates no state change. The description adds context about the output format (CSV, codebook, README) beyond 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?

A single sentence covers the tool's outputs efficiently. However, it could be slightly more structured (e.g., listing outputs) without adding length.

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 8 parameters with zero description coverage, the description is incomplete. It does not explain parameter usage, valid combinations, or how to configure the export. The output schema exists but does not compensate for missing parameter guidance.

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?

With 0% schema description coverage and 8 parameters, the description offers no parameter-level explanation. For example, it does not clarify the difference between 'countries' and 'country_group' or how 'top' limits rows. This is a significant gap.

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 clearly states the tool produces export-ready CSV data, codebook, and README text for a research extract. This specific verb-output combination distinguishes it from sibling tools like build_additive_breakdown or build_research_panel.

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 implies the tool should be used when a researcher needs an exportable package of data and documentation, but it lacks explicit guidance on when not to use it or alternatives among many siblings (e.g., get_indicator_data for raw data).

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