OpenArg — Argentina public data

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

Beyond the annotations (readOnly/idempotent/destructive=false/openWorld), the description discloses a rich set of behavioral traits: no 500-row ceiling, token efficiency, error behavior for `columna` + "conteo", ambiguity handling for numeric text formats, and 'no descuenta preguntas'. It also describes response semantics (filas_usadas, truncation when groups exceed `limite`, behavior when no rows match). 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 core guidance is front-loaded in the first two sentences and the rest is a tight per-parameter bullet list, so every line earns its place. It is longer than average, but the structure keeps it scannable rather than padded.

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?

Despite 12 parameters and 0% schema coverage, the description covers the aggregate operation, grouping, ordering, weighting, filtering, and limit semantics, plus error and truncation behavior. An output schema exists, yet the description still explains key response fields, so nothing an agent needs to call this correctly is missing.

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 description coverage is 0%, so the description must carry the full load, and it does: it defines `operacion` values, the `columna`/`conteo` incompatibility, `agrupar_por` (up to 3, with example), `limite` (1–200, narrower than the schema's default), `ordenar_por`/`orden` values and defaults, `ponderar_por` semantics, and ties `filtros`/`desde`/`hasta`/`columna_fecha` to the sibling's conventions. Only `tabla` is left implicit, which is self-evident.

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 states a specific verb and resource ('Calcula en la base una suma, promedio, conteo, mínimo o máximo, opcionalmente agrupado') and the title frames it as totals/rankings over an OpenArg table. It explicitly distinguishes itself from the sibling `obtener_datos`, so an agent can tell them apart without opening either schema.

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 gives explicit when-to-use guidance ('Usala SIEMPRE que necesites un total... o un ranking') and names the alternative it replaces ('en vez de traer filas con `obtener_datos`'). The trade-offs (exact, no 500-row cap, fewer tokens) make the routing decision unambiguous.

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

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

Annotations already declare readOnly/idempotent/openWorld/destructive=false, so safety is covered. The description adds genuinely useful behavior beyond that: the exact fields returned and the quota note ('No descuenta preguntas'), which tells the agent this call is cheap to repeat.

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?

Front-loads what the tool does, then return shape, then per-parameter meaning. Dense but every sentence earns its place; 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?

For a 3-parameter search tool with an output schema and fully annotated safety profile, the description covers purpose, return fields, all parameters, and routing to siblings. An agent has everything needed to invoke 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?

Schema description coverage is 0%, so the description must carry all three parameters — and it does: `texto` with concrete Spanish examples, `portal` with its filtering role and referent tool, and `limite` with its 1–25 range. Nothing material is left undocumented.

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?

States a specific verb (busca) and resource (catálogo de OpenArg) with a concrete scope ('más de 30.000 datasets de portales oficiales'). An agent can immediately tell this is a search-over-catalog tool and it is differentiated from siblings like describir_tabla/obtener_datos, which it names as the downstream consumers of results.

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?

Routes the agent explicitly: results' tables should be used with `describir_tabla` and `obtener_datos`, and `portal` filtering is done via `listar_fuentes`. Clear when-to-use context, though it never states a when-not-to-use condition.

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

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

Goes well beyond the annotations by disclosing response contents (datasets used with links to the official portal, data quality/coverage warnings, remaining monthly quota) and the exact cost model: 1 question deducted per answer, 10 free per month, with errors, timeouts, and identical questions repeated within 5 minutes not deducted. This is the kind of billing and failure-mode context that annotations cannot express and that materially affects how an agent should call it.

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?

Front-loads the purpose, then examples, then response contents, then cost and fallback routing — a logical order with no filler sentences. It is somewhat long (four examples plus a three-part billing clause), but each block carries information the agent needs and none is redundant with the schema or annotations.

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 one-parameter natural-language query tool with an output schema already defining return structure, the description supplies everything else an agent needs: scope, example inputs, cost and quota behavior, error/timeout exemptions, and preferred alternatives. Nothing material to correct invocation is missing.

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 single 'pregunta' parameter has 0% schema description coverage, so the description must carry the semantics — and it does, via four representative questions that establish free-text natural-language input, expected topics (unemployment, IPC, legislature, budget), and acceptable phrasing. It stops short of stating any length or formatting constraints.

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?

States a specific verb+resource: answering a natural-language question over official Argentine public data, with sources. The four concrete example questions make the scope unambiguous, and it distinguishes itself from sibling tools by telling the agent to prefer buscar_datasets + obtener_datos or agregar_datos when those suffice.

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 explicitly names alternatives (buscar_datasets, obtener_datos, agregar_datos) and a preference rule to use them instead when possible, which is real routing guidance. The deciding condition ('si podés responder con...') is self-referential and never says what this tool uniquely offers (multi-dataset synthesis, natural-language questions), so the agent must infer it.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so safety is covered; the description still adds non-obvious behavior: freshness is the source read date, not the data date, and a table is not 'current' merely because it was read today. It also implies it does not consume the question quota ('No descuenta preguntas'), though that phrase is left unexplained. Some of this restates output-schema fields, which caps it below 5.

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 output contents are front-loaded in the first sentence, followed by parameter sourcing, usage routing and freshness caveats. It is efficient overall, but the date-semantics passage is somewhat meandering and the trailing 'No descuenta preguntas' is cryptic without explanation.

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?

An output schema exists, so return fields need not be re-explained, yet the description still clarifies the non-obvious freshness semantics and where to source the parameter. With annotations and output schema already present, the only real gap is the unexplained quota statement, leaving the definition effectively complete for correct invocation.

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 0% for the single parameter, so the description carries the burden, and it does: `tabla` is defined as the identifier returned by buscar_datasets. That is the crucial semantic an agent needs and it is not in the schema. It does not give format or naming examples, so it is not fully exhaustive.

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?

States a specific verb and resource (muestra ... una tabla) and enumerates exactly what it returns: columns with types, row count, covered period, freshness and a sample. It also distinguishes itself from siblings by positioning itself upstream of obtener_datos/agregar_datos and downstream of buscar_datasets, so an agent can place it without opening any schema.

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?

Explicitly instructs the agent to use it before obtener_datos or agregar_datos in order to learn which columns to request and which dates exist, naming both alternatives and the condition that selects this tool. No when-not rule is given, but the routing condition is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond those annotations: it clarifies that the call does not consume questions and counts as a data-mode request, which helps an agent reason about quota impact.

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 two short sentences with no waste. The core purpose is front-loaded, and the quota note follows as a secondary operational detail.

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 simplicity, zero parameters, available output schema, and rich annotations, the description is nearly complete. It explains what is listed and adds quota context, though it could better position itself relative to sibling tools.

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 tool takes zero parameters, so there are no parameter semantics for the description to explain. The baseline for a no-parameter tool is 4, and the description does not need to compensate for any schema 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 states a clear verb and resource: lists the open data portals covered by OpenArg and how many datasets each has. It is specific about what the tool returns, but it does not distinguish itself from sibling tools such as buscar_datasets or consultar_datos_publicos.

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 does not say when to use this tool versus alternatives. The second sentence mentions quota behavior ('No descuenta preguntas: cuenta como un pedido del modo datos'), but that is not usage guidance for selecting this tool over its siblings.

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

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

Goes well beyond the readOnly/idempotent annotations: pagination limits (1-500 rows, offset up to 10,000 and next-page offset reported), the case/accent-insensitive filter behavior and its >1M-row exception surfaced via `filtros_aplicados`, and the empty-result behavior ('la respuesta dice qué valores existen'). Missing auth/rate-limit context, but the operational behavior is richly disclosed.

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?

Bullet-structured and front-loaded with the purpose sentence, and each bullet carries distinct semantic content rather than filler. It is dense and long, but almost no sentence is wasted; a slight trim would be possible.

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 9-parameter tool with an output schema present (so return shape needn't be described), the description covers parameter formats, filter grammar, pagination, ordering, edge cases, and sibling routing. An agent has everything needed 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?

Schema coverage is 0%, so the description must carry the full burden and does: it documents `columnas`, `desde`/`hasta` formats (AAAA / AAAA-MM / AAAA-MM-DD), the entire `filtros` grammar (equality object vs. operator list, the seven operators, max 5), `orden` semantics, `limite` range, the pagination `offset`, and `columna_fecha` as an alternative date column. Effectively every parameter is explained.

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?

States a specific verb+resource ('Trae filas de una tabla, en CSV, con la fuente oficial') and immediately distinguishes its scope from `agregar_datos` for aggregations. An agent can separate this row-fetch tool from its siblings without opening the schema.

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?

Explicit negation: for totals/averages/counts/min/max/rankings, do NOT fetch rows — use `agregar_datos`. It also routes column-name discovery to `describir_tabla`. Clear when-to-use and when-not-to-use guidance with a named alternative.

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