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

With no annotations, the description carries the full disclosure burden, and it does state the concrete content returned: endpoints, parameters, rate limits, CSV downloads, and attribution terms. This tells an agent what to expect beyond a vague 'reference.' It doesn't mention return format (text vs structured) or whether it is read-only, so it stops short of full transparency.

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?

Two tight sentences: the first front-loads the content inventory, the second gives the usage condition. No filler, no repetition of the name or title, and the most decision-relevant information (when to call it) is easy to locate.

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?

For a parameterless documentation tool with no output schema, the description is sufficient: it says what content is available and when to reach for it. Slightly more detail on response shape would make it fully self-contained, but nothing essential is missing.

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 tool takes zero parameters, so there is no parameter semantics to document and the baseline is 4. No schema detail is required or missing.

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 names a specific resource — the underlying free API — and enumerates what it covers: endpoints, parameters, rate limits, CSV downloads, and attribution terms. This clearly distinguishes it from the sibling data-query tools, which return market data rather than API documentation. It lacks a crisp verb+resource formulation but the purpose is unambiguous.

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 gives explicit routing guidance: 'Use when a tool here does not cover the exact query,' which positions it as the fallback for the 21 sibling data tools. The condition is precise and actionable, though no counter-examples or exclusions (e.g. don't use this when a data tool already fits) are spelled out.

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

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

With no annotations, the description carries the full burden. It usefully discloses provenance (company-filed XBRL, not market data) and timing semantics ('as of the filing period'), signaling reporting lag. It says nothing about universe size, refresh cadence, or whether it is a snapshot vs historical series.

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?

A single, front-loaded sentence with no filler, and the provenance qualifier is the most useful piece of information placed inline. It is terse, though for a whole-dataset tool a little more specificity would not be waste.

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?

No annotations, no output schema, and no parameters means the description is the only contract, and it stops at naming measures. It does not indicate the shape of the result (per-company rows? single aggregate?), coverage, or time span, which an agent needs to use it confidently.

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?

Zero parameters, so the baseline is 4. The description compensates somewhat by enumerating the returned measures (coins, fair value, cost basis), which is the closest thing to a field contract in the absence of an output 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 the specific resource (Bitcoin holdings of public companies) and even the provenance (their own XBRL filings), plus the fields exposed (coins, fair value, cost basis). It is distinguishable from crypto_market and company_financials, though it never names a sibling to sharpen the boundary.

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?

There is no when-to-use guidance, no prerequisites, and no alternative named. The only contextual hint is 'as of the filing period', which implies the data is periodic rather than real-time, but that is inference, not guidance.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It does disclose a notable derivation: fourth quarter is derived from the annual report. However, it does not state whether the data is read-only (though it appears to be a retrieval tool), whether it requires authentication, whether it is rate-limited, or how fresh the data is. For a data-retrieval tool with no annotations, this leaves significant gaps.

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?

The description is a single, dense sentence that front-loads the key metrics. It is efficient and avoids fluff, though the enumeration is lengthy and could be slightly more scannable with formatting. Every clause adds value, so it earns a 4.

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 must convey return values, which it does by listing the financial metrics. However, it omits important contextual details for an agent, such as whether the data is point-in-time, how to handle missing quarters, or if there are prerequisites like a valid SEC filing. For a tool with no annotations and no output schema, it is adequate but incomplete.

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 the single parameter (symbol) is well documented in the schema itself, including format examples and class share handling. The description adds no parameter-level information, which is acceptable given the complete schema. Baseline of 3 is appropriate.

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 names a specific resource (company XBRL financials) and enumerates exactly which metrics it returns: quarterly revenue, net income, diluted EPS, annual figures, operating cash flow, capex, buybacks, dividends, and balance sheet instants. It also states the source (the company's own XBRL filings), which distinguishes it from siblings like fund_portfolio or short_interest.

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?

There is no explicit guidance on when to use this tool versus alternatives. The description does not mention any sibling tool, nor does it state conditions or exclusions. It implies usage by describing the data returned, but an agent must infer the appropriate context.

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

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

No annotations are provided, so the description carries the full behavioral burden. It says nothing about return volume, ordering, rate limits, or what happens when no ticker is supplied (all-company sweep vs. empty), leaving key behavioral traits undisclosed for a tool whose default query type can materially change result size.

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?

One well-formed sentence with the resource front-loaded and the two usage modes stated compactly. No filler, though the parenthetical item list is slightly long relative to the rest.

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?

For a 3-parameter, no-output-schema tool, the description covers the resource and the ticker/no-ticker split but omits the days parameter's meaning and default behavior, and gives no indication of result shape or volume. Adequate but with a clear gap around the unspecified default query scope.

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 67% – ticker and item are documented in the schema, days is not. The description usefully expands the meaning of item codes (2.02 earnings, 5.02 officer changes, 1.01 agreements), adding value beyond the schema's bare "e.g. 2.02", but the days window remains undefined in both places.

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 (8-K current reports) and what it carries (item numbers), and clarifies the two access modes: by ticker or latest across companies. It does not explicitly differentiate itself from siblings, though none of the listed siblings cover SEC filings, so confusion risk is low.

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?

"For a ticker or the latest across companies" implies the two usage modes and hints that the ticker parameter is optional, but there is no explicit when-to-use guidance, no mention of how the days window interacts with these modes, and no named alternative.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses cadence (weekly) and the shape of the content (open interest, long/short by trader category), but says nothing about publication lag relative to the reporting date, pagination, default result size, or error behavior for an unrecognized market slug.

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?

A single dense sentence with the core noun phrase front-loaded and examples tucked into a parenthetical rather than bloating the prose. Slightly heavy on inline enumeration, but every clause carries information an agent needs.

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?

For a low-complexity read tool with no output schema or annotations, the description covers mode selection and the returned fields, which is the essential core. It still omits default limit/result size and any note on report recency, leaving small but real operating gaps for an agent building the call.

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 50%: market carries a description, limit does not. The description adds value on market by listing several example slugs beyond the schema's lone 'gold' example, but it never mentions limit at all, so the undocumented half of the parameter set stays unexplained (no default, no note that the cap is 500).

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: weekly CFTC Commitments of Traders positioning data. It immediately distinguishes the two retrieval modes (latest report across all markets vs a single market's history) and names the payload (open interest, long/short by trader category). None of the siblings cover CFTC positioning, so an agent can route here without ambiguity.

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 description makes the mode-selection rule clear: omit the market for the latest cross-market report, supply a slug for one market's history. It gives concrete slug examples (gold, crude-oil, sp500, bitcoin, euro-fx, 10-year-note) that steer argument choice. It does not name exclusions or point to sibling tools for related datasets, so it stops short of full when/when-not guidance.

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

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

No annotations are provided, so the description carries the full disclosure burden. It reveals nothing about auth requirements, rate limits, response format, pagination, or freshness/latency of the market data, which matters for live crypto metrics.

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?

A single dense sentence with no filler; each clause maps to a dataset branch. The enumeration ordering matches the schema enum order, but the sentence is not front-loaded with a clear verb+resource opener.

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?

Covers what each dataset is, but for a tool with no annotations and no output schema, it leaves the agent without return-shape expectations or scoping rules (e.g., whether slug is required/allowed for liquidations). Adequate but with clear gaps.

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 only 50% and the critical 'dataset' enum has no schema-level description at all. The description compensates by mapping each dataset value to its subject, and clarifies slug semantics per dataset (symbol slug for open-interest, BTC/ETH for options, coin for whales), which materially reduces ambiguity.

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 enumerates the four concrete capabilities (open interest history, liquidations, Deribit options metrics, Hyperliquid whale positions), which is far more specific than the title and distinguishes it from siblings like funding_rates or bitcoin_treasuries. It is a bare list without an explicit verb framing ('returns'/'fetches'), keeping it 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?

Naming each dataset against its subject matter implicitly tells the agent which dataset value to pick for a given question, which is real guidance for a multi-dataset tool. However, there is no explicit when-to-use/when-not statement, no mention of alternatives among siblings, and no prerequisite information.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals that actuals appear 'once published' (implying some events may lack actuals), but says nothing about data freshness, update frequency, pagination, timezone handling, or rate limits. For a time-sensitive calendar tool with zero annotation coverage, this is a significant gap.

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?

A single, well-structured sentence with zero waste. The parenthetical examples are front-loaded and immediately informative. Nothing extraneous.

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?

For a 3-parameter tool with no annotations, no output schema, and 0% schema description coverage, the description is far too thin. It omits parameter formats, date semantics, importance filtering behavior, and whether historical vs. upcoming events are returned. An agent has insufficient information to invoke this correctly without trial and error.

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 0%, so the description must compensate but does not. It doesn't explain that 'from' and 'to' are date bounds (format, maxLength 10 suggests YYYY-MM-DD but this is unstated), nor what 'importance' filters. Three undocumented parameters with no textual clarification leave the agent guessing about parameter semantics.

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 (US economic calendar) with concrete examples of the releases it covers (CPI, NFP, FOMC, GDP). This clearly distinguishes it from siblings like corporate_events, macro_series, or policy_rates, though it doesn't explicitly name an alternative tool. The purpose is clear but not maximally differentiated.

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?

No guidance on when to use this tool versus alternatives like macro_series or policy_rates. The description doesn't state whether it's for historical data, forward-looking schedules, or both. An agent must infer usage from the name alone.

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

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

With no annotations, the description carries the full burden. It implies a read-only data lookup but never states read-only behavior, pagination, rate limits, coverage window, or freshness of the settlement data. It does disclose the dual output shape, which is useful, but that is mostly return-content description rather than behavioral traits.

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?

A single dense sentence that front-loads the resource and covers both output modes with no filler. It is slightly compressed ('fails-to-deliver quantity and price') but nothing is wasted.

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?

No output schema exists, so the description must convey return content; it does identify the two return shapes (time series by settlement date, or largest fails by value). However, it omits when each mode applies and freshness/coverage, leaving an agent unable to call it confidently in all cases.

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% and the single symbol parameter is fully documented in the schema with format examples (GME, BRK-B). The description only echoes 'for a symbol' and adds no syntax or semantics beyond the schema, so the baseline 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?

The description names a specific resource (SEC fails-to-deliver quantity and price) and the keying dimension (settlement date, or the latest settlement's largest fails by value). An agent can tell this is a data-retrieval tool distinct from siblings like short_interest or short_volume, though it doesn't explicitly distinguish itself from those near-neighbors.

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?

No when-to-use guidance is given, and crucially the two output modes ('by settlement date for a symbol' vs 'the latest settlement's largest fails by value') are not tied to a selection condition, so the agent cannot tell what triggers each mode. No alternatives are named among the many sibling market-data tools.

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

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

No annotations exist, so the description must carry the whole load. It does disclose the default behavior (unfiltered results are ranked by size) and the aggregation semantics of by=ticker, which is real behavioral information, but it says nothing about result limits, the default time window, or what the returned records contain.

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?

A single compact sentence that front-loads what the tool returns before the optional modes. No padding, though the parenthetical '(by=ticker)' makes one clause slightly dense.

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?

For a 4-parameter tool with no output schema and no annotations, an agent still cannot tell what 'listed' does, what the default lookback is, or what shape the results take. The main query modes are covered, so it is adequate but not complete.

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 only 25% (only ticker is documented in the schema). The description usefully explains by=ticker (sum by listed parent company) and ticker (filter to one ticker), but leaves 'days' and especially the boolean 'listed' completely unexplained in both description and 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 verb+resource (contract actions from USAspending) and even names the ranking ('largest') and data source. The domain is unique among the financial-market siblings, so differentiation is implicit rather than stated, which keeps it just 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 description sketches two modes ('summed by listed parent company' via by=ticker, or 'filtered to one ticker') but never says when to choose one over the other or what the bare no-argument call returns. Usage is implied by the mode clauses, not articulated.

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

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

No annotations are provided, so the description carries the full burden. It mentions 'oldest first' and 'weekly', which gives some output ordering and frequency context, but it doesn't disclose data source behavior, caching, error handling for invalid series, rate limits, or the distinction in output shape between the net-liquidity mode and single-series mode. For a two-mode financial data tool with zero annotations, this is under-specified.

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?

The description is a single, information-dense sentence that front-loads the primary resource and its definition, then appends the alternative mode. It's efficient, though the long parenthetical and series list make it slightly less front-loaded and scannable than ideal.

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 annotations, no output schema, and 50% schema description coverage, the description needs to be more complete. It doesn't explain the return shape for either mode, how the series list maps to the net-liquidity components, or edge cases like invalid series IDs or the interaction between limit and series. An agent could call it but would be uncertain about expected output.

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 50%: the 'limit' parameter is documented in the schema (default 52, up to 2000), but the 'series' parameter has no schema description. The tool description lists the FRED series IDs (WALCL, WRESBAL, RRPONTSYD, WTREGEN, SOFR, EFFR, IORB, WSHOSHO), which partially compensates by indicating valid values, but it doesn't explain the mutual exclusivity or behavioral difference when series is provided versus omitted. The description adds some value but leaves the core parameter semantics unclear.

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 names a specific data resource (weekly US net liquidity) and defines its composition (Fed balance sheet minus TGA minus reverse repo), plus an alternate mode for individual FRED series. This distinguishes it from macro siblings like macro_series or economic_calendar, though the two-mode structure (net liquidity series vs. single series) adds some ambiguity about which mode is primary.

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?

Usage is implied by the description: use it to get weekly net liquidity data, or specify a FRED series ID for a component series. However, there's no explicit guidance on when to prefer this over sibling tools like macro_series, or on how the series parameter interaction with the net-liquidity mode works. The agent has to infer the selection logic.

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

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

With no annotations, the description carries the full burden. It does disclose two meaningful behavioral traits: the universe is limited to 'tracked' 13F managers, and data reflects the 'latest quarterly filing', implying lag and quarterly cadence. It says nothing about read-only safety, empty results for untracked tickers, or error behavior.

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?

A single sentence that front-loads the core question and then appends the returned attributes compactly. Dense but no wasted clauses; the parenthetical manager examples add credibility without bloat.

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?

No output schema exists, so the description must convey the return shape, and it does (shares, value, share of portfolio, change). For a single-ticker lookup it is nearly complete; it omits how many managers are returned and what happens for untracked tickers.

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?

Only one parameter exists and the schema documents it at 100% coverage (US ticker, class-share format like BRK-B). The description adds no syntax or format detail beyond the schema, so the baseline 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 resource (13F institutional holders) and the exact question answered ('which tracked managers held a ticker at their latest quarterly filing'), and even names the return fields. It does not explicitly distinguish itself from the closely related siblings large_holders and fund_portfolio (the inverse lookup), so it falls 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 usage is only implied — an agent can infer this answers 'who owns this stock' — but there is no explicit when-to-use, no exclusions, and no routing to alternatives such as large_holders or fund_portfolio, which are the obvious competing choices for holder data.

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

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

With no annotations, the description carries the full burden. It does add real context by naming the three exchanges covered and by indicating the data is 'current' versus historical. It says nothing about update cadence, rate limits, or what happens for an untracked slug, so behavioral disclosure is only partial.

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?

A single well-formed sentence with zero filler, front-loading the primary resource (current funding rates) before the secondary history mode. The parenthetical example is embedded efficiently rather than given its own sentence.

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?

For a one-optional-parameter read tool with no output schema, the description covers the resource, the sources, and both query modes, which is enough for correct invocation. It leaves the history window (how far back) unspecified, which is the only notable gap.

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 0% and the single 'slug' parameter is undocumented in the schema, so the description must compensate — and it largely does, giving the exact format with examples (btc, eth, sol) and clarifying that supplying it switches to single-symbol history. The one gap is that it never states the parameter is optional, though the dual-mode wording makes that inferable.

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 names a specific resource (perpetual funding rates) and enumerates the data sources (Binance, Bybit, OKX), so the agent knows exactly what data it gets. It also distinguishes two modes — cross-symbol current rates vs. single-symbol history. It does not explicitly contrast itself with the sibling crypto_market, which is the only thing keeping it from 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 'current ... or one symbol's history by slug' construction implies how to choose between the two modes, which is useful routing guidance. However, there is no explicit statement of when to reach for this tool over crypto_market or any other sibling, and no exclusions or prerequisites are given.

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

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

With no annotations, the description carries the full burden, and it partially delivers: it discloses that data is 'latest' 13F (quarterly filing cadence, snapshot in time) and describes the payload contents (value, shares, share of portfolio). It omits any statement of auth requirements, rate limits, or whether non-tracked managers return empty/error responses.

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?

Two tight sentences with no filler; the resource scope is front-loaded before the example slugs and the return-field note. The examples list is slightly redundant with the schema, keeping it just short of ideal.

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?

For a single-parameter lookup with no output schema, the description supplies both the identifier convention and the shape of the returned positions, which is what an agent needs to call and interpret it. Missing usage routing against siblings is the main gap.

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 the schema already documents the slug parameter with an example. The description reinforces the slug semantics with additional example slugs, but adds no format rules or constraints beyond what the schema provides, 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?

The description states a specific resource and scope: the latest 13F portfolio of one tracked manager, identified by slug. It provides concrete example slugs (berkshire-hathaway, bridgewater, citadel-advisors, renaissance-technologies), making the resource unambiguous. It is clear but does not explicitly name or differentiate itself from nearby siblings like fund_holders or large_holders.

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 description implies the tool is for retrieving a specific tracked manager's holdings, but it never states when to use this versus fund_holders, large_holders, or insider_trades. No exclusions, prerequisites, or alternative-selection guidance are given.

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

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

With no annotations, the description must carry the behavioral load. It usefully discloses the return content and the scope difference between ticker-history and cross-company views, but says nothing about limits, freshness, rate limits, or what happens with no parameters supplied.

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?

Two sentences, front-loaded with the resource and payload, with no filler. The field enumeration is slightly list-like but still earns its place by telling the agent what comes back.

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?

For a 3-parameter read tool with no output schema, the description adequately covers the returned fields and the two query modes. It is incomplete on the window parameter and on behavioral constraints, and with no annotations the safety/limits picture is thin.

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 67%; the description echoes the P/S meaning (also in the schema) and hints that 'history for a ticker' is a mode, but the window enum (7d/30d/90d) is neither described in the schema nor explained here, leaving a real gap.

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 names a specific resource ('Insider transactions from SEC Form 4') and enumerates the returned fields, so an agent immediately knows what it fetches. It does not, however, distinguish itself from the close sibling planned_insider_sales, which is a distinct insider-activity tool.

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 implies two usage modes ('History for a ticker or the latest trades across companies') and explains the P/S filter, giving the agent operational context. It offers no explicit when-to-use/when-not guidance and never references an alternative tool for related insider data.

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

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

With no annotations, the description carries the full behavioral burden. It identifies EDGAR as the source and the filing types covered, but does not disclose read-only status, rate limits, pagination, authentication needs, or how omitted parameters behave.

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?

The description is a single dense sentence that front-loads the resource and scope without unnecessary words. Every phrase contributes to identifying the tool's data.

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 and no annotations, so the description must do more. It states the data scope but omits input defaults, return structure, and usage context, leaving meaningful gaps for correct invocation.

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 67%. The description lists form examples that partly overlap the form parameter, but it does not explain the days parameter, the new filter, or defaults when parameters are omitted. It adds little beyond the schema for parameter meaning.

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 names specific EDGAR filing types (S-1, F-1, 424B4, EFFECT, RW) and the filer listing status, so the resource is clear. It does not explicitly differentiate itself from siblings or state a retrieval verb, but the content is specific enough to identify the tool.

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?

There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites, exclusions, or related tools such as corporate_events. The description only states what data is included.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not state whether the tool requires a symbol, what happens if none is given, pagination/rate limits, or any permission requirements. The only behavioral hint is 'active' vs 'passive' for 13D vs 13G, which is minimal.

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?

The description is a single efficient sentence fragment that front-loads the key concept (5%+ holders, 13D/13G) and then lists output fields. It is compact and wastes little space, though it is somewhat dense and could be clearer.

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?

Given 4 parameters (0 required), 25% schema description coverage, and no output schema or annotations, the description should do much more to explain parameter semantics and behavior. It only covers the returned fields and hints at usage, leaving critical gaps for correct invocation.

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 only 25% (only the symbol parameter is described). The description does not explain the 'days', 'form', or 'sort' parameters at all, so an agent has no guidance on how they affect results. This is a significant gap that the description fails to compensate for.

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 states a specific verb+resource: it returns 5%+ holders from Schedule 13D/13G cover pages, and lists the returned fields (holder, shares, percent of class, filing date). This clearly distinguishes it from sibling fund_holders (fund ownership) and insider_trades. It is clear but does not explicitly name or differentiate against those siblings, so a 4.

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 phrase 'For a symbol or the latest filings' implies the two usage modes (filter by symbol vs. get latest filings), which is useful context. However, there is no explicit when-to-use, when-not-to-use, or named alternative, so it is only implied guidance.

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

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

No annotations are provided, so the description carries the full burden. It states this is a read/query tool only implicitly and does not disclose pagination, return shape, rate limits, or how many series can be requested at once. For a multi-series data tool with zero annotation coverage, this is a significant transparency gap.

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?

Two short sentences, front-loaded with what data is returned and followed by filtering guidance. No wasted text, though it is quite minimal given the tool's multi-series nature.

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 annotations, no output schema, and only 33% schema coverage, the description should do more to explain valid series values, date range behavior, and return structure. As written, an agent lacks enough detail to invoke the tool correctly beyond the most basic case.

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 only 33% – only the 'from' parameter has a description (YYYY-MM-DD). The description adds that 'to'/'from' define a date range and 'series' is a series name, which helps interpret the two undocumented parameters, but it does not clarify accepted series identifiers or date format for 'to'. This partially compensates for the low coverage but leaves gaps.

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: 'US Treasury yield curve points, curve spreads and stablecoin supply as daily series.' An agent can tell this retrieves macro daily series data, distinct from siblings like fed_liquidity or policy_rates. It is clear, though it does not explicitly name how it differs from those nearest 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?

The description says 'Filter by series name and date range,' which implies usage context, but gives no explicit when-to-use or when-not-to-use guidance relative to alternatives like fed_liquidity, policy_rates, or economic_calendar. Usage is implied rather than stated.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the nature of Form 144 filings, but does not state whether the operation is read-only, what permissions are needed, whether data is delayed, or any other behavioral trait beyond the basic resource definition.

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?

The description is a single, front-loaded sentence with no filler. It packs the resource type, subject, key fields, and timing context efficiently.

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?

Given no annotations, no output schema, and only 50% schema description coverage, the description is incomplete. It does not explain how to use the input parameters, what the call returns structurally, or any behavioral constraints needed to invoke the tool 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?

The description adds no meaning for the two input parameters. The symbol parameter is already documented in the schema, and the days parameter has no schema description and is not addressed by the description at all. The parenthetical list refers to notice contents, not input controls.

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 clearly states the resource: SEC Form 144 notices of planned insider sales by affiliates. It specifies the subject matter and distinguishes the data from completed insider trades, though it does not explicitly name the sibling tool insider_trades as an alternative.

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?

There is no explicit guidance on when to use this tool versus alternatives, nor are any prerequisites or exclusions stated. The phrase 'filed before the trade' implies timing but does not tell an agent when to choose this tool over insider_trades or other sibling tools.

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

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

No annotations are provided, so the description carries the full burden; it does clarify the dual read mode (bulk table vs single-economy history) and the accepted code format. However, it says nothing about update cadence, data freshness, or rate limits, leaving behavioral gaps for a data-fetch tool.

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?

A single front-loaded sentence that leads with the resource and scope, then states the two operating modes using a parenthetical example. No filler.

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 and no annotations, the description still conveys the scope, the two response modes, and the parameter's effect. It stops short of describing returned fields, units, or refresh frequency, which leaves modest gaps for a data endpoint.

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 0% for a single maxLength-4 'country' string, yet the description compensates well by giving sample codes (us, eu, jp, gb) and explaining that the parameter switches the response from the full current table to one country's time series.

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 names a specific resource (central bank policy rates) and quantifies its scope (49 economies), plus the two shapes the result can take. It is clearly distinguishable from macro_series or funding_rates at a glance, though it never explicitly contrasts itself with those 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?

Usage is implied rather than stated: supplying a country code yields that economy's history, omitting it yields the current table of all 49. There is no guidance on when to prefer this over nearby siblings like funding_rates or macro_series, so an agent must infer the boundary itself.

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

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

No annotations and no output schema, so the description carries the full behavioral burden. It does disclose the record contents (issuer, amount sold, amount offered, investor counts, pooled-fund flag), which is useful. It says nothing about result caps, pagination, default window length, or ordering guarantees, leaving meaningful behavioral gaps for a bulk data endpoint.

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?

Two tight sentences: the first front-loads what the data contains, the second front-loads the three access patterns. No filler, no restatement of the name or title, and the most decision-relevant information comes first.

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 and no annotations, the description is the only guidance available. It covers data content and query modes but omits defaults (e.g. default days), result limits, and what happens when no cik filter is supplied. Adequate to attempt a call, but not complete for a 4-parameter, 25%-coverage endpoint.

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 only 25% (only 'funds' is documented), so the description must compensate, and it largely does: 'one issuer by CIK' maps to cik, 'largest raises in a window' maps to days and the sort behavior, and 'whether it is a pooled fund' maps to funds. It does not clarify default values or the fact that sort only accepts 'recent', which is a minor residual gap.

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 data source and resource (SEC Form D exempt-offering notices) plus the fields returned, which is well beyond a tautology. It lists three concrete query modes (largest raises in a window, one issuer by CIK, most recent filings) that distinguish it from siblings like insider_trades or large_holders. It stops short of explicitly naming a sibling it should be chosen over, so 4 rather than 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 three listed modes implicitly map to the parameters (window → days, issuer → cik, recent → sort), giving an agent a rough sense of when each input applies. However, there is no explicit when-to-use / when-not-to-use statement and no named alternative among the many sibling SEC-data tools. Usage is inferable but not spelled out.

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

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

No annotations are provided, so the description carries the full burden and does well: it discloses the FINRA settlement cadence (twice a month), ordering (newest first), and the default behavior when symbol is omitted. It does not mention rate limits, auth, or result-size characteristics, so it falls short of exhaustive.

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?

Two sentences: the first front-loads the resource and its fields, the second covers the alternate mode. Every clause carries information; nothing is filler.

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 compensates by listing the return fields and ordering. Combined with full schema coverage on the two optional parameters, an agent has everything needed to call it correctly in either mode.

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% (baseline 3), and the description adds real meaning beyond it by explaining what omitting the optional symbol produces — a ranked list rather than per-symbol rows. Limit semantics (default 24) remain schema-only, so it stays below 5.

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?

Names the resource (FINRA short interest) and enumerates the returned metrics (shares short, average daily volume, days to cover, change), so an agent knows exactly what data arrives. It does not explicitly route against the adjacent FINRA datasets (short_volume, fails_to_deliver), which is the only gap keeping it from 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?

Gives clear context for both invocation modes: with a symbol for one stock, without a symbol for the latest settlement's highest days-to-cover names. No alternatives or when-not-to-use conditions are named, but the two modes are unambiguous.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the data source, the ordering convention (oldest first), the two result modes, and a derived metric (short share of volume), which is real added context. It says nothing about units, result limits, rate limits, or freshness/update cadence of Reg SHO files.

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?

Two tight sentences, front-loaded with what the data is and its source, then the two usage modes. No filler or repetition.

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 should carry return-value detail. It names the fields conceptually (short volume, total volume, short share) but omits units, the size of the 'largest volumes' list in the no-symbol mode, and how many days the latest-day mode covers. Adequate but with visible gaps for a tool whose return shape is otherwise undocumented.

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 both parameters are already documented (days default 60, max 400; symbol format incl. class shares). The description only indirectly reinforces days as a history window and symbol as the trigger for history mode; it adds no syntax or format detail beyond the schema. Baseline 3.

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 the specific resource (daily short sale volume, total volume, short share of volume) and its source (FINRA Reg SHO files), which sets it apart from siblings like short_interest and fails_to_deliver. The two output modes are named. It stops short of explicitly contrasting itself with those siblings, so it is clear but not fully differentiated.

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 two modes are stated: symbol given yields history (oldest first), no symbol yields the latest day's largest short volumes. That implicitly tells the agent how to pick behavior via the optional symbol parameter. No explicit when-not or named alternative tool is offered.

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