Institutional holders (13F)

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

Annotations already declare this a read-only, open-world operation, and the description adds substantial behavior beyond them: only managers filing both quarters appear in the change column, a first-time filer is labeled, a suspicious thousands-scaled value is flagged, and every response is prefixed with a fixed quarter/publish-date sentence. It also explains the non-idempotent feel (latest quarter changes) and the exact degraded-case message.

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?

Purpose and key qualifiers are front-loaded and every clause carries information (quarter semantics, exclusions, error case). The delivery is one dense run-on sentence chain, which slightly hurts scanability for a tool with only two parameters.

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 burden of describing return content, and it does: per-manager share counts plus prior-quarter change, totals, filer counts, flagged anomalies, and the mandated leading sentence. Combined with the unmapped-ticker explanation, an agent has everything needed to call and interpret it.

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% and both parameters are already described there, including the exact ticker/contract format and the 1-20 range with default 10. The description adds only marginal semantics beyond the schema (that limit selects the top managers ranked by shares), so the baseline of 3 applies.

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 verb+resource: institutional holders from SEC quarterly Form 13F data sets for the company behind one Robinhood Stock Token. It names the accepted key forms (ticker such as NVDA or 0x contract) and the exact payload (top managers by shares, quarter-over-quarter change), which distinguishes it from siblings like insider_trades or fundamentals without opening their schemas.

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 clear usage context and exclusions: options (puts/calls) excluded, amendments applied, funds and foreign issuers not covered, and a ticker without a reviewed CUSIP returns '13F not mapped'. What it lacks is explicit routing to an alternative sibling (e.g. insider_trades for Form 4, fundamentals for financials), so the agent must infer the boundary.

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