indicadores_anuais

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

With no annotations, the description carries the full behavioral disclosure burden and does it well: it states the time range, the annual output contents, the API-key requirement (optional only for WEGE3), the environment-variable fallback, and the `erro` field returned when no valid key is provided. It does not mention rate limits or exact response structure, but the essential authentication, scope, and error behaviors are 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?

The description is front-loaded with purpose and output, followed by a one-line pointer to `metodologia` and a compact `Parâmetros` section. It is about 150 words, and every sentence adds needed information about scope, return contents, parameter syntax, or error handling. Nothing feels redundant or 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?

For a tool with no annotations and no output schema, the description covers selection, parameter syntax, data range, metric list, and error behavior. The only real gap is an explicit response shape, but the listed indicators and the mention of an `erro` field make the return contract reasonably predictable.

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 compensates fully. For `ticker`, it explains the B3 uppercase class-digit format and gives examples (WEGE3, PETR4, SANB11), plus points to `listar_empresas`. For `chave_api`, it explains the free WEGE3 option, the requirement for other companies, the empty-string environment-variable fallback, and the error behavior. This far exceeds the bare string types in the schema.

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 first sentence defines the tool as an annual series of fundamental indicators for a B3 company, and the description explicitly lists the returned metrics per year: ROIC, ROE, margins, revenue/profit growth, and net debt/EBITDA. This is a specific verb/resource pairing that clearly differentiates it from sibling tools like multiplos or fatos_contabeis, even without naming them.

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 gives clear operational context: it covers 2010 through the last published fiscal year and returns per-year metrics, which implies use for historical fundamental analysis. It also explicitly routes users to `metodologia` for calculation details and to `listar_empresas` for ticker discovery. However, it does not explicitly contrast with sibling tools like `saude`, `multiplos`, or `fatos_contabeis`, so selection among those alternatives is only implicit.

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