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

Annotations already establish readOnlyHint=true, and the description adds genuinely useful context: the state reported is local and is split per dataset, which tells the agent this is an inspection of on-disk state rather than a remote listing. It does not say whether the status is a cached snapshot or freshly verified, nor whether a stale cache still counts as downloaded, which matters given openWorldHint=true.

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 short sentence with no filler, and the key qualifiers ('already downloaded and parsed', 'per dataset') come immediately. It is efficient but borders on telegraphic, reading more like a table caption than a usable instruction.

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 an output schema present, the description need not explain the returned shape, and with no parameters there is nothing else to specify. What remains missing is the operational relationship to refresh_cache and load_dataset, which an agent needs to sequence calls 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?

The tool takes zero parameters, so the schema is complete by definition and the description cannot add parameter meaning. The phrase 'per dataset' usefully signals that the dataset key is the unit of the returned grouping even though no argument is supplied.

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 sentence names the resource (the local cache) and the scope it reports on (already downloaded and parsed data, broken down per dataset), so an agent knows this is a status/inspection read rather than a fetch. It is not a clean verb+resource phrasing and never names the closely related siblings list_datasets, describe_dataset, or refresh_cache, so differentiation is left to 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?

There is no when-to-use or when-not-to-use guidance and no reference to alternatives. An agent has to guess that cache_status should be consulted before load_dataset or run_query, and that refresh_cache is the tool that changes the state this one reports, rather than being told.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely non-obvious behavior: columns are served from a local cache and can be empty until a data tool is called, which an agent 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 return contents are front-loaded in the first sentence, followed by the cache caveat and the detail flag. The parenthetical examples earn their place by making the detail output concrete, though the prose is slightly dense.

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

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

An output schema exists, so return values need not be spelled out, and the cache-population caveat covers the main surprise an agent would hit. The only gap is that the relationship to list_datasets and run_query is 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?

Schema description coverage is 100%, so the baseline is 3. The description does add some meaning for detail=True by explaining that column_details covers units and pitfalls with concrete examples (VL_CONTA vs VL_CONTA_BRL, FRE percentages), but it says nothing about the table parameter beyond what the schema states.

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

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

The first sentence names a specific verb and resource ('Show the tables, cached periods and columns of one dataset'), which is far more precise than the sibling list_datasets or cache_status. It does not explicitly name a sibling to contrast with, 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 a concrete conditional workflow: if a table was never queried, call the corresponding data tool once to populate columns, and use detail=True to get units and pitfalls. It lacks an explicit 'use this instead of X' routing statement against siblings like list_datasets or run_query.

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 and openWorldHint, and the schema documents the max_rows safety cap, so the safety profile is covered elsewhere. The description's only added behavioral signal is that results form a compact series over time, which usefully sets expectations about result density but says nothing about multi-company merging, ordering, or gaps in years.

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

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

A single front-loaded sentence with no filler; the core scope appears first and the qualifier follows. It is efficient, though arguably so terse that it leans toward under-specification rather than crispness.

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 nine parameters, an output schema, and full annotation coverage, the heavy lifting is done by structured fields, so the description needn't repeat them. Still, for a tool spanning multiple companies and two data granularities (dfp/itr) with a row cap, one sentence leaves gaps around multi-company behavior and year-range semantics that a slightly richer description could close.

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 100%, and each parameter (account, by, doc_type, data_type, first_year/last_year, max_rows) already carries its own explanation. The description's phrase 'one account' loosely echoes the account parameter but adds no new semantics such as how `by` interacts with name fragments or how the year range is applied.

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 gives a concrete verb and resource: 'follow one account over time' across 'one or more companies', and the '(a compact series)' parenthetical signals this returns a lean time series rather than full statements. It stops short of naming siblings like get_financial_statements or get_statement_summary, so the boundary is implied rather than stated.

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: 'compact series' suggests you pick this over full statement retrieval when tracking a single metric over years. There is no explicit when-to-use or when-not-to-use guidance, and no mention of when to prefer the multi-account or summary 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 readOnlyHint=true and openWorldHint=true, so safety posture is covered. The description adds nothing further: it says nothing about what the 'version' flag does to results, whether historical versions are returned together, or how large the response can be.

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?

At eight words it is certainly short and the key content words lead, but it is a sentence fragment rather than a complete, front-loaded statement of purpose, so brevity here reflects under-specification more than discipline.

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 an output schema present and full schema coverage, the description's only real job is to state what the tool returns and when to use it over siblings; it half-satisfies the first and completely omits the second, leaving an agent guessing at routing.

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 100%, including the meaning of cd_cvm ('CVM code from search_company') and the version enum semantics, so the schema carries parameter meaning. The description adds no parameter context beyond that, which is the baseline for full-coverage schemas.

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 resources returned (board, officers, fiscal council composition) but is a bare noun phrase with no verb, so the agent must infer that it retrieves governance membership data. It distinguishes the topic from siblings like get_shareholders or get_compensation, but only loosely.

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 when-to-use guidance, no indication of prerequisites (e.g., that cd_cvm comes from search_company), and no mention of which alternative to pick for related governance data such as governance_practices, get_shareholders, or get_compensation.

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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the data categories but does not explain event scope, historical coverage, or pagination behavior; no contradiction with annotations.

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

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

The description is a single front-loaded fragment with no wasted words. It is very concise, though the noun-phrase form is less clear than a complete sentence stating the action.

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 query tool with an output schema and fully documented parameters, the description covers the core data retrieved. It leaves event scope and usage context implicit, which matters for selecting it among many 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?

Schema description coverage is 100%, and all three parameters are documented in the schema, including the meaning of version values. The description adds no additional parameter meaning, so the baseline 3 applies.

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 the resource as share capital events and enumerates the data categories returned (amounts, approvals, share counts). It lacks an explicit verb and does not distinguish itself from siblings, but no sibling appears to cover the same capital-event data.

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 guidance, no prerequisites beyond what the schema implies, and no alternatives named. Usage is only implied by the resource name and data list.

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 readOnlyHint/openWorldHint annotations, the description discloses an important behavioral trait: it downloads and parses the entire year, and the first call can be slow. That latency warning is exactly the kind of context an agent needs before invoking. It does not say whether results are cached afterward, but this is a solid addition over 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?

Two short sentences, front-loaded with the purpose followed by the cost warning; nothing is wasted. The parenthetical is slightly informal but functional.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a tool whose main value is deciding what to fetch next, the description omits how it relates to get_fre_table and whether the expensive download persists across calls.

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 100%, and the schema already documents both year and cd_cvm (including pointing to search_company for the code). The description only reinforces the company-year granularity, adding little semantic detail beyond the schema, so the baseline of 3 applies.

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: it shows which FRE tables contain data for one company-year, which refines the vague name 'get_company_overview'. It does not mention the closely related siblings list_fre_tables or get_fre_table, so an agent must infer the division of labor.

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?

Use as a discovery step before fetching a specific FRE table is only implied, not stated; there is no explicit 'use this when' or exclusion of get_fre_table/list_fre_tables. The one-year scope does hint at when the tool applies, but the agent must infer it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered and the bar is lower. The description adds essentially nothing beyond that: it does not mention the version selection (last/first/all), the aggregation detail modes, or the date/versioning behavior of the data, all of which materially change 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?

It is a single short sentence with no filler, so nothing needs trimming. However, its brevity comes at the cost of substance rather than from tight editing, and it is not front-loaded with any actionable instruction.

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 rich schema (including enums) and the existing output schema remove the need to explain parameters or return values. Still, for a tool with four parameters and three similar governance siblings, the description leaves the selection decision and the effect of the version/detail options entirely to the 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 description coverage is 100%, so every parameter (year, cd_cvm, detail, version) is already documented in the schema with defaults and enum meanings. The description adds no additional parameter semantics, which matches the baseline 3 when the schema does all the work.

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 resource (compensation) and its scope (board, officers, fiscal council), so an agent knows what data comes back. But it is a bare noun phrase with no verb and no differentiation from nearby tools such as get_board or get_capital, which cover overlapping governance subject matter.

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 when-to-use guidance, no prerequisite (e.g. that cd_cvm must come from search_company), and no named alternative or exclusion. The agent must infer from the name alone that this is the compensation-specific lookup rather than get_board or governance_practices.

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 annotations already declare this as a read-only, open-world operation, so the description's main added value is domain context: it defines inadimplencia_pct and cites the FIDC monthly report tables. It does not discuss permissions, rate limits, or return shape, but an output schema exists and the safety profile is already covered.

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 short and front-loads the dashboard contents before defining the delinquency metric. The metric definition and table references earn their place, though the first sentence is a noun phrase rather than a direct statement of the tool's action.

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 read-only report tool with a complete input schema and an output schema, the description supplies enough domain context to call it correctly. It does not cover every behavioral detail, but nothing critical for selecting or invoking the tool 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 100%, so fund, first_period, and last_period are already documented in the input schema. The description adds no parameter-specific syntax or constraints beyond the FIDC report context, making the baseline 3 appropriate.

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 the resource as a credit-fund dashboard and lists the specific content returned: assets, portfolio, net asset value, and delinquency. It is clear enough to distinguish this FIDC report from generic fund NAV or portfolio siblings, though it does not explicitly name those alternatives.

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 phrase 'Credit-fund dashboard' implies use for FIDC-level reporting, but the description gives no explicit when-to-use guidance or comparison with siblings such as get_fund_nav, get_fund_portfolio, or rank_funds. Usage is therefore inferable but not directed.

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=true and openWorldHint=true, so safety and network access are covered. The description adds the output shape (CSV, one row per account, VL_CONTA and VL_CONTA_BRL columns), which is real context, but says nothing about the max_rows truncation behavior, rate limits, or what happens when the cap is hit.

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 short sentences, front-loaded with the resource and output format, with the row structure following immediately. No filler, though the value-column detail is close to what the output schema likely already carries.

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 an output schema present, return values needn't be spelled out, and annotations cover the read-only profile. But for a 7-parameter extraction tool whose main failure mode is hitting max_rows, the description gives no guidance on scoping, truncation, or how the year/doc_type filters shape 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 100%, so all seven parameters (format, doc_type, data_type, year range, max_rows) are already documented in the schema, and the baseline of 3 applies. The description adds only that cvm_codes refers to companies; it does not explain how doc_type/format interact with the returned lines.

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 and granularity: 'full statement lines for one or more companies, as CSV', with 'one row per reported account'. That implies line-level detail as opposed to the sibling get_statement_summary without naming it, so an agent can broadly distinguish the two but gets no explicit routing statement.

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: 'full statement lines' suggests detailed/raw extraction rather than summarized views, but the description never says when to pick this over get_statement_summary, list_account_codes, or get_account_history. There are no exclusions or prerequisites 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the useful framing that this is the generic fallback path, but says nothing about the max_rows cap (50000), pagination/truncation behavior, or cost of wide queries — the traits that actually matter for a broad table-read 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?

Two sentences, front-loaded with what the tool does, then the routing hint. No filler. The second sentence is a fragment but reads cleanly and earns its place by flagging the fallback role.

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 an output schema and full parameter coverage, the description doesn't need to explain return values. However, for a 7-parameter generic query tool it omits any note on the row cap, version semantics ('first'/'last'/'all'), or which curated helpers to prefer — gaps the structured fields don't fill.

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 100%, so 'table', 'cd_cvm', 'columns', 'version', 'first_year', 'last_year' and 'max_rows' are all self-documenting; baseline 3 applies. The description's mention of company/year filtering adds a light framing but no semantics beyond what the schema already provides.

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 ('Read rows from one FRE table') and names the two filter dimensions (company and year). It positions itself against curated helpers but does not name any of them (get_financial_statements, get_shareholders, etc.), so sibling differentiation is directional rather than concrete.

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 phrase 'prefer the curated helpers when they fit' implies a when-to-use rule, but never names those helpers or states the conditions under which they 'fit'. An agent must infer both the alternatives and the selection criteria from the sibling list.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely non-structured behavioral context: for certain fund categories the call will yield no flow series, which warns the agent to expect empty/partial results rather than assume failure. It says nothing about units, currency, or ordering of the flow values.

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 lines with the core payload stated first and the eligibility caveat following, so nothing is buried. The dense domain abbreviations (FIF, FAPI, FII, FIDC, FIAGRO, Informe Diário) pack a lot into little space and are left unexplained, which slightly taxes comprehension.

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

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

An output schema exists and all three parameters are documented, so the description only needs to add the non-structural pieces, which it does via the fund-type eligibility rule. What remains missing is where to go for flows of the excluded fund types and any note on units or period granularity of the returned 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 description coverage is 100%, with fund, first_period and last_period each documented in the schema itself, so the baseline of 3 applies. The description adds no further meaning about period format, defaults, or how partial fund names are matched beyond what the schema already states.

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 concrete resource (subscriptions, redemptions, net flow) and scopes it to a single FI fund on a monthly basis, so the agent knows exactly what data comes back. It does not explicitly distinguish itself from nearby siblings such as get_fund_nav or get_fund_portfolio, which is the only thing keeping it from 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?

The second and third sentences give an explicit applicability rule: only FIF/FAPI publish a daily subscription/redemption series (Informe Diário), while FII, FIDC and FIAGRO have no flow series in the monthly report. That is strong when-not-to-use guidance, but it never names the alternative tool an agent should call for those fund types, so routing is still partly 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?

The annotations already cover the read-only and open-world profile. The description adds genuine behavioral context beyond them: the tool auto-routes to the correct CVM dataset, and it discloses that FIF/FAPI data is daily while FII/FIDC/FIAGRO data is monthly, which materially affects interpretation. It stops short of mentioning row truncation or pagination behavior around max_rows.

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 leading sentence front-loads the purpose and the mechanism, and the bullet list is compact and scannable per dataset type. Every line conveys distinct information; no filler. Slightly more markup than strictly necessary, but it aids 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?

An output schema exists, so the description need not explain return values, and annotations carry the safety profile. What remains is a simple read-only lookup with four documented parameters, which the definition covers adequately. Minor gap: no note on how fund name matching or date-range defaults interact.

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 100%, so the schema already documents fund, max_rows, first_period and last_period. The description adds no syntax or format guidance for these parameters. The dataset bullets give indirect signal about which period granularity to expect, which is why this sits at the baseline rather than a 2.

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: 'NAV time series for any fund', and adds the key mechanism, routing to the correct CVM dataset. The per-dataset bullet list makes the returned content concrete for each fund type. It does not explicitly distinguish itself from the closest siblings (get_fund_flows, get_fund_portfolio), which keeps it 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?

Usage is implied by the enumeration of supported dataset types (FIF/FAPI, FII, FIDC, FIAGRO), so an agent can infer it applies to any fund. There is no explicit when-to-use versus get_fund_flows or get_fund_portfolio, and no stated prerequisites or exclusions. Adequate but leaves the sibling 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 declare readOnlyHint and openWorldHint, so safety is covered; the description adds real behavioral detail by disclosing the long-form row-per-component output and BRL denomination, which is not derivable from the schema. It stops short of covering truncation, since max_rows caps at 50,000 and the description never warns that results may be silently capped or how completeness can be detected.

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 one-line purpose followed by three tightly scoped bullets that each map to a fund class, plus a single line on output shape — no filler and no restatement of the name. Minor loss: the bullets spend words on dataset internals while the routing decision (the actual call-time concern) is only implicit.

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 four parameters, full schema coverage, an output schema, and read-only annotations, the description covers the genuinely complex part — heterogeneous payloads per fund class — which an agent cannot infer from structured fields. Missing only edge behavior: what happens for an unmatched fund name, and whether a capped result is distinguishable from a complete one.

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 100%, so `fund`, `block`, `period`, and `max_rows` are all documented in the schema, and the description adds no format or syntax guidance beyond it. It introduces the `component` concept used in the output but does not tie it to any parameter, so baseline 3 applies.

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 ('Holdings of any fund') and immediately explains the routing behavior across three fund classes, listing exactly what each dataset returns (CDA portfolio fields, balance-sheet composition, credit portfolio by segment). This is concrete enough that an agent can predict the payload shape and distinguish it from siblings like get_fund_nav or get_fidc_report.

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 routing language — the tool claims to pick the right dataset for whatever fund is passed, which tells the agent it does not need to resolve the fund type first. However, there is no explicit when-to-use vs. when-not, and no mention of the closely overlapping sibling get_fidc_report, so an agent facing an FIDC still has no stated rule for choosing between them.

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=true and openWorldHint=true, so the safety profile is covered. The description adds genuine context – the CVM/VLMO Instruction 358 provenance and the fact that this is a raw transaction-level signal dataset – but says nothing about row limits (max_rows default 2000, cap 20000), truncation behavior, or historical coverage bounds beyond those already in 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?

Two tight sentences, front-loaded with the entity scope and followed by the payload contents. Nothing is wasted, though the second sentence partly duplicates what the output schema already conveys.

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 an output schema present and full parameter coverage, the description only needs to frame scope and provenance, which it does. The remaining gap is disambiguation from insider_summary and the aggregate-vs-raw distinction, which matters for a dataset with 30+ siblings.

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 100%, so every parameter including company, role, operation, first_year/last_year and max_rows is already documented in structured form. The description merely enumerates returned fields (role, movement type, date, quantity, unit price, volume) without adding syntax or semantics beyond the schema, so the baseline 3 applies.

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

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

States the resource precisely – transactions by controllers, officers and board members – with its regulatory provenance (CVM/VLMO, Instruction 358). An agent knows exactly what dataset is behind the tool, though it is not explicitly contrasted with the sibling insider_summary.

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 says what the dataset is but never says when to choose this tool over insider_summary, get_shareholders or get_compensation. There are no exclusions, prerequisites, or alternative-routing hints, leaving the agent to infer selection from names alone.

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=true and openWorldHint=true, so the safety profile is covered. The description adds nothing behavioral beyond that: it does not say the data is a point-in-time snapshot tied to the required year, how the 'first'/'last'/'all' version choice affects results, or whether large holders are paginated by max_rows.

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 short sentence with zero filler and the core concept (ownership and stake size) front-loaded. Its brevity is genuine conciseness rather than padding, though the fragment style leaves it slightly informal.

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

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

An output schema exists and the input schema is fully described, so the description need not cover return values or parameter formats. However, for a tool requiring both a CVM code and a year with a non-obvious version selector, the description leaves the agent without any operational context beyond 'this is about shareholders.'

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 100%, so all four parameters (year, cd_cvm, version, max_rows) are documented in the schema and the baseline is 3. The description contributes no additional parameter meaning, such as what 'version' means for amended shareholder filings.

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?

"Shareholder position: who owns the company and how much" identifies the resource (ownership stakes) and adds a hint that magnitude/stake size is included, but it is a noun-phrase fragment rather than a specific verb+resource statement. It gives no signal distinguishing it from related siblings such as get_capital, get_board, or get_insider_trades, which also surface ownership/governance data.

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 when-to-use guidance, no prerequisites (e.g. obtaining cd_cvm via search_company first, though the schema hints at that), and no named alternatives. An agent must infer from the name alone whether this or get_insider_trades / get_capital is the right call for an ownership question.

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=true and openWorldHint=true, so the safety profile is covered. The description adds that output is organized by a `role` column with named values (total_assets, equity, revenue, ebit, net_income), which goes slightly beyond annotations, but since an output schema exists this is largely redundant and no scope caveats, defaults behavior, or data-freshness context are given.

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 short sentences, front-loaded with the core purpose and then the return shape; no wasted phrasing. The parenthetical role list is slightly verbose but directly informative.

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 an output schema, annotations, and full schema parameter coverage, the description supplies enough to call the tool correctly. However, for a six-parameter tool with optional depth/doc_type/data_type knobs, it gives no orientation on how those shape the result, leaving the agent to rely entirely on structured fields.

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 100%, so all six parameters are documented in the schema, making 3 the baseline. The description adds the notion of a 'company-year' key that maps loosely to cvm_code plus year, but it does not clarify depth levels, doc_type composition, or the con/ind versus dfp/itr distinction.

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: a compact headline view of one company-year's statement totals (equity, revenue, profit). It implicitly differentiates itself from get_financial_statements by emphasizing 'compact headline' versus a full statement tool, though that contrast is never made 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?

There is no explicit when-to-use or when-not-to-use guidance and no sibling is named as an alternative. The agent must infer from 'compact headline view' that this is the lightweight counterpart to get_financial_statements, and must infer the depth/doc_type/data_type tradeoffs from the schema alone.

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=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: it does not explain the year-scoped nature of the FCA mapping, the 500-default / 5000-cap row limit, or whether results paginate. For a lookup whose results depend on a reference year, that omission is meaningful.

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

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

A single, front-loaded sentence with parenthetical examples and no filler. It is tight and readable, though at one clause it is arguably under-specified rather than merely concise.

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

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

An output schema exists, so return values need not be explained, and annotations cover the read-only profile. Still, a 4-parameter, year-scoped mapping tool with a crowded sibling list needs disambiguation from 'resolve' and a note on the year dimension; neither is present, leaving the definition thinner than the tool's complexity warrants.

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 100%, so all four parameters (year, limit, ticker, cvm_codes) are already documented in the schema and the baseline is 3. The description only implies that ticker and cvm_codes act as filters; it adds no syntax or interaction detail (e.g., what happens when both ticker and cvm_codes are supplied).

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 verb and resource: mapping tickers (with concrete examples PETR4, VALE3) to CVM codes and company names. The direction of the mapping and the output content are clear. It does not, however, contrast itself with the sibling 'resolve', which could plausibly do something similar, so an agent has to guess between 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?

There is no guidance on when to use this tool versus 'resolve', 'search_company', or 'list_companies', and no mention of prerequisites or exclusions. The only implicit usage signal is that a ticker is the input, which the schema already conveys.

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=true and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond that: no mention of the optional adopted/chapter filters, row limits, or what 'explain-or-comply' means for coverage gaps (practices not explained vs. not adopted).

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 economical sentence with the key concept front-loaded. It is not padded, though for a five-parameter tool with filtering capability it is arguably too terse rather than too long.

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?

Output schema exists and annotations cover safety, so return-value and read-only details need not be repeated. The remaining gap is the absence of any filter/usage hint for the three optional parameters, which keeps this a 4 rather than higher.

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 100%, with every parameter documented including enum-like values for 'adopted' and a chapter example. The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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 resource ('Explain-or-comply governance report') and states its content shape ('each practice and whether it was adopted'), which implicitly separates it from the sibling governance_score (a score, not a per-practice report). It never explicitly contrasts with that sibling, so an agent must infer the split.

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 when-to-use guidance, no statement of when to pick governance_score instead, and no prerequisites (e.g., company must be resolvable first via resolve/search_company). The agent is left to infer all routing decisions.

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=true and openWorldHint=true, so safety is covered. The description adds no behavioral context of its own: it doesn't explain what a 'chapter' is, how the score is scaled, whether extra data needs to be loaded first, or whether results are cached or point-in-time.

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?

It is a single short sentence with no filler, and the key scoping detail (overall and by chapter) comes early. The trade-off is that it is so terse that it reads as a label rather than an explanation of the tool.

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 only two parameters, an output schema, and read-only annotations, the structured fields cover most of what an agent needs. What is still missing is a distinction from the sibling governance tool and some indication of what 'chapter' refers to, which matters for interpreting the returned breakdown.

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 100%, with 'year' documented as a reference year of 2018+ and 'company' accepting cd_cvm, CNPJ, or name, so the schema carries the semantic load. The description adds nothing about how the parameters affect the result, which is the expected baseline here.

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 — adoption rate of recommended governance practices, broken down overall and by chapter — so an agent knows what data comes back. It stops short of distinguishing this from the sibling tool governance_practices, which sounds closely related and could easily be confused with it.

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 when-to-use guidance and no mention of when not to use it. The agent is left to infer the choice between governance_score and governance_practices purely from the names, with no exclusions or preconditions 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results are aggregates grouped by year and role, which is meaningful beyond the annotations, but says nothing about whether the output is signed net values, currency units, or how missing years are handled.

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

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

A single front-loaded sentence with no wasted clauses. The only weakness is the opaque 'VLMO' acronym, which adds length without conveying meaning to most agents.

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

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

An output schema exists, so return structure need not be explained. However, for a tool with optional year bounds and a closely related sibling, the definition leaves the aggregation behavior and sibling choice 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?

Schema coverage is 100%, so company, first_year and last_year are already documented, including the 2018+ floor. The description's 'by year and role' weakly signals that the year parameters bound the aggregation window, but adds no format or semantics beyond the schema; baseline 3 applies.

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-like resource and scope: net insider buying/selling aggregated by year and role. An agent can distinguish this from the transaction-level get_insider_trades sibling by the word 'aggregate', though the sibling is not named and the parenthetical 'aggregate of VLMO' is unexplained jargon.

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 when-to-use guidance and no named alternative. The aggregation hint implicitly contrasts with get_insider_trades, but the agent must infer that; nothing says when a detailed trade listing is preferable over this summary.

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=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: valor_total is as reported by CVM and amounts across decades are not inflation-adjusted, which is a material caveat for any comparison the agent produces.

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 short sentences, front-loaded with the purpose and followed by the one caveat that matters. No filler, though the caveat sentence could be tightened slightly and the term 'rite' is left undefined.

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

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

An output schema exists, so return structure need not be explained, and the annotations carry the safety profile. What remains is adequately covered: grouping options, optional filters via schema, and the nominal-value caveat. Only the unit/currency of valor_total is 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?

Schema description coverage is 100%, so every parameter (rite, asset_type, first_date, last_date, limit, group_by) is already documented in the schema. The description restates the grouping dimension list but adds no format, default, or semantic detail beyond it, so the baseline 3 applies.

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

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

States a specific verb+resource: total offering volume, plus the aggregation dimensions (year, asset type, issuer, lead, rite). This separates it from search_offerings and league_table by implying aggregation rather than listing or ranking, but it never names those siblings explicitly, so differentiation is left to 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?

Usage is only implied: an agent can infer this is the tool for aggregate offering volume rather than raw offering records. There is no explicit statement of when to prefer it over search_offerings or league_table, and no mention of prerequisites or data coverage limits.

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=true and openWorldHint=true, so the safety profile is covered, but the description adds nothing beyond purpose. It does not say how volume is aggregated, how ties are ordered, or whether the ranking is recomputed over the supplied date window versus all-time.

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

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

A single front-loaded sentence with no filler; the verb and ranked entity come first and the domain term is clarified in parentheses. Nothing 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?

An output schema exists so return values need not be described, and the annotations cover the read-only profile. For a tool with five optional filters and no required parameters, the main remaining gap is how those filters interact with the ranking, which is modest.

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 100%, so all five parameters (rite, limit, last_date, asset_type, first_date) are already documented in the schema. The description adds no additional meaning, such as how the date bounds constrain the ranking window; baseline 3 applies when the schema carries the burden.

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 ('Rank lead underwriters') plus the ranking metric ('total offering volume') and disambiguates the concept with the parenthetical 'ECM/DCM league table'. It is clearly distinct from siblings such as issuance_volume or rank_funds, though it never names an alternative to contrast against.

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 when-to-use or when-not-to-use guidance. An agent cannot tell from the description how this differs operationally from issuance_volume or search_offerings, nor whether filters must be paired (e.g., first_date with last_date) to produce a meaningful ranking.

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=true and openWorldHint=true, so the safety profile is covered. The description adds that the codes are 'curated' and server-understood, implying a fixed reference set, but says nothing about size, ordering, or whether the list is static versus dynamic.

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?

One short sentence with no filler, and the key noun phrase (account codes and role names) is front-loaded. It could be marginally stronger by noting the optional doc_type filter, but nothing 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 simple, zero-required-parameter reference lookup with an output schema present, the description covers what the tool returns conceptually. Return-value details are handled by the output schema, so the remaining gap is minor.

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 100% and the single doc_type parameter is documented in the schema with its allowed values (BPA, BPP, DRE, DFC_MI, DVA). The description does not mention the filter at all, so it adds no meaning beyond the schema; baseline 3 applies.

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 gives a specific verb ('List') and resource ('curated account codes and role names') plus the scope qualifier 'understood by this server', which tells an agent this is a reference/enumeration lookup rather than a data query. It is clear, though it does not explicitly contrast itself with siblings like list_datasets or list_fre_tables.

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: an agent can infer this is a discovery call to learn valid account codes before querying financial data. There is no explicit when-to-use, when-not-to-use, or named alternative, so the guidance is adequate but thin.

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=true and openWorldHint=true, so the safety profile is covered and the description's "Browse" wording is consistent with a read operation. However, it fails to disclose a meaningful behavioral trait: the status parameter defaults to 'ATIVO', so results are silently restricted to active companies unless overridden. That default-narrowing behavior is exactly the kind of context the description should surface.

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 compact sentence with the resource front-loaded and no filler. It is efficient, though the brevity borders on under-specification rather than optimal conciseness.

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

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

An output schema and full schema descriptions exist, and annotations cover the safety profile, so the core call is safe to make. Still missing are routing guidance against the many sibling company tools and any mention of the default ATIVO status filter or paging semantics, which matter for a registry-browsing tool in a crowded toolset.

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 100%, so all four parameters (limit, offset, sector, status) are documented in the schema and the baseline is 3. The description mentions only the sector filter and omits status entirely, which slightly misrepresents the filtering surface but does not contradict the schema.

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

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

States a specific verb ("Browse") and resource ("CVM company registry"), so the agent knows it is a listing tool over companies. It does not differentiate itself from siblings like search_company or resolve, which also return companies, leaving ambiguity about which one 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 when-to-use guidance at all: nothing says whether to use this instead of search_company (name-based lookup) or resolve (identifier resolution). The only hint is "optionally filtered by sector", which is a capability, not a usage rule.

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 read-only and open-world behavior. The description adds useful domain behavior: each dataset has an id, period granularity, tables, and SQL views named `<dataset>__<table>`, which goes beyond the annotations without contradicting them.

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, compact, and every sentence contributes: it states the catalog purpose, explains the entry-point role, and defines the table/view naming convention. There is no redundant wording.

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 an output schema, complete input-schema descriptions, and annotations covering safety behavior. The description supplies the remaining conceptual context an agent needs: what a dataset contains and how table identifiers relate to sibling tools and SQL views.

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 100%, so the schema fully documents `detail` and `domain`, including domain values. The description does not add parameter-specific meaning beyond that, so baseline 3 is appropriate.

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: list every CVM dataset this server understands. It also frames the tool as the entry point and clarifies that table ids feed describe_dataset and run_query, which distinguishes it from those sibling tools.

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 phrase 'This is the entry point' gives clear usage context, and the mention that table ids are used by describe_dataset and run_query implies a workflow. It stops short of explicit when-not-to-use guidance or naming alternatives, so it is strong but not exhaustive.

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=true and openWorldHint=true, so the safety profile is covered. The description adds the useful fact that the catalog is a fixed set of 36 tables, but says nothing about what the flag-on path changes or how results are shaped beyond the count.

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

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

A single front-loaded sentence with no filler; every word (verb, scope, count) carries information the agent can use.

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

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

An output schema exists, so return structure needn't be explained, and the tool is simple with one optional flag. What is missing is the workflow context tying this listing to get_fre_table, which matters for a catalog-discovery 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 100%, so the single optional 'detail' parameter is already documented in the schema as including curated key columns. The description adds no further meaning about how detail alters the listing, which is acceptable at baseline given full schema coverage.

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 gives a specific verb (List) and resource (FRE corporate tables) and even names the exact cardinality (36), so the agent knows precisely what comes back. It does not name the sibling get_fre_table, which is the natural follow-up call, 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?

There is no statement of when to use this versus get_fre_table, and no mention that this is a discovery step preceding a table fetch. The usage pattern is only inferable from the tool names, not stated in the description.

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 only declare readOnlyHint and openWorldHint; the description adds genuinely new behavior by explaining the incremental caching policy (reuse fresh archives, build only missing partitions). It does not say how long a download takes, how to detect a partially built dataset, or whether the local cache can be invalidated — but with an output schema present, the remaining omission is acceptable.

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 action in one sentence, then the sibling relationship, then the call-order advice and a pointer to a companion tool. No filler sentences; every clause carries either purpose, contrast, or sequencing.

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 annotations, a full-coverage schema, and an output schema, the description covers the workflow placement and non-destructive caching contract an agent needs. Minor gap: it does not suggest cache_status for verifying what is already loaded, which would complete the loop for repeated calls.

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 100%, so table, period, and dataset semantics are already fully documented in the schema, including the '*' wildcard, comma-separated periods, and dataset id examples. The description adds nothing specific about parameters beyond mentioning 'periods' incidentally, so baseline 3 applies.

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 verb and resource ('Download and parse a dataset/period into the local cache') and immediately positions it against a named sibling ('non-destructive counterpart of refresh_cache'). An agent can distinguish it from refresh_cache, cache_status, and run_query 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?

Gives an explicit sequencing rule ('Call it before run_query so the SQL layer has the tables it needs') and routes to a related tool for follow-up ('use describe_dataset(detail=True) for column meanings'). It also names the alternative (refresh_cache) and the condition that selects this one: archives still fresh, only missing partitions built.

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=true and openWorldHint=true, so the safety profile is covered. Beyond that the description adds nothing behavioral: it does not state ranking direction (descending vs ascending), tie handling, or whether funds with missing metrics are excluded — all material for interpreting a ranking result.

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

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

A single front-loaded sentence with the verb, scope, and metric list, and no filler. Every clause carries information an agent needs to select the tool.

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

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

An output schema exists, so return values need not be explained, and the period default is covered by the schema. However, for a ranking tool the sort direction and treatment of missing values are core semantics left unstated, leaving a real gap for a four-parameter 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 100%, so limit, metric, period, and fund_type are already documented, including the enum values and the 'latest' default for period. The description merely restates the metric options and adds no format or semantics beyond the schema, making the baseline 3 appropriate.

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 gives a specific verb (rank) and resource (FI funds) plus the exact metrics available, which lets an agent distinguish this from per-fund siblings like get_fund_nav and get_fund_flows. It stops short of naming an alternative tool, so it is clear but not fully differentiated.

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: an agent can infer this is the tool for cross-fund comparisons rather than single-fund lookups. There is no explicit when-to-use, when-not-to-use, or pointer to a sibling such as league_table, which could plausibly overlap.

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?

Adds real behavioral context beyond the annotations: the refresh is forceful (re-download, not validate), and 'CVM rewrites the current period in place' discloses a side effect. However, it says nothing about cost/latency of a full re-download, whether the operation blocks, or what happens to partitions not covered by the period filter. It also sits in mild tension with readOnlyHint=true, since a cache rebuild does mutate local state — an agent gets no help resolving that.

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 short sentences, front-loaded with the action and followed by the decision cue — no filler. The one blemish is the unexpanded 'CVM', a domain acronym that carries no meaning for an agent unfamiliar with the data source.

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 3 parameters at 100% schema coverage, an output schema, and annotations present, the description only needs to convey purpose and timing — both are covered. The remaining gap is operational: no sense of cost, duration, or blast radius when period is omitted and everything cached is refreshed.

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 100%, so the schema already defines table, period (YYYY/YYYYMM) and dataset semantics; the baseline is 3. The description modestly adds meaning by tying 'period' to staleness ('the latest month looks stale') and indicating that the operation is destructive of existing cached content before rebuilding. It does not clarify refresh scoping interactions between table and period.

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: 'Force a re-download and rebuild of cached partitions.' An agent can immediately tell this is a cache-maintenance action rather than a data read. It does not name or contrast with the adjacent siblings (cache_status, load_dataset, run_query), so the distinction from those is left implicit.

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?

'Use this when the latest month looks stale' gives a concrete triggering condition tied to the period parameter, which is more than most definitions offer. It stops short of explicit exclusions — e.g., don't use it for a full reload when only one table is stale, or when cache_status already shows the partition is current.

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 and openWorldHint, and the description adds no behavioral context such as ambiguity handling, normalization rules, or match limits. Listing the returned key types is largely covered by the output schema, so there is little 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?

One front-loaded sentence with no filler; the parenthetical output list is compact. Every element contributes to identifying the tool's purpose.

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

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

For a one-parameter, read-only resolver with rich schema and output schema, the description covers the core operation. It leaves gaps around ambiguous matches and sibling-tool selection, which an agent may need in practice.

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 query parameter has 100% schema description coverage and the schema already lists ticker, CNPJ, cd_cvm, and company name. The description's 'any identifier' adds no syntax or format detail 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 uses the specific verb 'Resolve' and states the resource, identifiers, and the canonical outputs (cd_cvm, CNPJ, ticker, name). It does not explicitly differentiate itself from sibling tools like search_company or get_tickers, 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 implies the tool is used when an agent has an identifier and needs CVM keys, but it gives no explicit when/when-not guidance and never names alternatives such as search_company or list_companies. An agent must infer the routing decision.

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 readOnlyHint and openWorldHint already present, the description adds useful behavioral context: the DuckDB engine, SELECT/WITH-only restriction, cached-table scope, and result capping via limit. It does not cover error behavior or how cached periods are discovered, but the annotations carry much of the safety profile.

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 short, front-loaded with the core operation, and then immediately states the main usage cases and query restriction. Every sentence contributes without 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 a complete input schema, an output schema, and annotations, the description is sufficient for an agent to call run_query correctly. It could be slightly stronger by pointing to dataset/table discovery tools or explaining how available cached periods are identified, but the core execution constraints are 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 100%, so both parameters are already documented in detail, including view naming and the maximum row cap. The description reinforces the read-only SELECT/WITH restriction and limit behavior but does not add syntax or format guidance beyond the schema.

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

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

The description states a specific verb and resource: run SQL across cached CVM tables using DuckDB. It also distinguishes the tool from the curated domain-specific siblings by framing it as the option for cross-dataset or otherwise unexposed queries.

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 conditions for use: questions combining datasets, aggregates not exposed by curated tools, and inspecting a table before writing a longer query. It implies alternatives through 'curated tools' but does not name specific siblings or explicitly state when not to use it.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint), and the description adds a genuine behavioral trait beyond them: matching is accent- and case-insensitive, which affects how the agent should phrase queries. It says nothing about ranking or what happens when nothing matches, but the output schema covers the return shape.

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 short sentences, front-loaded with the resource and its output, followed by the workflow rule. Every clause carries information and nothing is repeated.

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 3-parameter search with full schema documentation, annotations and an output schema, the description supplies exactly the missing piece: that this tool exists to obtain cd_cvm for downstream corporate tools. Nothing needed to call it correctly is absent.

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 100%, so the schema already documents query, limit and status. The description's list of identifier kinds essentially restates the `query` schema description, and it says nothing about `limit` or `status`, so it adds little beyond the structured fields — baseline 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 verb and resource ('Find the CVM code (`cd_cvm`) of a company') plus the accepted lookup keys (name, CNPJ, ticker, code). It is clearly distinguishable from siblings like list_companies, search_fund and resolve, since the output is explicitly an identifier rather than a record set.

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 frames the tool as 'the entry point for every corporate tool' because siblings key on cd_cvm, never the ticker — strong when-to-use guidance. It does not, however, contrast itself with the closest siblings (resolve, list_companies), so the agent must infer when to prefer those instead.

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 and open-world, so the description's job is domain behavior — and it delivers: it discloses that CVM keys data on the *class* CNPJ (so a class-level identity, not just a fund name, comes back) and that results carry a family tag from a known set (fi, fii, fidc, fiagro, fip). What's missing is ambiguity/zero-result behavior and match-ranking expectations for partial queries.

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 action and payoff in the first sentence, then a second block explaining the CNPJ/family mechanics. Every sentence carries information, though the line-broken formatting scatters related ideas slightly.

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

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

An output schema exists, so return values need no prose, and the description instead covers the prerequisite chain and the downstream family routing — the parts the schema cannot express. It is nearly complete for a two-parameter lookup, with only no-match behavior left unaddressed.

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 100% and the schema already documents both `query` (partial name, CNPJ, or CVM code, with an example) and `limit` (max matches). The description adds no accepted-input syntax or matching nuance beyond that, so the baseline 3 applies.

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 ('Find a fund or class') and, crucially, the output an agent needs ('get the CNPJ used by every fund tool'). That framing separates it from the company-side search tools in the sibling list and identifies it as the entry point for the fund tool chain.

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?

Implies when to call it: before any other fund tool, because every one requires the CNPJ this returns. It also explains downstream routing ('get_fund_nav routes automatically' based on the family). It stops short of an explicit when-not or a direct contrast with search_company/resolve, so 4 rather than 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds modest context about which offering classes are covered and the historical depth (since 1988), but says nothing about result ordering, what the default 100-row limit implies, or that unpaged result sets can be truncated.

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

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

A single front-loaded sentence with no padding or redundancy. It is efficient, though the terseness leaves the usage and behavioral gaps unaddressed rather than the sentence being wasteful.

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 six optional filters, no required parameters, and an output schema handling return values, the description still omits essential calling context: how filters combine, whether partial matching applies to issuer only, and what ordering to expect. For a broad open-world search tool this is under-specified even accounting for the annotation and schema coverage.

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 100%, so every filter (rite, issuer, asset_type, first_date, last_date, limit) is already documented with examples and formats in the schema. The description's only addition is the temporal bound implied by 'since 1988', which slightly informs first_date but adds little beyond the schema.

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

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

The description gives a clear verb+resource ('Search ... public offerings') plus meaningful scope qualifiers — registered, exempt and restricted categories and a start year of 1988. It does not distinguish itself from adjacent siblings such as issuance_volume or league_table, which also touch the offerings domain, so the agent must infer 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?

There is no when-to-use or when-not-to-use guidance and no named alternative. The agent is not told whether to reach for this tool versus issuance_volume or league_table when it wants offering-related data, nor what happens when no filters are supplied.

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