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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description goes substantially beyond that by defining the status taxonomy — notably that an unconfirmed 13D/13G is retained rather than assumed sold, and that 'below 5%' reflects the end of the duty to amend rather than the holding. It does not cover pagination/rate behavior, but that is a minor gap given the annotations.

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?

It is front-loaded with the core action and the field inventory, then closes with disambiguation and prerequisites, so the ordering is sound. It is, however, a single dense paragraph with long semicolon-chained enumerations of return fields and statuses, which is harder to scan than it needs to be for its length.

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?

There is no output schema, so the description carries the return-shape burden and does so thoroughly: event and filing dates, accession, split-restated shares, percent of class, change since the filer's prior filing, Item 4 purpose, and the full status enumeration. With 100% schema coverage on inputs and this level of return documentation, an agent has enough to call and interpret it correctly.

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 100%, so all four parameters are already documented, giving a baseline of 3. The description adds real meaning to includeHistory (it enumerates what the 'rest' actually is: below 5%, exited, retired securities) and to institutionName (unique partials resolve, ambiguous ones return candidates), but adds nothing for offset or maxResults.

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 opens with a precise verb+resource ('Get the Schedule 13D and 13G stakes a named institution has disclosed') and immediately delimits scope against the obvious confusion point: event-dated 5% stakes versus the 13F book in GetInstitutionPortfolio. It even explains the resolution behavior for filers that file only 13D/13G, which separates it from the broader 13F-oriented siblings.

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 states the default listing behavior ('Current and unconfirmed stakes list by default; includeHistory adds the rest'), names the alternative for the portfolio use case ('GetInstitutionPortfolio covers the 13F book'), and routes CIK resolution to SearchInstitutions. When-to-use and when-not-to-use are both explicit.

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