ine_indicator

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

With no annotations, the description must carry the behavioral burden, and it does disclose useful traits: default geography resolution ('Portugal when present, otherwise all geographies'), the periods range 1-24, and substring-matching filter semantics for category. It says nothing about error behavior for an invalid varcd, unknown place names, or result ordering across geographies, which matters for a 6-parameter retrieval tool.

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 front-loaded summary sentence followed by a compact Args block; no filler and each line carries information. The docstring-style layout is slightly mechanical but appropriate given six undocumented parameters.

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 shape need not be described, and the description covers all six parameters plus default-resolution behavior for the riskiest one (place). Remaining gaps are edge-case behavior (invalid codes, ambiguous place names) and the periods/limit interaction, which are modest for a read-only statistics lookup.

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 carries parameter meaning, and it does so for all six parameters with worked examples ('0008074', 'Portugal', 'Total', 'Mulheres') and the PT/EN enum that the schema itself does not declare. Minor shortfalls: limit is only 'max rows' with no mention of its default of 40 or how it interacts with periods, and units for periods are implied, not stated.

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 the resource (INE indicator values) and the ordering guarantee ('latest periods first'), which is genuinely informative. It does not name a specific sibling to differentiate from, though it does point back to ine_search as the source of varcd, and the verb phrase 'Values of' is slightly passive.

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 varcd entry ('7-digit indicator code from ine_search') implicitly tells the agent this is a second-step tool after ine_search, which is useful routing. However there is no explicit when-to-use/when-not statement, no mention of when to prefer bpstat_series or open_data_search, and no guidance on when a wider or narrower query is appropriate.

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