Dados B3

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: no API key required, the newest month is preliminary, mobile totals exclude M2M and service points, and the response carries source, license, attribution and citation. It even discloses a data quirk (the `ticker` field is null unless the full CNPJ belongs to a listed company, and Claro is not listed) that an agent could not infer from 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?

Purpose is front-loaded and the mode logic follows logically, but the run-on license parenthetical ('CC BY-ND 3.0 ... uso acertado com o órgão e informado pelo dono em 01/11/2026') and the 'contas nossas' asides are noise that lengthen an already dense block. The substantive content earns its place; the boilerplate does not.

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?

With no output schema, the description does the necessary work by sketching both return shapes (ranking with share of total and 12-month variation; per-carrier monthly series with source/license/citation). Minor gaps remain — no mention of pagination, size limits, or what happens with a malformed date — but nothing critical to calling it 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% — the schema only has bare titles with empty-string defaults — so the description carries the full burden and does so: `servico` is restricted to movel or banda_larga, `cnpj` is 14 digits or the literal TOTAL, and `de`/`ate` are AAAA-MM. It also explains that an empty-argument call is a valid ranking mode rather than an error, which resolves the zero-required-parameter ambiguity.

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 names the exact resource (mobile and fixed-broadband accesses by carrier), the source (Anatel open data) and the granularity (month by month), which no sibling covers. It also states the two distinct outputs — a consolidated-month ranking and a per-carrier monthly series — so an agent can distinguish it from the financial-data 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?

It gives clear conditional routing: call with no arguments to get the per-service ranking for the consolidated month, or pass `servico` + `cnpj` with `de`/`ate` to get one carrier's monthly series. What it lacks is any when-not or sibling comparison, e.g. pointing an agent elsewhere for financial data, so it falls short of a full 5.

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/closed-world, so the safety profile is covered. Beyond that, the description adds genuinely useful behavior: deterministic sampling keyed on the seed (same seed → same cases, reproducible by third parties) and the fact that it is free and needs no key. This is real context an agent cannot get from the 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 operative content is front-loaded in the first sentence, which is good. However, the description is bloated with editorializing and exhortation ('não aceite sugestão de ninguém', 'Auditoria que exige cadastro não é auditoria') that does not help an agent select or invoke the tool, and the reporting rules belong to the agent's behavior rather than to the tool contract.

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 2-parameter, read-only, no-output-schema tool, the description covers the essentials: it lists the return fields, the data source, the determinism guarantee, and the verification procedure. The one real omission is that the 'n' parameter is never explained, which leaves sample sizing implicit.

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 param burden. It does well on 'semente' (an arbitrary integer the caller must choose themselves, with determinism implications) but never mentions 'n' (sample size, default 25), which is documented only by the schema's default. Half the parameters are semantically explained, so the description only partially compensates for the coverage 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?

States a specific verb ('sorteia casos' – draws cases) and enumerates exactly what each returned case contains (empresa, CD_CVM, exercício, indicador, valor publicado, fórmula, conta CVM), so an agent understands the output without opening a schema. It does not, however, differentiate itself from any of the 23 siblings (veredito, scores, reapresentacoes, etc.), so it falls short of a 5.

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?

Clear on when to use it: to independently re-verify published numbers against the original CVM file, with concrete downstream steps (download dfp_cia_aberta_<EXERCICIO>.zip, filter CD_CVM and ORDEM_EXERC='ÚLTIMO'). It resolves the 'audit this, not our claims' intent well but never names an alternative sibling or an exclusion 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?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds critical context beyond them: AAPL34 is open while all others require `chave_api` (auth gating), what each mode returns, what is deliberately absent (código da ação lá fora, proporção BDR:ação), and an explicit non-recommendation disclaimer.

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?

Dense but front-loaded: the ticker="" list behavior is stated before the detail mode, and backticked parameter names plus uppercase emphasis make it scannable. Slightly long with parenthetical asides, but nearly every clause carries distinct information.

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?

No output schema exists, and the description compensates well by enumerating the returned fields for both modes and stating the auth gate. The main gap is the unexplained `de`/`ate` date-range parameters, which an agent cannot infer.

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 the description must carry the load, and it explains ticker (empty vs set), tipo (filter), serie (daily closing sample of 30 pregões), and chave_api (auth requirement) richly. It omits any explanation of `de` and `ate`, leaving two of six parameters 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 resource (BDRs negociados na B3), defines what a BDR is with concrete examples (AAPL34, NVDC34, IVVB39), and clearly distinguishes the two operating modes (`ticker=""` list vs `ticker` detail). An agent can tell this apart from siblings like etf, fii, or precos 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?

Gives strong mode-selection guidance: empty ticker lists, `tipo=` filters, set ticker returns detail, `serie=True` returns daily series. However, it never explicitly contrasts this tool against sibling alternatives (etf, precos, dividendos) for overlapping needs, so it stops short of full when/when-not routing.

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?

Beyond the annotations (readOnly/idempotent/destructive/openWorld), it discloses auth needs (keyless, chave_api optional), cost assumptions ('SEM custos', premissas returned), price-adjustment behavior and a past-measure disclaimer. That is substantive context; it does not, however, cover latency, limits, or data coverage edge cases.

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?

Purpose is front-loaded, but the body is a single dense paragraph riddled with nested parentheses, semicolons and capitalized emphasis, making it harder to scan than it needs to be. Nearly every clause carries information, yet the layout could be tightened without loss.

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?

With no output schema and 0% schema coverage, the description compensates by naming the return fields (retorno_total_pct, premissas) and the estimation assumptions. Enough is covered to call the tool correctly, though response structure and date formats are only loosely implied.

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, the description carries the load and largely does so: it fixes the default period (last 5 years), explains media_curta/media_longa via 'cruzamento de médias móveis (padrão 21 × 100)', and states that chave_api is accepted but unnecessary. It leaves the string format of de/ate unexplained.

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?

It names a specific verb and resource and enumerates the exact outputs computed (retorno, drawdown máximo com datas, volatilidade do comprar-e-manter, cruzamento de médias móveis). It also positions itself against a concrete alternative ('em vez de baixar a série diária'), so an agent can separate it from the price-series tool 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?

It gives an explicit use-case trigger ("essa estratégia valeu a pena?") and steers away from the daily-series approach. The exclusion is stated behaviorally rather than by naming the sibling tool (precos), so it stops one step short of a fully named when/when-not statement.

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, and closed-world behavior. The description adds valuable context beyond that: it specifies the output is JSON, lists what is included (formula, CVM accounts, profit basis), and gives a critical semantic warning about how margem_liquida and roe use different profit bases. It also notes the tool is free.

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 what the tool provides and is reasonably concise. The final 'Gratuito' adds a minor but useful fact, and the middle warning is justified by its importance for correct comparisons. No major filler, though the structure could be slightly tighter.

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 zero-parameter reference tool with no output schema, the description gives a good indication of the return content (JSON, formula, CVM accounts, profit basis) and a key semantic caveat. It stops short of detailing the full return shape, but it is likely sufficient for an agent to understand what calling it yields.

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 is no parameter semantics to explain. Per the baseline for zero-parameter tools, a 4 is appropriate; the description correctly focuses on content rather than nonexistent inputs.

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 resource: methodology of indicators, including formula, CVM accounts, and the profit basis for each. It distinguishes itself from most siblings by describing specific content, but it does not explicitly differentiate from the close sibling 'metodologia', leaving some ambiguity about which one to call.

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 an interpretation caveat ('IMPORTANTE para comparar corretamente...'), but it never states when to use this tool versus alternatives such as 'metodologia' or 'indicadores_anuais'. No exclusions or conditional guidance are provided.

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 past the annotations by disclosing unauthenticated rate limits (1000/hour and 10000/day per address), that chave_api is optional, and that the response carries a `citacao` field that must be cited when using the number. The one-ticker-per-call constraint is also surfaced, which is the kind of operational detail annotations cannot express.

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 returned data, then handles access rules and limits, with no filler sentences. The parenthetical endpoint references are slightly dense but each carries routing or provenance value.

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?

No output schema exists, so the description carries the return-shape burden and does so by enumerating every field plus the annual summary and yield windows. Combined with auth, rate-limit, and citation requirements, 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?

With 0% schema description coverage, the description compensates: it explains that ticker is a single company symbol constrained to one per call (mirroring the /empresas/TICKER/dividendos route) and that chave_api is an optional key whose absence triggers the stated rate limits. It stops short of giving the literal ticker format (e.g. PETR4 vs PETR4.SA).

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 — the history of cash proceeds (dividends and JCP) for a single B3 company — and enumerates exactly what comes back (value per share, approval date, ex-date, ex-date price, installment, payment date, annual summary, 12-month dividend yield). That field inventory distinguishes it cleanly from siblings like eventos, fatos_relevantes or precos.

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 that it is open to all tickers, requires no key, and takes one ticker per call, plus a pointer to the equivalent REST route. It gives clear context for invocation but does not name which sibling to use for adjacent needs (e.g. eventos for non-cash corporate actions).

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, so the description's added value is the auth tiering (key required except BOVA11), the truncation behavior without a key (last 30 pregões, BOVA11 full), and the mode switch `serie=True` expanding to a daily series with adjusted close and reinvested-return columns. That is concrete behavior beyond the structured fields; it doesn't cover rate limits or error modes.

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-loaded with the payload summary, then the access rule, then the `serie`/date-range modifiers in a logical order. It is dense and field-heavy but nearly every clause carries information an agent needs; only the long parenthetical column list feels 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?

No output schema exists, so enumerating returned sections (cadastro, informe diário, ágio/deságio, carteira, retornos) is doing necessary work, and the `serie` variant's columns are described. The missing pieces are date-input format and ticker conventions for a 5-param tool.

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 the description must carry all five params, and it largely does: `serie` toggles the daily-series output, `de`/`ate` clip the range, `chave_api` gates non-BOVA11 access, and `ticker` is implied by the BOVA11 example. It omits date format for `de`/`ate` and ticker format, which keeps it from a 5.

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?

Opens with a specific verb+resource ('Detalhe de um ETF') and then enumerates the concrete payload: CVM/B3 registration, latest daily report, premium/discount over 30 sessions, fees, top-10 portfolio, overlap, returns. That is far more than a restatement of the title. It does not name a sibling (etfs_ranking, fii) to differentiate against, so it stops short of a 5.

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 real access guidance — BOVA11 is open for degustação, other tickers require chave_api (free or Pro), and without a key you get a 30-session sample. However it never says when to reach for this tool rather than etfs_ranking or fii, so alternative selection is left implicit.

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, closed-world behavior, lowering the bar. The description still adds real behavioral context beyond them: the liquidity filter (> R$ 1 mi/dia), the exact same-day convention for ágio/deságio, the 'total return by construction' basis for 12-month return, and the effective-fee formula plus the disclosure that no nominal fee exists publicly ('Gratuito' also signals cost). It does not disclose return format, hence not a 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?

A single dense paragraph that front-loads the resource and then defines each metric. Every clause carries load (definitions and eligibility rule), though the parenthetical formulas make it run-on and dense for a caller skimming. Efficient overall.

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?

With no parameters and no output schema, the description carries the burden of explaining what is returned, and it does explain the metrics and their computation caveats well. It is slightly incomplete on the shape of the response (sort order, field names), which matters more because no output schema exists.

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 no parameters (parameter count 0), so the baseline of 4 applies. There is nothing schema-side to document, and the description cannot add parameter meaning beyond that.

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 names a precise resource (ETFs listed on B3) and enumerates the exact rankings it produces: most traded, largest patrimônio, largest ágio, 12-month return, lowest effective fee. This clearly separates it from 'etf' (single ETF) and 'fiis_ranking' (FIIs, not ETFs) by implication. It stops short of explicitly naming a sibling to route against, so it falls just below the 5 bar.

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 metric definitions imply the use case (get a ranked view of liquid B3 ETFs), and the eligibility note 'Só ETF líquido (> R$ 1 mi/dia) entra em ágio, retorno e taxa' tells the agent which tickers are filtered. But there is no explicit when/when-not guidance or contrast with alternatives like 'etf' or 'fiis_ranking', so usage is only implied.

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 the safety profile (readOnly, idempotent, closed-world, non-destructive), so the lower bar applies, and the description still adds real substance: the source attribution (declared by B3 vs found by us), the price-agreement states, and the same-day grouping rule. It does not cover pagination or errors, so it falls short of a 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?

Three front-loaded sentences: resource/types first, then the same-day multiplier semantics, then the auth detail. Dense and jargon-heavy but every clause carries information; the all-caps emphasis is stylistic noise rather than wasted 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?

With no output schema, the description steps in usefully by naming the efeito_liquido_do_dia multiplier and the confirmation states, giving the agent a sense of the return. Annotations cover the safety profile, so the remaining gap (no explicit output shape or error behavior) is minor for a read tool.

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 carries the full parameter burden. It partially compensates by explaining that chave_api is required for all tickers except WEGE3, but neither ticker format nor what chave_api is remains unexplained. Partial compensation supports a 3.

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 resource with enumerated event types — desdobramentos, grupamentos, bonificações, cisões of a company — plus the distinguishing dimensions (source, price confirmation). This is cleanly separable from the nearest sibling, dividendos, which covers a different class of event.

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 an access prerequisite (WEGE3 free; other tickers require chave_api), which is useful for invocation, but never says when to prefer this tool over siblings or what situations call for it versus dividendos/scores. Usage is only implied by the resource itself.

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 and closed-world, but the description still adds substantial context beyond them: anonymous access is open for any ticker one at a time, rate limits of 1000/hour and 10000/day per address (key-based limits with `chave_api`), and that historical `as_of` views require a key and are absent here. It also notes the `citacao` field is returned.

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?

Dense but every sentence carries information: purpose, granularity switch, domain exclusion, access model, limits. Front-loading is good, though the access/limit paragraph is a bit crammed and could be split more cleanly for scanning.

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?

No output schema exists, so the description carries return-value burden; it names the key fields and the `citacao` field but doesn't describe the response shape (e.g., period-by-period rows or nesting). For a read-only, well-annotated tool this is close to complete, with only return structure a minor gap.

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% and there are three params, yet the description explains all three: `trimestral` granularity semantics, `chave_api` effect on rate limits, and that `ticker` accepts any single stock ticker. Only the ticker string format and how to obtain a key are left implicit, keeping it just under a 5.

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 resource — standardized CVM-sourced financial accounts (receita, EBIT, lucro, PL, dívida, caixa) for a stock — with the auditorable origin of each line. It also explicitly separates itself from the sibling `fii`, which covers FIIs, so an agent can pick correctly 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?

Explicitly states the domain restriction ('Só ações'), explains why FII data isn't here and routes to `fii` as the alternative, and clarifies the `trimestral` choice (DFP annual vs ITR Q1-Q3). It also flags what is NOT available (past `as_of` balances, old versions) and the auth/rate-limit tradeoff.

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 a safe read, but the description adds substantial proprietary context: the data comes from CVM open data (ODbL) refreshed WEEKLY, carries date but not time, and the `fonte` field signals file freshness — a critical caveat for a 'latest news' tool. It also bounds expectations explicitly (no summary, no impact analysis, no recommendation; a single descriptive `frase` per item) and notes it is free with no API key.

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-loaded with the resource, ordering, and returned fields before the parameter and caveat details, which is the right structure. It runs long and a few clauses are dispensable ('Gratuito, sem chave', 'Traz `citacao`'), but nearly every sentence carries operational information.

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?

With no output schema, the description does the job of documenting the return shape (companhia, assunto, data de entrega, protocolo, link, frase, fonte, citacao) plus the freshness limitation. An agent has everything needed to call it and to correctly caveat results as weekly-lagged and reference-only.

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 load: it explains `ticker` as a company filter with an example (PETR4) and pins `categoria` to its two allowed values, which the schema does not declare as an enum. Only `limite` is left wholly unexplained (no default, no cap), which is the one meaningful 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?

States a specific verb and resource — the latest Fatos Relevantes / Comunicados ao Mercado delivered to the CVM, ordered newest to oldest — and enumerates the exact fields returned (companhia, assunto, data, protocolo, link). An agent can distinguish this from siblings like fatos_contabeis or eventos 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?

Usage is implied by the filtering explanation (`ticker` per company, `categoria` for 'Fato Relevante' vs 'Comunicado ao Mercado'), which tells the agent how to narrow results. But it never says when to pick this tool over the many sibling disclosure tools (eventos, fatos_contabeis, reapresentacoes), and offers no exclusions or prerequisites.

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 cover readOnly/idempotent/non-destructive, and the description goes well beyond them: per-address rate limits (1000/h, 10000/day), key-based limit substitution, unauthenticated sampling limited to the last 30 pregões with MXRF11 as the full-data exception, and unadjusted series with flagged jumps. It stops short of explaining what 'citacao' actually is or the shape of the paid serie output, which keeps it from a 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 core capability is front-loaded, which is good, but the text is a dense run-on with nested parentheses and awkward line wrapping that mixes return contents, auth rates, and sampling policy in one block. The rate-limit clause is useful yet could be stated once more crisply.

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 5-parameter read tool with no output schema, the description is nearly sufficient: it names what comes back, what `citacao` accompanies results, and how behaviour degrades without a key. The only real hole is the unexplained `de`/`ate` window on the historical series.

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 the full burden. It adequately explains `serie=True` (daily columns, no adjustment, jumps signalled) and `chave_api` (limit behaviour), but `de` and `ate` are never mentioned and must be guessed as the serie date window. Ticker and the default sample/full distinction are only implied.

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 ('Detalhe de um fundo imobiliário') and enumerates exactly what is returned (cadastro, último informe, série P/VP, DY 12m, rendimentos). The 'ABERTA: qualquer FII, sem chave' framing implicitly differentiates it from the ETF/BDR siblings, though it never names fiis_ranking or screener_fiis to sharpen the boundary.

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?

'um por vez' and the open-access/rate-limit note give some usage context, but there is no explicit statement of when to prefer this over fiis_ranking, screener_fiis, or dividendos. The agent must infer that this is the single-ticker drill-down and the others are list/rank tools.

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 cover safety (read-only, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: data provenance (CVM monthly report + COTAHIST), a data-quality filter ('só valores limpos (sem flag) e fundos líquidos'), explicit rate limits with and without an API key, and the presence of a `citacao` field.

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?

Purpose is front-loaded and every sentence carries information, but the phrasing is cluttered: 'ABERTA, sem chave (sem chave: ...)' repeats the same idea and the parenthetical rate-limit block interrupts the flow. Tightening could cut it meaningfully without losing content.

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?

With no output schema, the description does the work of telling the agent what comes back (rankings, segment medians, `citacao`), plus provenance, filtering rules, and limits — enough to call it correctly. It could go slightly further on result shape/ordering, but nothing essential 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 parameter `chave_api` has 0% schema coverage, so the description carries the burden — and it does explain the practical meaning (without a key: 1000/hour and 10000/day per address; with `chave_api` the key's own limit applies). It doesn't describe the key format or where to obtain it, so it is not fully complete.

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 resource (FIIs) and exactly what the ranking contains: lowest P/VP, highest DY 12m, and median P/VP and DY by segment. It also names the sibling it is not (screener_fiis), so an agent can distinguish the two 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?

Explicitly contrasts with screener_fiis ('O filtro em massa por faixas é `screener_fiis`, que exige chave'), giving a clear condition for choosing the alternative. It also states the tool is open/anonymous, which is a strong usage cue. It stops short of enumerating when-not-to-use cases beyond that one sibling.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely useful behavior beyond them: each section carries `dados_ate` per source because source lag differs, so stale sources are visible rather than masked, plus 'gratuito, sem chave'. This freshness semantics is real added value; only the return shape stays underspecified.

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 core scope in the first sentence and then layers detail in a controlled way; every clause maps to a concrete output section. It is somewhat verbose with illustrative parentheticals, but nothing is padding and the key constraint (fixed 30-day window) sits early.

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?

With no input params, rich read-only annotations, and no output schema, the description does the needed work: it enumerates the returned sections and explains the per-source freshness field. It is close to complete for a zero-arg aggregator, though it could more explicitly route agents away from the overlapping 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 the schema carries nothing to misinterpret and the baseline of 4 applies. There is no parameter meaning for the description to add or omit.

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 scope ('o que mudou no mercado brasileiro nos últimos 30 dias') and enumerates the covered content (balanços, documentos reenviados, proventos, eventos societários, trocas de ticker), so the agent knows exactly what the resource is. It implicitly differentiates from annual-series tools ('a pergunta que nenhuma série anual responde') but never names the overlapping siblings like eventos, reapresentacoes, or dividendos, so sibling disambiguation is incomplete.

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?

Frames the use case via the question it answers ('o que aconteceu com a empresa X esta semana'), which implies when to reach for it. However, there is no explicit when-not guidance and no named alternative when a narrower tool (eventos, reapresentacoes) would be preferable, leaving routing to inference.

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 cover safety (readOnly, idempotent, non-destructive), and the description adds genuinely new context: no API key required, one ticker per call, concrete rate limits (1000/hour, 10000/day per address) that change when `chave_api` is supplied, and the presence of a ready-to-use `citacao` field.

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?

Content is front-loaded and every line carries information (scope, exclusions, limits, return value). The dense telegraphic fragments ('ABERTA:', 'Só ações.') and hard line breaks make it slightly harder to parse than a cleanly structured description.

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 2-parameter read-only lookup with no output schema, the description covers scope, exclusions, auth, limits and the headline return field. Minor gaps remain: it doesn't say what an invalid/unknown ticker yields or the exact shape of the quality flags, though the `citacao` promise partly compensates.

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 load and largely does: it explains `ticker` (a B3 stock symbol, explicitly excluding FIIs ending in 11) and `chave_api` (optional key that raises rate limits). It does not state format expectations such as case or the '.SA' suffix convention, which would have earned a 5.

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 resource (annual series 2010–today) and enumerates the exact metrics returned (ROIC, ROE, margins, growth, net debt/EBITDA) plus quality flags. It also scopes it to B3 stocks, distinguishing it from `fii` and the quarterly `trimestres` tool.

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 names when NOT to use it: FII tickers ending in 11 (e.g. MXRF11) must go to `fii`, with the reason given (no ROIC/EBITDA for FIIs). It also pre-empts a common edge case by noting banks/insurers are accepted but return no ROIC/EBITDA.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavioral context beyond them: the 5-year default window, that access is open without a key, that serie=True changes the return shape, that an unkeyed call returns only a 30-session sample with an `aviso`, and that a total-return methodology is applied. This is exactly the kind of access/limits disclosure the annotations do not carry.

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?

Dense but front-loaded: the core behavior comes first, then the serie/codigo modes, then the methodology caveat. Backticks isolate parameter names effectively. It is somewhat run-on and packs several modes into long sentences, but for a 7-parameter tool with three distinct modes nothing feels wasted.

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?

No output schema exists, and the description compensates by describing the returned fields (`data`, `fechamento`), the `aviso` on sampled responses, and the metric set (return, drawdown, volatility, moving-average crossover). Given seven parameters and multiple modes, this is nearly complete; only the date-parameter semantics remain under-specified.

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 schema coverage at 0% across 7 parameters, the description must carry the load, and it does for the important ones: serie (changes output to daily closes), codigo (empty string lists indices and coverage; default IBOV), chave_api (determines sample vs full series), and the 21x100 moving-average pair. The de/ate date parameters are only implied through the period phrasing and their formats are never stated, so it misses full compensation.

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 names a specific resource (B3 market indices: IBOV, IFIX, SMLL, IDIV, IBXX) and states concretely what it returns in each mode. An agent can tell this is the index-performance tool, distinct from siblings like precos, desempenho, or etf. It does not explicitly name a sibling it is not, so it falls short of a 5.

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 a use-case framing ("the benchmark to compare a stock or a strategy") and explains which modes exist (default, serie=True, codigo=""), which implies when to pick each. However it never states when NOT to use this tool or name an alternative sibling when another data source is more appropriate, so usage is only implied.

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 and closed-world, so the safety profile is covered. The description adds real value beyond that: it discloses the returned fields, notes that the count is delivered in the response rather than in the description, and states the tool is free with no key required — an auth fact the annotations do not carry.

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 purpose and scope are front-loaded in the first sentence, and the exclusion rule follows immediately. The middle sentence about the count being served in the response is slightly meta, but it is short and informs AI clients why no count is hardcoded, so it largely earns its place.

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 zero-parameter, read-only list tool whose annotations cover the full safety profile, the description is sufficient: it states the content, the exclusions, the alternative tools, and the auth status, and even anticipates the missing return schema by naming the fields returned.

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 is nothing to disambiguate; baseline for a parameterless tool is 4. The description correctly adds no parameter detail because none exists.

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?

Names a specific verb (Lista) and resource (companhias abertas brasileiras / AÇÕES) and states the returned fields (nome, CNPJ, ticker). It explicitly distinguishes itself from the FII siblings by declaring that real estate funds are excluded, so an agent can tell it apart without opening other schemas.

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?

Gives an explicit when-to-use with routing: use this for stocks, and for FII use `fiis_ranking` (the list) or `fii` (a single fund). It names the alternatives and the condition that selects them, leaving nothing to inference.

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 cover readOnly/idempotent/non-destructive/closed-world, and the description adds substantial context beyond them: no API key required, rate limits (1000/hour and 10000/day per address, or the key's own limit with `chave_api`), that the values are historical and not a recommendation, and that a disclaimer note is included in the response.

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 core promise and the parameter semantics follow logically, with no filler sentences. It is somewhat dense and the 'ABERTA' sentence restates the no-key condition awkwardly inside parentheses, costing a little readability.

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?

No output schema exists, so the description must convey the return shape — it does: ranking, name, DATA-BASE, criteria description, ticker/value rows, source and canonical source_url. Combined with the disclosed rate limits and auth model, an agent has everything needed to call it and interpret the result.

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 load — and it does. It enumerates every `lista` value with its meaning ('dividendos', 'pl', 'fiis') plus the empty-string default behaviour, and gives the `limite` range (1–20) and default (20), and explains the role of `chave_api` in the rate-limit context.

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 concretely what it returns: a pre-computed ranking with name, base date, criteria, ticker rows, source and source_url. It distinguishes itself from the alternative workflow of reading one page per stock to assemble a ranking, but never names the sibling ranking tools (dividendos, fiis_ranking, screener, etfs_ranking), so sibling differentiation rests on inference.

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?

Gives a clear directive: 'use esta ferramenta em vez de ler uma página por ação para montar um ranking', and explains that an empty `lista` returns a catalogue of all three lists. It lacks explicit when-not guidance and does not contrast with the closely related ranking/screener 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?

Annotations already declare readOnly, idempotent, non-destructive and non-open-world, so the safety profile is covered. The description adds genuine behavioral context beyond them: the list-vs-full-text duality and that the content is free ('Gratuito'), which hints at no cost constraint.

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?

Two compact sentences with zero filler, and the core purpose plus both modes are front-loaded. Every clause adds information.

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 single-parameter lookup with no output schema, the description fully covers what an agent needs: what it returns in each mode and a sample input. Nothing essential 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 compensate, and it does well: it explains that 'nome' selects a specific page and gives a concrete example ('roic') alongside the default behavior when it is omitted. Only the exact valid page names are left unspecified.

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 resource ('metodologia pública dos indicadores') clearly, so an agent understands this returns documentation rather than data. It distinguishes itself implicitly from the numeric-data siblings (dividendos, precos, multiplos), though it never names an alternative explicitly.

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?

Describes the two invocation modes concretely: without the argument it lists the available pages, with a name it returns the full text. This is clear context on how to call it, but there is no explicit statement of when to prefer it over sibling tools or any exclusions.

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?

Beyond the readOnly/idempotent annotations, it discloses concrete operational traits: no API key required, per-address rate limits (1000/hour, 10000/day) escalating to the key's own limit when `chave_api` is supplied, and a response that includes a `citacao`. It also explains the no-look-ahead pricing rule (first trading session after actual publication), which is behavioral context the annotations cannot express.

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?

Content is front-loaded (metrics and pricing rule first, exclusions second, access/limits third) and every section earns its place. It is slightly verbose with the capitalized block labels and the parenthetical REST aside, but nothing is genuinely redundant.

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 2-parameter, no-output-schema tool, the description covers metrics, timing semantics, exclusions, auth, rate limits, and the presence of `citacao`. It stops short of sketching the response shape (e.g. per-metric objects or period labels), which would matter given there is no output schema.

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 load: it explains that `chave_api` swaps the anonymous rate limit for the key's limit, and that `ticker` accepts any ticker one at a time. It does not give a ticker format example (e.g. PETR4) or state whether the key is optional-but-recommended beyond the default empty string, leaving a small 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 names the exact resource (point-in-time multiples for a single stock) and enumerates the metrics returned (P/L, P/VP, EV/EBITDA annual; P/L TTM quarterly) plus the timing convention used to compute them. It also explicitly differentiates itself from the `fii` sibling for real-estate funds, so an agent can route 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 states when to use this tool (stocks, current method, one ticker at a time) and when not to (FII P/VP must go to `fii`, which uses CVM monthly reports instead of quarterly balance sheets). It further clarifies that point-in-time by past date is not available here and requires a key on the REST side, which prevents a wrong invocation path.

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, but the description adds substantial behavior an agent cannot infer: the unadjusted-price caveat, the 30-session keyless sample plus `aviso`, the ~250 KB context-overflow risk, and the default compact column format versus `campos` full objects. This is exactly the extra context the annotations do not carry.

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 purpose and scoping are front-loaded, but the block is long and the final compact-format paragraph is dense with parenthetical detail and a dated release note. Every sentence does carry information, so it is efficient rather than padded, though tighter phrasing would help scanning.

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 6-parameter tool with no output schema and no annotation-derived return info, the description covers param semantics, quota behavior, response size, default versus full output shape, and cross-tool routing. Nothing needed to invoke it correctly is left out.

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 carries the full burden and does so well: `de`/`ate` as AAAA-MM-DD clipping, `limite` default 1500 / max 20000 with oldest-first truncation and a warning, `campos` as an enumerated comma list plus the `todos` special value, and `chave_api` as the free key. Every parameter is given meaning beyond its type.

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 names a specific verb and resource: a DIÁRIA price series for a single stock, from B3's COTAHIST, oldest to newest, with the exact fields returned (abertura, máxima, mínima, fechamento, médio, volume, quantidade, negócios). It is trivially distinguishable from siblings like eventos, dividendos and desempenho.

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 strong routing context: `eventos` exists for whoever builds total return on the unadjusted price, and `desempenho` answers without a key. It also explains the keyless sample fallback and how to obtain a free key. What is missing is an explicit negative condition (when to prefer a different sibling over this one) beyond these hints.

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 the tool as read-only, idempotent, non-destructive, and closed-world, and the description adds substantial behavioral context: open access without a key, ANP licensing, partial coverage from 2024 onward, `fonte`/`escopo` fields, `cobertura_manual`, and the 12-month variation restriction. These details materially help an agent interpret the results correctly.

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 units, and most sentences carry operational or caveat information rather than filler. It is dense and uses long parenthetical clauses, so structure could be cleaner, but the length is largely justified by the source-coverage and license caveats.

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 7-parameter tool with no output schema, the description explains both input modes and the shape of returned data: latest-month operator aggregates, national share, 12-month variation, field-level results, monthly series, and coverage fields. It also covers source, license, citation, and the non-investment-advice disclaimer, leaving little an agent needs before calling it.

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, the description carries the burden and explains most parameters: `periodo` and `de`/`ate` use AAAA-MM, `cnpj` is 14 digits, `operador` is the ANP operator name, `campo` selects a field, and `nivel=campo` changes granularity. Some details remain implicit, such as the full accepted values for `nivel` and exact matching rules, so it is strong but not complete.

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 resource and scope: oil and natural gas production by operator and field from ANP open data, including daily average units. It is clearly distinguishable from sibling tools such as tarifas_energia or financial-data tools because it names the exact domain, source, and measurements.

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 clear usage modes: no arguments returns latest-month operators, `nivel=campo` returns fields, `periodo` selects another month, and `cnpj`/`operador`/`campo` return monthly series clipped by `de`/`ate`. It does not state explicit exclusions or name an alternative tool, so it stops short of a 5.

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 cover read-only, idempotent, non-destructive and closed-world, so the description's real contribution is the access model (free vs. key-gated, free vs. Pro tier) and the returned comparison fields — both genuinely additive. It says nothing about behavior with tickers that never restated, error responses, or pagination, keeping it out of 5 territory.

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 returns before the access-tier details, and every sentence carries information. Slightly dense, stacking output shape, product differentiator and monetization rules into three sentences, but there is 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?

With no output schema, the description takes on the burden of describing the return columns (ano, conta CVM, valor antigo × novo, variação) and does so competently, alongside the auth prerequisites. Remaining gaps are edge-case behavior — empty results for non-restating companies, ticker format, error handling — which are secondary for a simple two-parameter read.

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 parameter meaning. It does reference both parameters in prose — 'ticker' via the WEGE3/other-tickers example and 'chave_api' as a free-or-Pro key — but adds no ticker format (e.g. WEGE3 vs WEGE3.SA), no guidance on obtaining a key, and no explanation of why chave_api defaults to an empty string.

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 concrete resource with unusual precision: restated (republished) financial statements, with the exact shape of the comparison (year, CVM account, old vs. new value, variation). The 'reapresentação registrada, nunca corrigida em silêncio' framing implicitly separates it from tools that surface only current figures, but no sibling (e.g. fatos_contabeis, trimestres) is named, so full sibling discrimination isn't explicit.

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?

Gives clear calling context that an agent would otherwise have to discover by failure: WEGE3 works without a key, other tickers require chave_api, and per-version restatements are gated behind the key. It stops short of naming alternatives or stating when NOT to use it (e.g. when the caller just wants current-period statements).

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 establish the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds two genuinely new facts: the tool is free of charge and the response contains counts and the latest ingestion time. It does not state refresh cadence or whether coverage is broken down per dataset, which would push this higher.

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?

Eight words in two fragments, with the substantive content ('cobertura atual do banco') front-loaded ahead of the parenthetical detail and the cost note. Nothing is padded, though the telegraphic phrasing slightly weakens readability.

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 zero-argument, read-only metadata tool with rich annotations and no output schema, the description covers what the agent needs: what is returned and that it is free. It is complete enough to call correctly, with only the exact meaning of 'cobertura' (which entities, what granularity) left implicit.

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 has zero parameters, so per the baseline this is a 4. There is nothing for the description to clarify on the input side, and the coverage statement applies to the whole call with no arguments needed.

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 names a concrete resource and its payload: 'Cobertura atual do banco (contagens e última ingestão)' tells the agent this returns database coverage counts plus the last ingestion timestamp. It is a nominal phrase with no verb, but the scope is specific enough to separate it from the financial-data siblings (precos, dividendos, screener), which all report market data rather than dataset freshness.

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?

Usage is only implied: the agent can infer this is a status/metadata probe, and 'Gratuito' signals there is no cost barrier to calling it. There is no explicit when-to-use, no when-not-to-use, and no sibling is named as the alternative for any adjacent need (e.g. metodologia or dicionario).

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 read-only, idempotent, non-destructive behavior, and the description adds meaningful context: the free/paid access model, the requirement of chave_api for non-WEGE3 tickers, and the bank limitation. It stops short of explaining error behavior or rate limits, but it adds substantial behavioral detail 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?

The description is compact and front-loaded, naming the scores first and then adding definitions, limitations, and access rules. Every clause adds useful information with no obvious 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 two-parameter tool with annotations and no output schema, the description covers purpose, scoring definitions, access requirements, and a key data limitation. It could say more about the response shape, but the essential information an agent needs to invoke it correctly is present.

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 parameter meaning. It explains that ticker can be WEGE3 as a free example, that other tickers require chave_api, and that the key can be free or Pro, which meaningfully clarifies both parameters. It does not fully specify ticker format or chave_api optionality, keeping it below a 5.

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 that the tool returns fundamental scores, specifically the Piotroski F-Score and the Graham criterion, which gives it a distinct purpose. It does not explicitly differentiate itself from siblings such as saude, veredito, or multiplos, so it falls short of a 5.

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 useful constraints: banks have no Piotroski, WEGE3 is free, and other tickers require chave_api. However, it does not explicitly say when to use this tool instead of sibling tools like saude, veredito, or screener, leaving usage partly implied.

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 the read-only/idempotent/non-destructive profile, yet the description adds substantial behavior: only unflagged values pass, P/L negative/above 200/absent is always rejected, `rigor="estrito"` rejects any P/L with a caveat, `fora_do_filtro` reports exclusions, `multiplos` exposes `dt_receb`/`data_preco`/`ressalvas`, the result carries a declared survivorship bias, and `recibo=True` freezes the answer with a sha256. It also flags the `chave_api` requirement.

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?

Purpose and sibling routing are front-loaded and no sentence is filler, but the paragraph is long and run-on, with parameter, temporal, and receipt semantics interleaved rather than grouped. Dense and effective, yet a reader must work through it linearly.

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 6-parameter tool with a free-form nested dict, no schema descriptions, and no output schema, the description covers filtering syntax, temporal semantics, caveat handling, response fields, and citation mode. Nothing needed to invoke it 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 full burden—and it does. It documents the nested `filtros` dict shape with concrete examples, lists the valid indicators and the `_min`/`_max` suffix convention, explains `pl` (annual P/L from DFP) vs `pl_ttm` (trailing 12m), and defines `ano`, `as_of`, `rigor`, `recibo`, and `chave_api` semantics.

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 precise verb+resource ('Filtra as AÇÕES do universo por faixas de indicadores') and immediately demarcates scope against the sibling 'screener_fiis', noting that fund filters differ (P/VP, DY, segmento, cotistas). An agent can distinguish the two tools 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?

Explicitly routes: use this for stocks, use `screener_fiis` for real estate funds. It also disambiguates the two temporal parameters (`ano` = latest per company vs `as_of` = what was public on a date, and that they cannot be combined) and states when to set `recibo=True` (when citing the list, because it otherwise changes). Conditions for selection are given, not inferred.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: only clean values enter (P/VP and DY without flag), results are sorted by ascending P/VP, and there is a hard cap of 100 results, plus the auth requirement. It stops short of describing the response shape or pagination.

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?

Dense and front-loaded: the purpose, then the filter contract, then the data-quality rule, ordering, cap and auth, all in a handful of sentences. The example dict slightly overlaps with the subsequent key list, a minor redundancy, but no sentence is wasted.

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 read-only screener with no output schema, the description should ideally tell the agent what comes back. It discloses ordering (P/VP ascending) and the 100-item cap but not the returned fields or whether the result set is truncated silently. Filter semantics and auth are complete, so the gap is confined to the return contract.

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% and 'filtros' is a free-form nested object with additionalProperties, so the description carries the full burden and does so well: it gives a concrete example dict and enumerates every valid key with semantics (pvp_min/max, dy_min/max inclusive bounds, segmento exact case-insensitive match, cotistas_min as a liquidity floor). It also documents chave_api as the required free-or-Pro key.

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 a specific verb and resource: 'Filtra os FIIs por faixas' (filters FIIs by ranges), which tells an agent exactly what the tool returns. It does not explicitly differentiate itself from the sibling 'screener' (presumably the equity equivalent) or 'fiis_ranking', so the agent must infer the boundary from the 'FIIs' scope alone.

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?

Usage is implied rather than stated: it is clearly the tool for range-filtering FIIs, and the auth prerequisite 'Requer chave_api (grátis ou Pro)' is disclosed. However, there is no guidance on when to prefer this over 'screener', 'fiis_ranking' or 'fii', and no exclusions or preconditions beyond the API key.

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 cover read-only, idempotent and non-open-world, and the description still adds real substance: no API key required, taxes (ICMS/PIS/COFINS) deliberately excluded, the `ticker` field is often null because distributors are subsidiaries, and the response carries source, license and citation. It doesn't discuss pagination or result cardinality limits, which is the remaining gap.

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-loaded with what the data is (source, units, tax basis) before the call modes, and every sentence carries operational or interpretive value. It is dense and slightly long, particularly the `ticker` explanation, but nothing is 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?

No output schema exists, so the description must describe returns — and it names the fields, the summary block (cheapest/median/priciest), the ticker nullability rule, and the included source/license/citation. An agent can call this correctly and interpret the response without further docs.

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 param meaning — and it does: `cnpj` is 14 digits and returns all validity periods of a single distributor, while `de`/`ate` are AAAA-MM-DD bounding the start of validity. It also defines the default no-argument behavior, which the schema cannot express.

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 precise verb+resource: residential electricity tariff per distributor from ANEEL open data, in R$/MWh, subgrupo B1 conventional, since 2010. It also distinguishes its two operating modes (no arguments = latest tariff per distributor; `cnpj` = all validity periods for one distributor), so an agent knows exactly which behavior it will get.

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 context for both call patterns: no-arg for a cross-distributor snapshot with summary stats, `cnpj` for a single distributor's history sliced by `de`/`ate`. It also excludes a likely mis-expectation ("Não é recomendação de investimento"). No sibling tool overlaps in domain, so there are no alternatives to name — which is the only thing keeping this from a 5.

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 cover the read-only/idempotent/non-destructive profile, and the description adds substantial unstated context: no API key required ('ABERTO, sem chave'), morning indicative rates, buy/sell are source labels from the investor's perspective, nominal vs real rates are not directly comparable, numbers are not recalculated, and the response carries source, license (ODbL 1.0) and citation.

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-loaded with what the tool returns and the zero-argument default, then parameters, then interpretation caveats. Dense and mostly waste-free, but the single run-on block mixes defaults, filters and financial semantics without visual separation, making it harder to scan.

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?

With five all-optional undocumented parameters and no output schema, the description supplies everything needed: defaults, each filter's effect, rate-type interpretation, and the fact that the response contains source, license and citation. Nothing required to call it 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 coverage is 0%, so the description carries the full burden and does most of it: it enumerates the eight accepted titulo values, gives the AAAA-MM-DD format for data and vencimento, explains that data means 'last base date up to that date', that titulo+vencimento returns a daily series, and that de/ate slice that series. It leaves the format of de/ate implicit and does not say what happens if de/ate are supplied without titulo+vencimento.

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 resource (daily rates/prices of Tesouro Direto bonds) with scope (public yield curve by maturity, since 31/12/2004) and provenance. It is unmistakable against siblings such as bdr, etf, fiis_ranking or precos, which cover entirely different asset classes.

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 defines the default invocation ('sem argumentos: todos os títulos no dia-base mais recente') and three distinct usage modes keyed on titulo, data, and titulo+vencimento. It does not name sibling alternatives or say when a different tool would be preferable, which keeps it short of a 5.

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 cover read-only, idempotent, and non-destructive behavior, so the description adds important context beyond them. It discloses that ITR publishes only 1T/2T/3T and that 4T is deliberately not derived, that banks and insurers receive only net margin and ROE, and that WEGE3 is free while others require `chave_api`. This is rich behavioral context without contradicting 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 description is multi-paragraph but front-loads the core definition and every sentence adds necessary context: usage guidance, 4T rationale, sector coverage limits, and auth requirements. Given the tool's complexity, the length is justified and there is no redundant 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?

With no output schema and minimal schema descriptions, the description carries the full burden and succeeds. It covers what data is returned, when to use the tool, why 4T is excluded, sector-specific limitations, and authentication needs. An agent has enough 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 compensate. It explains the `chave_api` condition well ('WEGE3 gratuita; demais exigem chave_api') and implies `ticker` via 'de uma AÇÃO' and the WEGE3 example, but it never specifies ticker format or requiredness. Adequate but incomplete compensation for an undocumented 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 description states a specific verb and resource: a quarterly series for a stock, with ITR accounts, quarter price, and indicators. It distinguishes itself from the annual sibling by naming `indicadores_anuais` and explaining why the fourth quarter is absent. An agent can identify its purpose and scope immediately.

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 conditions for use: questions about the current year or the most recent quarter, with examples like 'como foi o 2T'. It names the alternative tool (`indicadores_anuais`) for closed fiscal years and explains the data-source reason. No ambiguity remains about when to choose this over 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds genuinely useful context beyond them: it is free with no key, it returns a ready-to-use `citacao`, it includes a green/yellow/red confidence flag, and it deliberately omits recommendations. With no output schema, this return-shape disclosure carries real weight.

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 purpose is front-loaded in the first clause, and the remaining sentences map the return contents systematically. It is dense and parenthetical-heavy, but every sentence conveys output content rather than filler, so it earns its length reasonably well.

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?

With no output schema, the description must describe the return, and it does so thoroughly: the six metrics, their comparison baselines, the confidence flag semantics, the 25-word summary line, and the citation field. Safety behavior is covered by annotations. Only the input ticker convention remains unexplained.

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% and the single `ticker` parameter is undocumented in the schema. The description implies the parameter by stating it targets 'uma AÇÃO da B3', making a stock identifier inferable, but it adds no format, exchange-suffix, or validation detail. For a single obvious parameter this is adequate but not enriched.

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 names a specific resource (a B3 stock) and enumerates precisely what the output contains: six numbers across three questions (margin, ROIC, net debt/EBITDA, P/L, P/VP) plus a confidence flag and a citation. This is far more than a restatement of the name. However, it never contrasts itself against clearly overlapping siblings such as `saude`, `scores`, or `multiplos`, so an agent cannot easily tell which to pick.

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?

There is no explicit when-to-use, when-not, or alternative routing. The description clarifies that the tool gives no recommendation and no judgment adjective, which hints at its framing, but it never tells the agent when to reach for `veredito` versus `saude`, `scores`, or `multiplos` — a significant gap given the crowded sibling set.

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