Summarizes net insider buying and selling by year and role for a Brazilian company from CVM filings, with optional year-range filters.
Net insider buying/selling by year and role (aggregate of VLMO).
| Name | Required | Description | Default |
|---|---|---|---|
| company | Yes | cd_cvm, CNPJ or company name. | |
| last_year | No | Last year. | |
| first_year | No | First year (2018+). |
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Changes observed during successful MCP inspections.
v0.1.1Does 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.