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

Annotations already establish the safe read-only, non-open-world profile, and the description layers substantial extra behavior on top: single-count dedup by CIK and SEC reporting links, registered funds shown but excluded from sums, negative float flagged rather than clipped, and foreign private issuers receiving no % or remainder. This is exactly the kind of non-obvious semantics that structured fields cannot convey.

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 scope statement is front-loaded and nearly every sentence carries unique information that a caller needs. It is dense to the point of being hard to parse in the dedup sentence ('the filers and persons of any 13D or 13G that names a 13F filer... by CIK and SEC reporting links'), which slightly hurts readability, but length is justified by the domain complexity.

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 no output schema, the description carries the return burden and does so well: it states the units (shares and % of shares outstanding), the holder-type/style/location breakdown, and the negative-remainder flag. It omits only secondary call logistics such as response shape for a single ticker versus batching, so it is strong but not exhaustive.

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% across both parameters, so the baseline is 3. The description's 'view=ultimate adds the largest ultimate parents' essentially restates the schema's own description of view, adding no new syntax or format detail 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?

Precise verb+resource with an unusually specific scope: it enumerates exactly which ownership classes are included (13F institutions, insiders Forms 3/4/5, 13D/13G blocks, residual float) and what is not summed. An agent can distinguish it from GetTopHolders or GetHolderMix by content, but no sibling is named explicitly, so it falls 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 through the inclusion/exclusion rules and the note that view=ultimate adds ultimate parents, which tells the agent when to pick that mode. However, there is no explicit when-to-use guidance against the many overlapping siblings (GetBeneficialOwnership, GetInsiderOwnership, GetAllHolders), leaving the routing decision to inference.

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