Dados B3

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

No annotations are provided, so the description carries the full behavioral burden — and it excels: it discloses that the sampling is deterministic and reproducible ('a mesma semente devolve sempre os mesmos casos, então seu resultado é reproduzível por terceiros'), that the sample is randomly drawn, and that the tool is free with no API key ('Gratuito, sem chave'). These are exactly the behavioral traits an agent needs to know and could not infer from the schema or 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 dense (roughly 350 words) but well-structured and front-loaded — the core purpose comes first, followed by methodology, case contents, verification steps, and reporting rules. Every block earns its place, especially the audit-integrity rules that constrain agent behavior. It is slightly long in the operational verification section (the dfp_cia_aberta_<EXERCICIO>.zip download and filtering details), which borders on over-specification, but it is scannable and purposeful.

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 tool with no annotations and no output schema, the description is remarkably complete. It effectively supplies a de facto return contract by enumerating what each case contains (empresa, CD_CVM, exercício, indicador, valor publicado, fórmula, conta CVM), explains the required parameter, gives verification workflow, sets behavioral rules, and even points to the issue tracker for bugs. Nothing an agent needs to invoke it correctly is left to guesswork.

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 thoroughly explains the required parameter 'semente' — what it is (any integer), the security constraint (don't accept suggestions), and its behavioral implication (determinism). The optional 'n' (sample size, default 25) receives no explicit explanation, but it is a simple integer with a sensible default visible in the schema, and the text implicitly references sample sizes ('7 divergências em 100'). Strong compensation for the hard parameter, slightly light on 'n'.

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 leads with a specific verb and resource scope: 'AUDITE ESTA BASE. Sorteia casos e devolve o que você precisa para refazer cada número contra o arquivo ORIGINAL da CVM'. This makes crystal clear it is a sampling-audit tool that cross-checks against original CVM filings, not a fetch/query tool. It is also self-evidently distinct from all 13 siblings (dividendos, fatos_contabeis, fii, etc.), which are data-retrieval tools, so an agent cannot confuse them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives strong contextual guidance on the intended scenario ('AUDITE ESTA BASE') and rich methodological rules — choose your own seed, never accept someone else's suggestion, publish the denominator and not just '7 divergências', and show the account when claiming an error. However, it stops short of explicitly naming sibling alternatives or stating when NOT to use this tool versus the regular data tools; the distinction is implied rather than spelled out.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It discloses that the output is in JSON ('em JSON'), that it is free ('Gratuito'), and provides important methodological nuances (e.g., different profit bases for margins and ROE). This adds valuable context beyond a simple definition, though it does not explicitly state whether the tool is read-only or describe all return contents.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long and every phrase earns its place: the first sentence defines the tool's content, and the second provides a critical practical caveat for correct usage. It is well-structured, front-loaded, and free of redundant 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?

Given that the tool is a parameterless reference dictionary, the description provides sufficient context: it explains what the JSON contains, mentions a key caveat for correct use, and notes the cost. It does not enumerate all indicators, but that is not essential for this type of tool, and the description is complete enough for an agent to understand its purpose.

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 has zero parameters, and schema coverage is 100% vacuously. The baseline for 0 parameters is 4, and the description does not need to explain parameter behavior. It provides no parameter-related information, which is appropriate for a parameterless reference tool.

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 provides indicator methodology in JSON format, including formula, CVM accounts, and the profit base for each indicator. It gives a specific example (margem_liquida vs roe) to illustrate its purpose, though it does not explicitly distinguish itself from the sibling tool 'metodologia'.

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 implies the tool is useful for correctly comparing indicators ('IMPORTANTE para comparar corretamente'), but it does not explicitly state when to use this tool versus alternatives like 'metodologia' or other sibling tools. There is no clear when-to-use or when-not-to-use guidance.

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?

No annotations are provided, and the description adds behavioral context by noting that WEGE3 is free while other tickers require chave_api. It lists the response contents but does not disclose whether the operation is read-only, rate limits, or error behavior. This is adequate for a simple read endpoint but lacks broader behavioral detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first lists the tool's purpose and key output fields, the second covers the free/API-key distinction. No filler or redundant 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?

Given the absence of annotations and output schema, the description covers the main purpose, output fields, and a key authentication requirement. It does not mention pagination, historical depth, or error handling, but for a straightforward data retrieval tool this is reasonably complete.

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%, but the description explains the chave_api parameter by stating that only WEGE3 does not require it, and that a free or Pro key is used. The ticker parameter is self-evident from the name and is used in the example 'WEGE3', though its format is not formalized.

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 'Histórico de proventos em dinheiro (dividendos e JCP) de uma empresa da B3' which clearly identifies the tool as returning a history of cash dividends and JCP for a single Brazilian company. It lists specific fields (valor por ação, data de aprovação, data-com, preço) and adds metrics (resumo anual, dividend yield), distinguishing it from siblings like 'multiplos' or 'indicadores_anuais'.

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 provides a usage condition: 'WEGE3 é gratuita; demais tickers exigem chave_api' – indicating when the API key is needed. However, it does not explicitly compare this tool to sibling tools or state when to prefer it over alternatives.

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?

With no annotations present, the description carries the disclosure burden. It reveals the data sources (CVM + B3), the scoped information returned, and the API-key requirement for non-BOVA11 tickers. It does not mention rate limits or explicitly state read-only behavior, but the query-like nature plus detailed output sections give adequate transparency for an agent.

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 dense but well organized: the first sentence front-loads the core purpose and output contents, and the second delivers the access caveat. Every clause adds information, though the long comma-separated list makes it slightly heavier than necessary.

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?

There is no output schema, so the description must explain what the tool returns, and it does so thoroughly: portfolio overlap, premium/discount, monthly rates, returns by quote and price, and registration data. Combined with the API-key guidance, an agent has enough context to invoke the tool for the intended use case.

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 only supplies titles and defaults, and schema coverage is 0%, so the description must compensate. It does: 'BOVA11' provides a concrete ticker example, and the sentence about requiring chave_api for all other ETFs clarifies the otherwise misleading empty-string default on the chave_api parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear, specific purpose: 'Detalhe de um ETF' and enumerates the exact data blocks returned, such as cadastro CVM+B3, informe diário, ágio/deságio, taxa efetiva, carteira, sobreposição, and retornos. This scope distinguishes it from broader siblings like etfs_ranking, which clearly focuses on ranked lists rather than a single ETF's detailed profile.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear contextual guidance: BOVA11 is freely available for testing, while all other ETFs require a chave_api (free or Pro). It does not explicitly compare this tool with alternatives or state when not to use it, so it stops short of a 5, but the access and prerequisite guidance is concrete and actionable.

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?

The description provides several behavioral details beyond annotations: it defines the metric computations (e.g., price ÷ same-day nav, effective fee = expense ÷ average net assets), specifies the liquidity threshold, and notes that the use of the share price is same-day. But because there are no annotations and no output schema description, it still lacks information about the or delivery format (e.g., sorted order, number of results, whether it is a table or JSON). The description adds meaningful context, yet the actual runtime behavior remains incompletely disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact—one sentence with parentheticals—and communicates a large amount of information in a relatively short space. All the clauses are relevant and none are filler. However, the dense parenthetical definitions, while useful, make the wording harder to parse at a glance; a structured bullet list would improve readability without adding length. It is appropriately concise but could be slightly better organized.

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?

The tool is moderately complex with no parameters, no annotations, and no output schema. The description covers the metric definitions and the liquidity scope, which addresses the core data semantics. But it does not specify what the actual result looks like—whether it returns a list of ETF tickers with sorted rankings, how many items are returned, or in what order. Because the output format is omitted, an agent could call the tool correctly but not know how to interpret the response, making the description incomplete for a software agent.

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?

This tool has zero parameters and the schema shows an empty object, so the baseline for parameter semantics is 4. The description clarifies that the tool is a fixed-ranking endpoint and explains that it is 'free', which is helpful but not required. Since there are no parameters, the description doesn't need to explain parameter meaning, and it successfully avoids any parameter-related confusion.

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 identifies the resource (ETFs listed on B3) and the content: it provides a list of most-traded, largest assets, discount/premium, 12-month return, and lowest effective fee. This conveys the tool aims to deliver ETF rankings by multiple criteria, which is clear enough to distinguish it from other data tools. However, it does not explicitly name the ranking behavior or contrast with the sibling 'etf' tool, so it falls shy of full clarity.

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' or 'when not to use' guidance. The description mentions that only liquid ETFs (> R$1 million/day) are included in certain metrics, which hints at a scope filter, but it does not tell the agent when to prefer this tool over alternatives such as 'etf' or 'fiis_ranking'. With no exclusions or alternative references, the usage context is implied rather than stated.

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?

No annotations are provided, so the description carries the full burden. It discloses data-source behavior (DFP annual vs ITR quarterly granularity with overlapping history), scope limitations (stocks only; FII not supported in this format), and authentication requirements (chave_api needed except for WEGE3). It does not cover error behavior, invalid-key handling, or output structure, but the core behavioral traits an agent needs are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact paragraphs, each with a distinct job: core functionality and granularity, scope/exclusion with sibling routing, and access requirements. The key purpose is front-loaded and every sentence carries information — no filler or repetition of schema fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-parameter tool with no annotations and no output schema, the description covers what data is returned, source traceability, granularity semantics, scope restrictions, and authentication conditions. Minor gaps remain — exact return format and error behavior — but nothing that would prevent correct selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the schema. It fully explains `trimestral` with the concrete outcome of each value (annual DFP vs isolated ITR Q1-Q3) and explains when `chave_api` is required (all tickers except WEGE3). `ticker` is only implied as a stock code rather than explicitly described, so the compensation 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 identifies a specific resource and output: standardized accounting accounts for a stock (receita, EBIT, lucro, PL, dívida, caixa) with the originating CVM account for each figure, making the data auditable end-to-end. It also distinguishes itself from siblings by stating 'Só ações' and explicitly routing FII queries to the `fii` tool. The verb is implied rather than explicit ('returns/provides'), but the intent is unambiguous.

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 explicit when-to-use guidance: stocks only, with FII explicitly excluded and routed to the sibling `fii` tool ('o que existe é o informe mensal, exposto por `fii`'). It also explains the `trimestral` choice as a granularity decision (False → annual DFP, True → ITR Q1-Q3, both covering the same history) and the access condition (WEGE3 free, others require chave_api). Nothing is left 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?

With no annotations provided, the description carries the full transparency burden. It discloses the data included and the authentication requirement (chave_api for non-MXRF11 funds). It does not mention rate limits or explicitly state read-only behavior, but the listed content and key requirement provide substantial transparency for a data-retrieval tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: two sentences that start with a clear purpose and then list specific data items, followed by a crucial access note. Every clause adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only two parameters, no output schema, and no annotations, the description provides a solid overview: purpose, data contents, and access conditions. It lacks explicit error handling or output format details, and does not distinguish itself from overlapping sibling tools, leaving some gaps, but overall it is fairly complete.

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 compensate. It does so by explaining that the tool requires a ticker (implicitly via MXRF11 example) and that chave_api is required for funds other than MXRF11. This gives meaningful context to both parameters beyond the bare 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 clearly states the tool provides details of a real estate fund (FII) and enumerates specific data points (cadastro, último informe, historical P/VP series, current 12m DY, and last dividends paid). This makes the purpose specific and valuable, but it does not explicitly differentiate from sibling tools like fiis_ranking or dividendos.

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 implies usage by indicating it is for individual FII details and explains that only MXRF11 is open for free testing while others require an API key. However, it does not provide explicit when-to-use or when-not-to-use guidance compared to alternatives, such as directing users to fiis_ranking for rankings or dividendos for broader dividend queries.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context beyond basic ranking: data sources ('informe mensal da CVM + COTAHIST'), data filtering ('só valores limpos (sem flag) e fundos líquidos'), authentication requirement ('Requer chave_api'), and a note about free access to a specific ticker ('MXRF11 é aberto para degustação'). This gives the agent meaningful insight into how the tool behaves.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences and front-loaded with the core purpose (ranking FIIs). Each clause adds distinct information: criteria, data sources, quality filters, and authentication. There is no redundant filler, though some domain abbreviations (P/VP, DY) may be less accessible to general audiences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (one param, no output schema) and lack of annotations, the description provides a solid overview of what the tool returns (rankings and medians) and its data provenance. However, it omits practical details such as result limits, default sorting, output format, or whether all FIIs are included, leaving some ambiguities for the agent.

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 input schema only shows a parameter named 'chave_api' with no description (schema coverage 0%). The description compensates by explaining that this is an API key, mentions free and Pro tiers, and states it is required ('Requer chave_api'). This adds essential meaning beyond the raw schema definition.

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 tool's function with a specific verb and resource: 'Ranking dos fundos imobiliários (FIIs)' and details the ranking criteria (most discounted by P/VP, highest yield by DY 12m, and medians per segment). It distinguishes itself from siblings like 'screener_fiis' by focusing on rankings and aggregate statistics rather than screening.

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 intended use is implied through the description (it provides rankings for FIIs), but there is no explicit guidance on when to choose this tool over alternatives like 'screener_fiis' or 'fii'. No exclusions or alternative recommendations are provided, though the context is clear enough for an agent to infer basic usage.

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?

With no annotations, the description carries full disclosure responsibility and does so well: it reveals data-lag behavior (`dados_ate` per section, fixed window from today, stopped sources look stopped) and access constraints ('Gratuito, sem chave'). This is meaningful behavioral context beyond a simple 'returns data' statement.

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 the primary promise, then details the window contents, then explains the freshness semantics, then gives access info. Each sentence adds a distinct piece of information and none restates the title or schema.

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 no-parameter, no-output-schema tool, the description explains the relevant output categories and the `dados_ate` field meaning, which is sufficient for an agent to present results accurately. It still leaves minor ambiguity about how the 'empresa X' phrasing maps to an invocation with no parameters.

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 has zero parameters, so the description cannot add parameter-level detail; the 0-parameter baseline of 4 applies. The only relevant semantic detail, that no API key is needed, is stated in the description.

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 clear deliverable ('O que mudou no mercado brasileiro nos últimos 30 dias') and enumerates the concrete content: public filings, re-submitted documents, dividends, FII reports, corporate events, and ticker changes. It does not name sibling tools, and the 'empresa X' phrase is framed as a user question rather than an explicit scope, so it stops short of full sibling differentiation.

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 clear context — use for recent changes that 'nenhuma série anual responde' and explicitly frames the 30-day window as the differentiator. It never names alternatives or says when not to use the sibling tools, but the context is specific enough to route an agent.

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?

With no annotations provided, the description carries the full behavioral disclosure burden and handles it well: it discloses the data scope (2010–today), the indicator set, the FII exclusion behavior, the bank/insurer limitation (no ROIC/EBITDA due to their chart of accounts), and the API-key requirement. It stops short of describing the return format or what 'flags de qualidade' mean, but the core behavioral traits are transparent.

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 short paragraphs, each with a distinct job: what the tool returns, exclusions and alternative routing, and auth/pricing. Every sentence earns its place and the core purpose is front-loaded in the first sentence. No filler or repetition.

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 tool with no annotations and no output schema, the description is nearly complete: it covers purpose, valid inputs, exclusions, alternatives, and auth requirements. The only minor gaps are the undefined 'flags de qualidade' and the lack of a return-structure sketch, though the enumerated metric list already gives an agent a solid expectation of the response.

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 fully compensates: it defines the valid `ticker` space (B3 stocks only, not FIIs ending in 11, banks/insurers allowed with caveats) and specifies when `chave_api` is required (all tickers except WEGE3) and which tiers work (free or Pro). This is exactly the parameter-level meaning the schema fails to provide.

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-resource relationship: it provides an annual series (2010–today) of ROIC, ROE, margins, growth, and net debt/EBITDA for a single B3 stock, with quality flags. It distinguishes itself from siblings by explicitly excluding FII tickers and routing them to `fii`, and by noting banks/insurers are included with limitations.

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 explicit when-to-use/when-not-to-use guidance: FII tickers ending in 11 (e.g., MXRF11) must NOT be queried here and should use `fii` instead, with the rationale that FIIs have P/VP, DY, and vacancy rather than ROIC/EBITDA. It also states the prerequisite that WEGE3 is free while all other tickers require chave_api.

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?

No annotations are provided, so the description carries the full burden. It discloses meaningful behavior beyond the basic function: the count is returned in the response rather than hardcoded, tickers appear only when resolved, FIIs are excluded, and no authentication key is needed. This is strong behavioral context for a zero-parameter tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The main action and scope are front-loaded, and the exclusion note is efficient. The meta-explanation about why the count is not written in the description is slightly verbose, but it does serve a purpose for AI clients reading the 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 parameterless listing tool with no output schema, the description is complete: it covers scope, returned fields, response count behavior, exclusions, sibling alternatives, and access requirements. Nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the baseline is 4. The description adds useful output-field semantics (nome, CNPJ, ticker) but there are no parameters for it to document.

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: 'Lista as companhias abertas brasileiras (AÇÕES)', with the returned fields named (nome, CNPJ, ticker). It explicitly separates this tool from FII tools, so an agent can distinguish it from fiis_ranking and fii without opening 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 explicit when-to-use guidance: only stocks, and explicitly excludes real estate funds. It names the alternatives for FII use: fiis_ranking for the list and fii for a single fund. It also states access requirements upfront: 'Gratuito, sem chave'.

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?

With no annotations, the description carries the full burden. It discloses that the tool is free, lists pages without an argument, and returns full text with a name. This covers the main behavioral aspects, though it does not mention error handling or the exact return format.

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 extremely concise—two sentences—and front-loaded with the tool's purpose. Every word earns its place, making it efficient and easy to parse.

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 simple tool with one optional parameter and no output schema, the description covers both usage modes and states the return type (text). It is complete enough for an agent to invoke correctly, though it omits minor details like invalid name behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% for the 'nome' parameter, but the description compensates by explaining that the parameter takes a name (e.g., 'roic') and returns the full text. This gives clear semantic meaning beyond the raw 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 clearly states the tool's function: it provides public methodology for indicators. It specifies two modes: listing pages without arguments and returning full text when a name is given (e.g., 'roic'). This distinguishes it from sibling tools that likely provide data values rather than methodology.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains how to use the tool (with and without the 'nome' argument) but does not explicitly mention when to use it instead of alternatives or exclusions. It implies usage for methodology text, but no direct comparison to siblings is made.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It discloses the key methodology (no look-ahead bias, price after actual publication) and the API key requirement. However, it does not describe the response format or behavior on errors, which is a minor gap given no output schema exists.

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 three sentences with no wasted words. It front-loads the core purpose and methodology, then adds usage nuance about scope and pricing. The line 'Só ações' ('only stocks') slightly repeats the initial 'de uma AÇÃO', but it reinforces the exclusion and fits naturally.

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?

The description covers the multiples provided, the pricing rule, the restriction to stocks, the alternative tool, and the API key condition. Since there is no output schema, it could be more explicit about the return format, but for an agent deciding whether and how to call the tool, the information is sufficient.

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 provides only `ticker` and `chave_api` with 0% coverage, so the description must compensate. It adds meaning by giving a concrete example (WEGE3) and explaining that `chave_api` is required for all tickers except WEGE3, which clarifies the role of both parameters beyond the bare schema fields.

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 explicitly defines the tool's function: it provides point-in-time multiples (P/L, P/VP, EV/EBITDA annual; P/L TTM quarterly) for stocks, with a precise pricing rule based on the first trading session after the actual earnings release. It also clearly distinguishes itself from the sibling `fii` tool for real estate funds, making the resource and scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states 'Só ações' (only stocks) and directs users to the `fii` sibling for real estate fund P/VP, providing a clear alternative. It also gives a concrete usage condition: WEGE3 is free while all other tickers require an API key, helping an agent decide when to invoke this tool.

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?

With no annotations, the description carries the burden and does well: it explains the side-by-side display, the fact that restatements are recorded rather than silently corrected, and gives a free-use example. It does not cover error handling or return format, but the core behavior is transparent.

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 a compact, front-loaded two-sentence summary. Every part adds value: purpose, output details, differentiator, and an example. No redundant or filler 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?

Even without an output schema, the description gives a good sense of what the result contains (ano, conta, valores, variação). It lacks information on possible empty results or authentication nuances, but for a simple tool with one required parameter, it is largely adequate.

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 description clarifies that the tool works for a company ('de uma empresa') and provides WEGE3 as an example ticker, which helps for the required 'ticker' parameter. However, the optional 'chave_api' parameter is not mentioned at all, and schema coverage is 0%, so the description only partially compensates.

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 tool's purpose: it shows republished balance sheets with side-by-side comparisons of original and restated values. It includes specific fields (year, account, old vs new, variation) and a concrete example (WEGE3), making it distinct from siblings like fatos_contabeis.

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 implies usage for a specific company's restatements but does not explicitly state when to use this tool over alternatives. The 'differential' line hints at a unique benefit, but no direct comparison or exclusion is 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only status check but does not explicitly state that, nor does it mention any side effects, authentication, or rate limits. The information given is accurate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, front-loading the core purpose and adding the 'free' note. Every word earns its place, with no redundancy or fluff.

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 simple no-parameter, no-output-schema tool, the description covers the basic functionality but lacks details about the return format or what 'contagens' refers to specifically. It is adequate for a status check but not fully complete for an agent to predict the output structure.

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 schema description coverage is 100%. Per rubric, a baseline of 4 is applied for 0-parameter tools. The description adds nothing about parameters because none exist, which is acceptable.

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 tool provides current database coverage counts and last ingestion timestamp. It identifies a specific resource (database health) and is distinct from sibling tools focused on financial data. However, it lacks an explicit verb like 'get' or 'list', so it doesn't fully meet the 5-level criterion.

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 provides no guidance on when to use this tool versus alternatives. It does not mention alternatives, prerequisites, or typical use cases. The only additional note is that it is 'free', which is not a usage guideline.

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?

No annotations are provided, so the description must fully disclose behavior. It does mention that banks do not have Piotroski scores and that WEGE3 is free, which is useful context. However, it does not clarify return format, authentication requirements, any side effects, or what happens if the account is not open. The 'com a conta aberta' prerequisite is vague and unexplained.

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 concise at three sentences and front-loads the main purpose. Some details like 'cada um dos 9 critérios auditável' are useful but could be trimmed; overall it is well-organized and avoids fluff.

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?

The tool has no output schema and only two parameters, so the description is the main source of context. It explains the two scoring methodologies and includes exceptions, which is helpful. However, it lacks parameter semantics, auth details, and explicit usage guidance, leaving noticeable gaps for an agent 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, but it only implicitly mentions the ticker by giving 'WEGE3' as an example. It does not explain the format or meaning of the 'ticker' parameter, nor does it mention the 'chave_api' parameter at all. This leaves the agent with insufficient information to correctly populate both arguments.

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 tool provides fundamental scores (Piotroski F-Score and Graham's criterion), mentioning specific details like the 0-9 range and the P/L × P/VP ≤ 22.5 threshold. It distinguishes itself from sibling tools by naming these specific scoring methodologies, though it lacks an explicit verb like 'calculates' or 'returns'.

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?

No explicit guidance is given on when to use this tool versus alternatives. The phrase 'com a conta aberta' implies a prerequisite (open account) but does not explain it, and there is no mention of situations to avoid or sibling comparisons. The only concrete usage hint is that WEGE3 is free, but that does not help an agent decide when to invoke this tool.

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?

No annotations exist, so the description carries the full disclosure burden and does so thoroughly: it explains the ~100-day CVM publication lag, the `disponivel_em` field, survivorship bias in the universe, exclusion of flagged values, and the `chave_api` requirement. These are behavioral facts an agent could not infer from the schema.

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 dense and every sentence carries useful information, and the core purpose is front-loaded. However, it is a long single paragraph; the `as_of` explanation is especially heavy and could be structured as a short list without losing 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?

Despite having no output schema, the description covers everything needed to invoke the tool correctly: filter syntax, date modes, exclusions, bias caveat, and auth. It even mentions the `disponivel_em` field in the response, so the agent is not left completely blind about output shape.

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 fully: it explains the `filtros` dict with a concrete example, enumerates every supported indicator and the _min/_max suffix convention, and clarifies `ano` vs `as_of` semantics. The only minor issue is that `chave_api` is described as required while the schema gives it a default and does not require it, but this does not reduce the semantic value added.

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: 'Filtra as AÇÕES do universo por faixas de indicadores'. It also immediately distinguishes itself from `screener_fiis`, so an agent can tell exactly what this tool does without opening the schema. There is no ambiguity about the stock universe.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use and when-not-to-use guidance: stocks only, with FIIs routed to `screener_fiis`. It also tells the agent when to use `as_of` ('para pesquisa sem olhar o futuro') and states that `ano` and `as_of` cannot be combined, which prevents an obvious misuse.

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?

With no annotations, the description carries full responsibility and covers key behaviors: inclusive bounds, exact/case-insensitive segment matching, a liquidity floor, exclusion of flagged values, ascending P/VP sorting, a 100-record cap, and API-key authorization. This is rich behavioral disclosure.

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 a tight paragraph where every sentence earns its place: it gives a mini-example, enumerates valid filters, notes data-quality constraints, ordering, limit, and auth. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description explains filtering criteria, sorting, maximum returned records, data-quality filtering, and required key, which is enough to understand the tool's behavior. The nested filtros object is fully demystified, so nothing critical 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% and the only parameter property is an unconstrained object with additionalProperties true. The description compensates by listing valid keys (pvp_min, pvp_max, dy_min, dy_max, segmento, cotistas_min) and their semantics, including inclusivity and matching rules, plus the chave_api requirement.

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 'Filtra os FIIs por faixas,' using a specific verb and resource, and immediately distinguishes this from the stock-screener sibling by scoping to FIIs. It further specifies ordering and output cap, making the tool's role unmistakable.

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 clearly establishes this tool is for filtering FIIs by range-based criteria ('por faixas') and gives the exact accepted keys. It does not explicitly name alternatives or exclusion scenarios, but the FII-specific scope provides clear enough context.

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?

With no annotations provided, the description carries the full behavioral burden and exceeds it: it discloses the Q4 absence ('O 4º TRIMESTRE NÃO VEM'), the deliberate no-derivation policy for Q4, the sector-specific indicator gaps for banks and insurers ('Banco e seguradora recebem só margem líquida e ROE'), and the conditional API-key requirement. These are non-obvious facts an agent cannot infer from the schema and are exactly the kind of behavior that prevents failed or misinterpreted calls.

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 is front-loaded in the first sentence, followed by four short paragraphs each with a single job: when to use, the Q4 caveat, the sector limitation, and the auth requirement. Every sentence earns its place — even the rationale for not deriving Q4 ('número calculado por nós não entra na mesma lista dos que a companhia reportou') prevents the agent from wrongly expecting or computing that value. No filler or restatement of the schema.

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?

This tool has real complexity — missing Q4, sector-specific indicator availability, conditional auth — and no output schema or annotations to fall back on. The description covers all the major caveats, the content categories returned, and routes to the correct sibling. The remaining gap is the response shape: since there is no output schema, a brief note on how the quarterly series is structured per period would fully round it 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 must compensate for both parameters. It does add real meaning: chave_api's conditional necessity is explained ('WEGE3 gratuita; demais exigem chave_api'), and 'WEGE3' implicitly signals the Brazilian ticker format for the ticker parameter. However, ticker format is never explicitly stated (e.g., 'use the code with exchange suffix'), leaving a small gap for a parameter whose schema entry is bare.

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 opening line states exactly what the tool provides: 'Série TRIMESTRAL de uma AÇÃO: contas da ITR, preço do trimestre e indicadores (margem bruta, margem EBIT, margem líquida e ROE TTM).' This names the resource, its periodicity, and its specific contents, which clearly separates it from the annual-series sibling indicadores_anuais. The only minor stylistic point is the absence of an explicit verb, but the noun-phrase structure communicates the return value unambiguously.

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 explicit trigger condition — 'Use quando a pergunta for sobre o ANO CORRENTE ou o trimestre mais recente' — with concrete example queries, and explains WHY the alternative fails ('a série anual só responde depois que o exercício fecha, e fica até um ano defasada'). It also names the alternative directly: 'Para o ano fechado use indicadores_anuais.' This is textbook when-to-use-vs-alternative guidance.

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