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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered, but the description adds real behavioral value beyond that: sort order ('largest first'), the presence of change-since-previous-report data, and the divergent insider payload. It stops short of noting pagination semantics or that missing holders return nothing, which would be the remaining useful disclosures.

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 the usage trigger before the argument and return details, with no filler phrasing. The return enumeration is dense and slightly run-on, but each clause carries information an agent would otherwise have to guess.

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 an output schema exists, the description need not spell out return fields — yet it does, and consistently with the declared payload. The main remaining gap is that pagination (page/limit) is undocumented in both description and partially in schema, which matters for a tool with a default limit of 15 over potentially large holders.

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 only 25%, so the description has to carry the load, and it partially does: it explains the 'holder' argument (name or find_holder id) and the 'changes' filter values with intent ('optionally changes'). But page and limit — both user-facing pagination controls with min/max bounds — get no mention, leaving half the parameters undocumented in the description.

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

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

The description states a specific verb and resource ('what an investor, fund, fund family or insider owns') and enumerates the concrete payload (positions, shares, value, share of holdings, change since previous report, insider trades). It is clearly distinguishable from the sibling get_company_ownership and get_company_substantial_holders, which pivot on the company rather than the holder.

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

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

It gives explicit trigger conditions ('Use this when someone asks what an investor... owns, what it bought or sold in its latest report, or who a holder is') and names find_holder as the companion tool that supplies the id. It does not, however, say when to prefer a sibling such as compare_peer_ownership or get_company_ownership instead, so the routing guidance is one-directional rather than a full when/when-not.

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