bdr

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

With no annotations, the description carries the full burden and does well: it discloses the free-key requirement and the single free ticker (AAPL34), enumerates the fields returned (rentabilidade com/sem proventos, proventos, desdobramentos), and explicitly scopes out what is absent (código lá fora, proporção BDR:ação). It also clarifies the non-advisory nature.

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

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

Front-loaded with the resource identity, then split into two clearly delineated mode paragraphs, with a final caveat sentence. Length is justified by the two operating modes, and backticks aid scanability; only slightly 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?

For a 3-optional-param, no-output-schema tool, the description covers both modes, access/auth requirements, and the per-mode return contents. Reasonably complete for correct invocation; pagination or list size limits for the empty-ticker listing are not addressed.

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

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

Schema coverage is 0% (titles only, or default), so the description must compensate and largely does: it explains `ticker` (empty=list, filled=cadastro), `tipo` (filter, e.g. "DRE"), and `chave_api` (required except AAPL34). Only minor gaps remain around accepted `tipo` values, which are partially implied by DRN/DR1/DR2/DR3/DRE.

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

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

States a specific resource (BDRs negociados na B3 – recibos de ações/ETFs listados lá fora) with concrete examples (AAPL34, NVDC34, IVVB39) and two clear operating modes. It is easy to tell what the tool does, though it does not explicitly distinguish itself from the sibling bdr_precos.

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

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

Gives explicit mode-selection guidance: `ticker=""` lists all BDRs that traded in the last year, while a concrete `ticker` returns the cadastro detalhado. It also states the access condition (AAPL34 is open; the rest require chave_api). It lacks any when-not-to-use or named alternative among the many siblings.

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