enaho_agregar_modulo

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses critical runtime behavior: with function 'suma', a household with all missing rows remains missing rather than zero, and treating it as zero biases estimates. It also warns against 'aggregate all numeric' because summing product codes yields meaningless numbers. This adds significant behavioral context that annotations do not convey.

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 compact but dense: the first sentence states the core purpose, the second paragraph explains why the tool exists, the third gives usage rules, and the fourth provides a critical warning. Each section serves a distinct function, with no filler.

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 (nested variables object, multiple parameters) and the presence of an output schema, the description covers all essential behavioral aspects: aggregation logic, variable selection, missing-value handling, and differentiation from raw joins. The only notable omission is the `nivel` parameter's persona option, which is available in the schema but not mentioned in the text.

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 schema covers 67% of parameters; the description compensates by explaining the `variables` parameter in depth: users must explicitly map variables to functions because there is no automatic option, and it provides the example of summing product codes as a pitfall. It does not explain the `nivel` parameter, which allows both 'hogar' and 'persona', while the description only mentions household level; this is a slight 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 opens with 'Colapsa un modulo de gastos o produccion al nivel hogar' – a specific verb and resource – and immediately distinguishes itself from raw joins by explaining that modules 07-28 have one row per product and that joining raw inflates estimates. This clearly separates it from sibling tools like enaho_unir_modulos.

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 explains when to use the tool: for modules 07-28 that have product-level rows and need to be aggregated before analysis. It also instructs users to use enaho_buscar_variable to explore module variables, providing a concrete workflow. However, it does not explicitly list situations where another tool should be used instead (e.g., retaining product-level detail), so it lacks a true when-not clause.

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