Market-Wide 13F Activity

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

Beyond readOnlyHint=true, the description discloses substantive behavior: Δ Value uses report-date closing prices, may fall back to filer values, can be zero, and includes price movement on held shares (so Δ Shares should be used to read position changes). It also states the tool refuses comparisons crossing the first complete 13F report quarter boundary. Missing is any note on result volume or ordering stability, but the semantic caveats are well beyond what annotations provide.

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 bucket list are front-loaded, and every sentence carries signal (ranking rules, Δ Value caveats, corpus boundary). It is dense and readable, though the single long paragraph and the trailing rhetorical question add length without adding much beyond the earlier framing.

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 burden of describing returns, and it does so by explaining what each bucket ranks and the Δ Value/Δ Shares distinction. It stops short of describing the per-stock fields or ordering guarantees, but an agent has enough to call it correctly and interpret the leaderboard.

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 goes further by defining each bucket's ranking rule (top-buys ranked by Δ value desc, top-sells by Δ value asc, new-positions by count of initiating filers, sold-out-positions by count of exiting filers) — information the terse schema string omits. That materially improves correct bucket selection.

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 (get) and resource (market-wide 13F leaderboards for a given quarter) and immediately enumerates the four buckets, which clearly separates it from institution-scoped siblings like GetInstitutionQuarterlyActivity or GetTopInstitutionalBuyersSellers. An agent can tell what it returns 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?

The closing line 'Use this to answer what's the consensus 13F move this quarter?' gives an explicit usage context and the market-wide framing implies when to prefer it over institution-scoped tools. However, it never names an alternative tool or states an exclusion condition, so routing is inferred rather than directed.

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