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

Annotations already cover read-only/idempotent/non-destructive behavior. The description adds useful behavioral context: the data is derived from the sworn tape, starts in 2011 and ends with 2024 filings, excludes feeders/quarantined readings for GAV, and is explicitly non-predictive. This goes beyond annotation payload and helps set expectations.

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, long, dense sentence with a colon-separated list. It packs a lot of information but lacks structural breaks; it's not as scannable as it could be, though every clause does carry meaning.

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 tool with no output schema and three parameters, the description explains the data's provenance and limitations, but leaves ambiguity about whether all series are returned at once or selected via view, and is silent on limit. The agent could still call it, but might mispredict output shape.

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

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

Schema coverage is only 33%, with only min_gav_usd described. The description's list of series maps loosely to the view enum values, but never states that the view parameter selects one of these series, nor explains the limit parameter. Since schema coverage is low, the description should compensate but only partially does.

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

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

The description explicitly states this returns derived trend series over the sworn tape and enumerates six specific series (vehicles by year, managers by year, GAV by year, vintages, drops, top managers). That differentiates it clearly from sibling get_ria_trends and search tools, which focus on individual records or other asset classes.

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

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

No explicit when-to-use or alternative guidance. The description implies it is for annual trend analysis of real estate fund activity and mentions data range caveats, but never says 'use search_re_fund_* for current individual records' or similar. Siblings like get_re_fund_vehicle and search_re_fund_managers are left unaddressed.

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