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

Annotations already declare readOnlyHint and openWorldHint, and the description adds genuinely useful context beyond them: quarterly filing cadence, the 45-day post-quarter lag, and the critical limitation that only long US positions are shown. That last caveat prevents the agent from misreading the output as a complete portfolio. It stops short of 5 because it doesn't say how "latest quarter" resolves for managers who haven't filed yet or what happens for non-13F filers.

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?

Front-loaded with what the agent gets back, then how to look it up, then the data caveats — a sensible order with no filler sentences. It is dense and slightly run-on, packing the change-summary enumeration into one long clause, but every element carries information.

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 only two parameters, full schema coverage, and no output schema, the description carries the return-value burden well by enumerating the fields returned (positions, share of portfolio, total value, changes) and the data's freshness limits. It is nearly complete; the only missing piece is failure behavior for funds without a 13F filing.

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 the baseline is 3, but the description earns extra credit by illustrating the `fund` parameter with recognizable legal-name forms ('Pershing Square Capital', 'Berkshire Hathaway', 'Scion Asset Management'), clarifying that informal names like "Berkshire" vs. exact legal names are acceptable. The `top` parameter is only obliquely referenced via "top positions by value," leaving its default and cap to the schema.

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 resource (13F-reported institutional holdings) with a precise verb-like framing: top positions by value, share of portfolio, total value, and quarter-over-quarter changes. The parenthetical scope ("any manager with $100M+ in US stocks") and the contrast with insider_trades or filing_search is implicit but the resource is unmistakable, so an agent can pick it out of the sibling list without opening the schema.

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?

Gives concrete lookup keys (manager legal name with three real examples, or SEC CIK) and states the data cadence and lag ("quarterly, filed up to 45 days after the quarter ends"), which tells the agent when this data is appropriate versus a live quote tool. It does not explicitly name a sibling alternative or say when not to use it (e.g. for non-US or short positions), so it falls short of full routing guidance.

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