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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so safety and idempotency are covered structurally. The description adds genuinely useful provenance (Yahoo Finance via yfinance, no API key required) but says nothing about latency, caching, or coverage limits, which matters for an external-source fetch.

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 purpose sentence followed by a tight bulleted usage block and a one-line enum listing plus source note. Every element is relevant to invocation; the only waste is restating holder_type values already in the schema.

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?

An output schema exists, so return-value explanation is not required, and annotations carry the safety profile. However, the schema exposes a set of fin-internal filtering parameters (wholesaler_ids role semantics, source_resource_id cache reuse) that the description never acknowledges, leaving the agent to infer how they interact with a simple stock-ownership lookup.

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?

The description repeats the holder_type enum ('institutional', 'mutualfund', 'insider', 'all') that the schema already defines, and mentions no other parameter. Coverage for the many unrelated-looking fields (wholesaler_ids, exclude_fillers, source_resource_id, mcp_prompt_id, question_asked) is zero in the description, leaving complex behavior undocumented in prose.

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 ('Fetch ownership data for a stock') and enumerates the three data categories returned: institutional holders, mutual fund holders, and insider transactions. It does not explicitly distinguish itself from the closely related sibling Get13FHoldings, so it stops 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?

The 'Use this tool when' block gives three concrete triggering scenarios (institutional/fund ownership, insider buying/selling, ownership concentration). That is clear usage context, but no when-not guidance or explicit routing away from siblings like Get13FHoldings or SearchEdgar13F.

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