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

With only readOnlyHint provided, the description carries the rest and does so well: it discloses the return shape (one row per ticker, latest-restated value), the handling of tickers with no data (listed separately), and a critical caveat that fiscal year/period follow each company's own calendar so rows may span different calendar months. This is substantial behavioral context beyond the annotations.

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?

Three sentences, front-loaded with the core purpose and then the return semantics and the fiscal-calendar caution. Each sentence earns its place, though the NVDA example adds some length beyond the minimum needed.

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 correctly picks up the burden of explaining return values, including row structure and missing-data behavior, and flags the fiscal-calendar trap. It omits pagination/result-size behavior, but for a bounded max-25 comparison this is a minor 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%, so parameter documentation is already handled (baseline 3). The description adds interpretation the schema does not: it clarifies that fiscalYear/fiscalPeriod resolve against each company's own fiscal calendar and points the agent to the Period End column, which meaningfully aids correct use of those two parameters.

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 and resource — 'compare one financial concept across several companies for the same fiscal period' — and labels it as peer comparison. This clearly distinguishes it from the sibling GetFinancialFact (single-company lookup) without needing to open either 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?

It establishes clear context for when to reach for this tool (peer comparison of a single concept across multiple tickers for one period). However, it never explicitly names the single-company alternative or states exclusions, leaving the agent to infer the boundary from the sibling 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?

Annotations provide readOnlyHint=true, but the description adds substantial behavioral context: it lists the exact overlap metrics returned, notes that prices normally use report-date closing values but may fall back to filer values and can be zero when unavailable. This data-quality caveat is valuable beyond the annotation, though it doesn't cover auth or rate limits.

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?

Four efficiently front-loaded sentences: purpose, return values, data caveat, and alternatives. Each sentence adds useful information, though the data-quality sentence could be slightly tighter without losing meaning.

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 comparison tool with no output schema, the description adequately explains return values, data caveats, and alternative tools. It does not mention the maxResults limit or pagination behavior, but the schema covers maxResults, and no output schema exists to require additional explanation.

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%, so the schema already documents all four parameters thoroughly. The description adds the name-resolution tip and clarifies the 'common report date' concept, which gives some extra meaning, but the baseline of 3 is appropriate since the schema carries the primary documentation burden.

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 (Compare), resource (institutions' 13F portfolios), and scope (latest common report date). It also names the return contents and differentiates from sibling tools like GetFundProfile and SearchInstitutions. An agent can immediately tell what this tool does.

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?

Explicitly names alternatives for specific cases: 'Resolve filer names with SearchInstitutions' and 'For mutual-fund or ETF NPORT portfolios, use GetFundProfile.' These are clear when-to-use and when-not-to-use directives that prevent mis-invocation.

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 readOnlyHint=true already covering the safety profile, the description adds real value beyond the annotation: it discloses the unit denomination (USD or the listing's quote unit) and, notably, the warm-up behavior so results don't depend on the range's left edge. This is meaningful context an agent could not get from annotations alone, though it doesn't cover return shape or rate limits.

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?

Four sentences, front-loaded with the definition of ATR, then formula, interpretation, units, and a subtle warm-up caveat. Every sentence contributes; the parenthetical formula is dense but earns its place for an indicator tool.

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-indicator computation tool with no output schema, the description supplies computation method, units, and warm-up semantics – enough for an agent to call and interpret it. Return-value format is not described, but a technical-indicator series needs little explanation.

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%, so all five parameters are already documented in the schema; the baseline is 3. The warm-up sentence adds interpretive meaning relevant to startDate, but the description otherwise adds little parameter detail beyond what the schema already provides.

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 indicator (ATR), defines it precisely as Wilder's volatility measure, and states what it represents for a stock. An agent can clearly distinguish this from sibling technical indicators like GetBollingerBands or GetStochasticOscillator. It stops short of an explicit sibling comparison, so a 4 rather than 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?

It gives interpretive context ('higher ATR means wider daily moves') and names use cases ('position sizing and stop placement'), which implies when the tool is relevant. However, it provides no explicit when-to-use/when-not guidance or routing against the numerous sibling indicators, leaving selection to inference.

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?

Annotations already declare readOnlyHint=true, so safety is covered. The description additionally discloses that the moving-average window is warmed up on price history before startDate, which prevents an important misinterpretation of values near the left edge of the requested range.

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?

Four sentences, each contributing distinct information: definition, interpretation, extra columns, and warm-up behavior. It is front-loaded and free of redundant 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?

For an indicator tool with no output schema, the description explains the returned conceptual columns (%B, bandwidth) and the warm-up behavior. It is nearly complete, though it could mention tool-selection context for a fully complete definition.

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%, so all six parameters are already documented in the schema. The description adds context about the warm-up behavior affecting period/startDate, but does not add syntax or format details beyond the schema baseline.

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 the specific indicator and defines its components (middle band, upper/lower bands, %B, bandwidth). This is concrete enough for an agent to distinguish it from sibling indicator tools such as GetStochasticOscillator or GetAverageTrueRange.

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 explains what the indicator means (overbought/oversold cue when price touches a band), but gives no guidance on when to choose this tool over alternatives, no exclusions, and no prerequisites for use.

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?

Annotations already establish readOnlyHint=true, so safety is covered. The description adds meaningful data semantics beyond that: values are contract counts, sourced from the legacy futures-only COT report, with positions as of Tuesday and published Friday. This reporting-lag context is valuable for interpreting results, though it says nothing about pagination or rate limits.

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?

Four short sentences, each carrying distinct information (what it returns, what the values mean, source/cadence, and where to get market codes). The core purpose is front-loaded and there is 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?

For a read-only tool with full schema coverage and no output schema, the description supplies the interpretive context (units, report source, publication cadence) an agent needs. The main omission is routing versus GetLatestCftcPositioning, which matters given the near-identical sibling name.

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%, so all four parameters (marketCode, startDate, endDate, maxResults) are already documented, including defaults, formats, and the newest-kept behavior. The description adds nothing parameter-specific, 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 states a specific verb and resource: 'Get Commitments of Traders (COT) positioning data for a specific futures contract', and clarifies the value semantics (contract counts, commercial/non-commercial positions). However, it does not distinguish itself from the sibling GetLatestCftcPositioning, which an agent could easily confuse with this historical-range 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 gives one concrete prerequisite: 'Use SearchCftcMarkets to find available market codes', which is genuinely helpful. But it offers no guidance on when to choose this tool over GetLatestCftcPositioning or what happens when the requested market is unavailable.

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?

The readOnlyHint annotation already establishes that this is a safe read. The description adds genuinely useful behavioral context beyond that: results are newest-first, the default window is one year, and amounts are disclosed ranges rather than exact values. Minor gap: nothing about pagination/offset interplay or response size limits.

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?

Three sentences, all earning their place: scope, then return-shape caveats, then the alternative-tool routing. Front-loaded with the ticker scope so the agent gets the critical selector 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, the description usefully characterizes the returned fields (members, purchase/sale, transaction and filing dates, disclosed amount ranges, Asset instrument type), which the agent would otherwise have to guess. Slightly light on pagination behavior for a tool with an offset parameter, but otherwise 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 description coverage is 100%, so every parameter (offset, ticker, startDate, endDate, maxResults, transactionType) is already documented in the schema itself. The description only re-states the newest-first ordering and the one-year default, adding no syntax or semantic detail beyond the structured fields.

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 (congressional securities transactions) scoped to a ticker, which immediately distinguishes it from the member-centric sibling. The ticker scope is baked into the first clause so an agent can route 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?

Explicitly names the alternative tool and the condition that selects it: 'Use GetMemberTrades for one member's transactions across all tickers.' Combined with the ticker-scoped purpose, the when-to-use decision is fully determined.

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?

Annotations only declare readOnlyHint=true; the description adds substantial behavior beyond that: currency varies by listing (USD for US, trading currency for MIC:TICKER), future ex-dates can appear after declaration, and each listing reports its own payments without inheriting from related listings. These are non-obvious traits an agent needs, though return shape and pagination behavior are not described.

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 is front-loaded in the first sentence, with supporting constraints following in order of relevance. Four sentences is slightly long, and the final listing-independence sentence is verbose, but each point carries real 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 no output schema, the description correctly carries the burden of describing return values (ex-dividend date plus cash amount per share) and their currency basis, and it covers date-filter semantics, ordering, and the future-ex-date caveat. An agent has everything needed to call it 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by clarifying that date filters operate on the ex-dividend date (not payment or declaration date) and restates the currency-per-listing rule that no parameter captures. It does not add further syntax beyond 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?

Opens with a specific verb and resource: 'Get the stored declared cash dividends of an exact stock or ETF listing, newest first.' It clarifies the data domain (declared cash dividends) and scope (a single exact listing), leaving no ambiguity about what is returned.

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?

Implies usage context by stating that date filters apply to the ex-dividend date and that listings must be exact, but it never says when to reach for this tool versus alternatives (e.g., price vs. dividend data). There is no direct sibling for dividends, so this gap is partly structural, but no explicit when/when-not guidance is 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?

Annotations declare readOnlyHint=true, and the description reinforces this by describing a read-only calendar query. It goes beyond by detailing what is not included (FOMC meetings), explaining importance tiers with examples, and noting default time ranges. No contradictions.

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 concise (4 sentences) and well-structured, starting with the core purpose and then adding relevant details. Every sentence adds value: purpose, exclusions, defaults, and usage tips. No fluff.

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?

The description covers key aspects: what the tool returns (publication dates, FRED series, importance tiers), what it excludes, and default behavior. However, it does not explicitly describe the output format (e.g., array of objects). Given no output schema, a hint about structure would improve completeness.

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% with parameter descriptions. The description adds context by explaining defaults (30-day window, max 100 results) and the practical use of minImportance to filter market movers. While not repeating schema, it enriches meaning with usage examples.

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 'Get the economic release calendar' for US macro data, specifying it includes scheduled and recent publication dates, FRED series, and importance tiers. It distinguishes from sibling GetEconomicIndicator and explicitly excludes FOMC meetings, which are handled by another 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?

The description provides explicit when-to-use guidance, including defaults (next 30 days), filtering with minImportance (high for market movers), and a clear alternative: use GetEconomicIndicator to fetch actual data after release. It also warns that FOMC meetings are not included, directing to the Fed's calendar.

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?

readOnlyHint already establishes this as a safe read. The description adds meaningful non-obvious context: the curated ~40-series coverage rather than the full FRED catalog, which prevents an agent from assuming arbitrary series IDs work. It does not address error behavior for unknown series IDs.

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 is front-loaded, followed by scope and the routing hint to SearchEconomicIndicators. The long inline list of nine example indicators is somewhat list-heavy and partly redundant with the schema, but each element is informative.

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 at least states that it returns historical observations, and the schema fully documents inputs. The exact observation shape (date/value) is not spelled out, a minor gap for a data-returning tool.

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% with rich descriptions for all four params (formats, defaults, maxResults ordering). The description's example series IDs largely duplicate the schema's own examples, so it adds little param-level meaning beyond narrowing seriesId to the curated set. 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 verb+resource ('Get time series data for a FRED economic indicator') and clarifies it returns historical observations. It differentiates from SearchEconomicIndicators by name, though it does not explicitly contrast with the nearest sibling GetLatestEconomicIndicators.

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?

Names the alternative (SearchEconomicIndicators) and the condition for using it ('to find available series'), plus a scope constraint that this covers only the curated ~40-series set. No explicit when-not-to-use guidance beyond that, but context is clear.

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?

Annotations supply only readOnlyHint=true, and the description adds substantial beyond-schema behavior: the balance-vs-flow nature of Quantity, the prior-close convention for Price, the covered-window semantics, publication lag, and what absence of a date does or does not mean. This is exactly the interpretive detail an agent needs for a data-quality-sensitive 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?

Purpose and source are front-loaded, followed by field semantics and coverage caveats, with no filler sentences. It is dense and slightly long, but nearly every clause carries interpretive weight rather than restating 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?

With no output schema, the description fully carries the burden: it defines the returned fields, their units and conventions, the valid date window, and the lag behavior. An agent can interpret results correctly without additional context.

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%, so ticker, startDate, endDate, and maxResults are already documented (including the max: 500 bound and the 'most recent N, oldest-to-newest' ordering). The description's detail concerns output fields (Quantity, Price, Value) rather than inputs, so it adds little input-level meaning beyond the schema; 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 verb and resource — 'Get fails-to-deliver (FTD) data for an exact listed stock or exchange-traded fund from the SEC's twice-monthly FTD files' — and pins the source and cadence. This clearly separates it from siblings like GetShortInterest or GetShortVolume.

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 interpretive context: never sum Quantity across dates, dates absent within the window mean no reported fails, earlier dates are only partially covered, and rows trail today by ~two weeks. It does not, however, name alternative tools (e.g., GetShortInterest) or state when to prefer one over the other, so it stops short of explicit routing.

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?

Annotations only declare readOnlyHint=true, so the description carries most of the burden and delivers real context: coverage begins in late 2025, entries are the FDA's own listings, they are not mapped to stock tickers, and each includes a link to its FDA meeting page. It could still say more about result behavior such as pagination or sort beyond 'soonest first', which the schema covers.

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?

Three sentences, front-loaded with the resource and source, then defaults, then limitations. Every sentence carries information an agent needs; 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?

For a simple read-only calendar lookup with a fully described 3-parameter schema and no output schema, the description covers scope, defaults, source, and data limitations (late-2025 coverage, no ticker linkage). The remaining gap is minor: return shape details beyond 'each with a link to its FDA meeting page'.

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%, so the schema already documents all three parameters, their formats, and defaults. The description restates the 90-day default and the date-range override, adding only slight reinforcement beyond the schema's 'defaults to 90 days after the start'.

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 (scheduled FDA advisory-committee meetings), plus the source (FDA.gov advisory-committee calendar). None of the 60+ siblings cover FDA regulatory events, and the description makes the domain unmistakable.

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?

Explicitly states the default window (next 90 days) and the condition for overriding it (pass a date range to look further ahead). It also draws the when-not boundary clearly: a forward-looking calendar, not a historical archive, so an agent knows not to use it for past meetings.

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?

Annotations only declare readOnlyHint, so the description carries the behavioral burden and does so well: it discloses the restated-vs-originally-reported default, the row semantics for flows vs balances, the fiscal-calendar behavior, and a warning emitted when an alias ends materially early (tag change). This is rich context beyond the read-only hint.

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 tool returns and its source, then the restatement and period-row behavior, then routing to siblings. Dense but every sentence earns its place; slightly long, 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?

With no output schema, the description must explain the return shape and it does: one row per fiscal period for flows, one per as-of date for balances, each row carrying actual period start/end, plus the early-alias warning. Nothing an agent needs to invoke or interpret this tool correctly 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for asOriginallyReported (earliest canonical filing vs latest restatement) and clarifies period semantics tied to fiscalPeriod and the fiscal calendar. It stops short of adding syntax detail for form/fromDate/toDate beyond what the schema already states.

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 (get a single financial concept over time for a company), lists concrete concept examples, and names the data source (SEC Company Facts / issuer filings). It explicitly differentiates from siblings by pointing to GetFinancialStatement for full statements and CompareFinancialFact for peer comparison.

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 explicit routing: use GetFinancialStatement for a full statement, CompareFinancialFact for peers, and states the scope boundary that dimensioned disclosures like customer concentration are outside this consolidated-series tool. When and when-not are both covered.

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?

Annotations only declare readOnlyHint, so the description carries the main behavioral burden and adds substantial context: SEC XBRL sourcing, latest-restated value selection for one exact period end, and the discrete-quarter derivation rule marked as Derived. It also discloses scope exclusions, which is valuable for avoiding misuse.

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?

Four dense sentences front-load the core purpose and source, followed by return behavior, derivation logic, and exclusions. Every sentence adds distinct routing or behavioral information with 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?

For a read-only statement tool with no output schema, the description is unusually complete: it explains purpose, data source, return scope, derivation behavior, and explicit alternatives. Combined with the readOnlyHint annotation, nothing material 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?

Schema description coverage is 100%, so the schema already documents ticker, year, period, and statement with formats and defaults. The description adds conceptual context but no new parameter syntax or constraints beyond what the schema provides, so baseline 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?

States a specific verb and resource: get a company's income statement, balance sheet, or cash-flow statement for a fiscal year and period. It also names the data source and explicitly differentiates from siblings like GetRevenueBreakdown and GetFinancialFact, so an agent can select it without opening other 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?

Provides explicit when-to-use and when-not-to-use guidance: company-specific dimensional facts are excluded, and it routes segment/geographic revenue to GetRevenueBreakdown and single-line-item comparisons to GetFinancialFact or CompareFinancialFact. It also clarifies the common Q4 reporting pitfall and directs users to FY for annual figures.

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?

Annotations only declare readOnlyHint=true, and the description adds real behavioral context: results are ordered most-recent-first, a note flags when more exist than were returned, and it cautions that a proposal may never execute and only appears on Form 4/5 when reportable. It does not spell out offset/pagination mechanics explicitly, but the truncation note covers the key risk.

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-loads the purpose and packs returned fields, ordering, and caveats into one dense paragraph with little waste. It is on the longer side, but each clause carries actionable information rather than 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 enumerates the returned fields (seller, relationship, shares, aggregate value, percentage of shares outstanding, sale date, broker, remarks/10b5-1) and covers ordering, truncation, and interpretation caveats. An agent has everything needed to call and interpret it 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?

Schema description coverage is 100%, so the baseline is 3, but the description earns a step up by explaining the purpose of fromDate/toDate (scoping a period to avoid 10b5-1 flooding), which adds decision value beyond the schema's format hints.

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 and resource ('Get recent proposed insider sales ... from SEC Form 144 notices') and effectively differentiates from the Form 4/5 tools by clarifying these are declarations of intent, not completed sales. An agent can distinguish this from GetInsiderTransactions without opening either 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 clear context on when to scope with fromDate/toDate and warns that heavy 10b5-1 filers can flood the recency window with small daily notices. It stops short of naming an alternative sibling tool or stating explicit when-not conditions, so it is clear but not fully routing.

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?

Annotations only declare readOnlyHint=true, so the description carries the real burden — and it delivers. The warning that ongoing offerings are re-noticed through D/A amendments that RESTATE the same offering, with a dedup rule (group by first-sale date and offering amount, keep only the latest notice), is a genuinely valuable behavioral caveat that prevents double-counting capital raised.

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?

It is a fairly dense block, but it is front-loaded (what it returns first, then the critical D/A caveat, then the use context) and nearly every sentence earns its place. The enumeration of returned fields is long but necessary given no output 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?

With no output schema, the description must describe the return payload — and it enumerates issuer, date of first sale, offering amount (dollar figure or 'Indefinite'), amounts sold and remaining, minimum investment, investor count, exemptions, D/A amendment status, and accession number. Nothing material an agent needs to call it correctly 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?

Schema coverage is 100% and all five parameters are well documented in the schema (offset, ticker, toDate, fromDate, maxResults with defaults and clamping rules). The description adds no parameter-level syntax or format detail beyond what the schema already provides, so the baseline 3 is correct.

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 and resource — 'Get recent exempt securities offerings (private placements) for a company from SEC Form D notices' — and lists the exact fields reported. No sibling tool covers Form D offerings, so an agent can immediately tell this is the one tool for private-placement capital raises.

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?

'Use this to track how a company is raising private capital alongside its public filings' gives a clear use context, and the D/A grouping guidance tells the agent how to consume results correctly. It stops short of naming explicit alternatives or when-not-to-use conditions, so it's clear but not fully routing.

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?

Beyond the readOnlyHint annotation, it discloses non-obvious behavior an agent cannot infer: N-CEN is filed at registrant level rather than series level, ingestion runs through tracked issuer feeds, and a resolvable series can still yield zero reports. That is exactly the kind of caveat that prevents a false 'no data means not a fund' conclusion.

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?

Four sentences, front-loaded with purpose, then identifiers, then returned content, then coverage caveats — no filler. The coverage-caveat sentence is long and could be tightened, which keeps it just shy of a 5.

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 return-value burden and does: registrant classification, Investment Company Act file number, reporting period, first/last-filing flags, latest service providers, and filed-name provider history. Combined with the coverage caveats, an agent has everything needed to call this correctly and interpret empty results.

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%, so the `fund` and `maxResults` parameters are fully documented in structured form (including accepted identifier forms and the default/max on maxResults). The description restates the identifier types but adds no syntax, resolution-order, or format detail beyond the schema, 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?

Opens with a specific verb+resource: retrieve operational data for a registered investment company from SEC Form N-CEN annual reports. The scope is narrow enough (N-CEN only, registered funds only) to distinguish it from the broad sibling GetFundProfile without opening either 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?

Points the agent at SearchFunds as the source of valid identifiers and states the exclusion cases explicitly (non-registered/operating companies return no data; untracked multi-series trusts may resolve but have no report). It never names a concrete alternative tool to call instead for those cases, so it stops short of a full 5.

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?

The readOnlyHint annotation covers the safety profile, and the description adds genuinely new behavior: the NPORT-P provenance, what is returned (registrant, series, assets, reported vs stored counts, largest positions), and a data-quality caveat that some multi-series trusts store only tracked-stock positions while counts and asset totals reflect the full filing. It does not discuss pagination behavior for the offset/maxResults window.

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?

Four tight sentences, front-loaded with purpose, then inputs, then return contents, then the sibling handoff. Every sentence carries information; the only mild redundancy is the restatement of accepted identifier forms 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?

For a three-parameter read tool with no output schema, the description covers source, accepted inputs, returned fields, and the stored-vs-reported caveat that an agent would otherwise get wrong. Pagination semantics are left to the schema, which handles them adequately.

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%, so the schema already documents all three parameters, including the accepted fund ID forms and the maxResults cap of 500. The description largely restates those accepted identifier types rather than adding format or syntax detail. 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 verb and resource ('Get a registered fund's profile and largest stored holdings') plus the exact data source (latest SEC Form NPORT-P report). It explicitly names the sibling it is not — GetFundsHoldingStock is the 'inverse lookup' — so an agent can separate the two without opening either 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?

Names the alternative tool and the condition that selects it ('Use GetFundsHoldingStock for the inverse lookup'), and points at SearchFunds as the source of a valid 'verified alias'. It stops short of stating when-not to use this tool, but the routing to the sibling is explicit and actionable.

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 only a readOnlyHint annotation, the description carries real behavioral load: it discloses the 18-month stale-series cutoff so exited positions don't read as current, and warns that per-series report dates differ so cross-row totals mix as-of dates. These are non-obvious caveats an agent could not derive from annotations or schema.

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 scope are front-loaded, and every sentence adds a distinct fact (source, matching key, staleness cutoff, returned fields, date-mixing caveat). It is dense and slightly run-on, but there is little wasted text.

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?

Despite having no output schema, the description enumerates the returned fields (registrant/series, reporting period, position size, USD value, net-asset share, Long/Short payoff) and the ordering. Nothing an agent needs to call or interpret the result 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?

Schema coverage is 100% (baseline 3), but the description adds genuine meaning: ticker resolution is via authoritative CUSIP/ISIN, results are ordered largest-first, and registrantOrSeries is explained as the way to reach positions beyond the largest 500. That last point materially clarifies a parameter the schema only labels generically.

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 (funds holding an exact stock/ETF listing) and pins the data source to SEC Form NPORT-P, which cleanly separates it from 13F-based siblings like GetTopHolders or GetMostHeldStocks. An agent knows exactly what population of holders is returned 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?

Scope is unambiguous (mutual funds/ETFs only, exact CUSIP/ISIN match, stale series excluded), which implicitly routes the agent here vs institutional-holder tools. However, it never explicitly names an alternative tool or a when-not condition, so the routing is inferable 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely valuable context beyond that: the $1M prime-award threshold, the listed-company resolution requirement, and the caveat that totals understate federal revenue and that 'total value' includes unexercised ceiling rather than revenue received. However it says nothing about pagination or response shape. With annotations carrying safety, a 3 fits the lower bar for a non-mutating read 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?

Front-loaded with purpose then caveats, zero filler words, though the middle sentence is a dense list of return fields. Every sentence carries information; slight density cost keeps it off a 5.

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 return-value burden and does so fully: it enumerates each returned field and qualifies the two that are most often misread (total value vs. revenue, outlays when reported). Combined with the explicit coverage limitations, 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%, with defaults, formats, and enum-like values ('amount'/'date') all documented inline. The description adds semantic meaning to the returned value field but little per-parameter detail beyond confirming date filtering uses the award action date. Baseline 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?

States a specific verb and resource (get federal contract awards from USAspending.gov) scoped to a specific public company, and explicitly names the sibling GetTopGovernmentContractors it is not. An agent can pick between the two without opening a 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 the use case ('gauging a company's reliance on federal spending') and an explicit alternative with condition ('use GetTopGovernmentContractors to rank companies market-wide'). It also flags the coverage limits that make it inappropriate as a total-revenue measure.

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?

Annotations already establish readOnlyHint=true, and the description adds genuine behavioral context beyond that: results are anonymized aggregates by filer type, and the active-holder change deliberately excludes index-like books. That tells the agent what the numbers mean and what they omit, which annotations cannot convey.

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 output scope is front-loaded, but the two long sentences are dense and run-on, packing dimensions and the index-exclusion caveat together. It is informative yet heavier than needed for three 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?

With no output schema, the description must explain return values and does so well: bucket share, like-for-like change, and new/exited filer counts, plus the active-holder variant. Only the routing against sibling holder tools is left implicit.

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 dimension parameter already lists its allowed values, so the schema carries the parameter burden. The description restates the dimension options and clarifies they are holder-splits rather than adding new semantics, 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 holder mix for a stock/ETF) and the concrete outputs: each bucket's share of 13F common shares, like-for-like change, and new/exited filers. The 'regulatory records, never names' clause distinguishes it from name-level siblings like GetTopHolders, though it never names an alternative outright.

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 only implied: the 'never names' note suggests this is the aggregate view versus a name-level tool, but there is no explicit when-to-use or when-to-prefer-a-sibling statement despite many overlapping neighbors (GetTopHolders, GetHolderTypeFlows, GetMostHeldStocks).

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?

Beyond the readOnlyHint annotation, the description discloses genuine behavioral traits: trades are priced at quarter-average prices, filers with no prior-quarter 13F contribute no flow, and buckets are regulatory records that never name individuals. The last point is an important privacy disclosure not present in any structured field. It stops short of describing pagination or response format.

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?

Three dense but front-loaded sentences: the purpose and output metrics come first, then the dimension list, then the pricing/prior-book caveat. Every sentence carries information; only minor tightening would help.

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 return-value burden and does so by naming the specific metrics returned (net flow, net flow as % of prior book, net buyers vs sellers). It is complete enough to call the tool correctly, though it omits any indication of result size or ranking order.

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 adds meaning beyond the schema: it groups the dimension tokens as 'holder type, measured style, turnover, horizon, book size, client base, private funds or location' in plain language, notes that sector splitting is optional, and adds that ETFs are separated out ('with ETFs apart') — a sector-grouping detail absent from 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?

The description states a specific verb and resource (market-wide 13F money flows for a closed quarter, broken down by kind of filer) and enumerates exactly what is produced (bought/sold, net flow, net flow as % of prior book, net buyers vs sellers). This clearly separates it from generic holder tools, though it does not explicitly name which sibling it supersedes. 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 scope is implied ('closed quarter') and the bucket/sector options signal context, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g., GetMarketWide13FActivity or GetHolderMix). The agent must infer selection from the sibling list rather than the text.

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?

Annotations only include readOnlyHint=true, but the description adds rich behavioral context: data source (SEC Form 3/4/5), computation methodology (closing balance per security, actual shares only, excluded derivatives, restated to today's split basis), caveats about indirect understatement and stale/zero former insiders, and the default maxResults limit. This significantly exceeds 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?

The description is front-loaded and well-structured, moving from purpose to methodology to caveats to usage. However, it is somewhat verbose—some sentences (e.g., the detailed explanation of indirect understatement) could be tightened without losing essential meaning.

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 should explain return values. It covers the key output aspects (ranked by total shares held, Direct and Indirect columns, maxResults limit) but does not specify other returned fields like insider names or relationships. This is largely adequate for a summary tool, though slightly 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 description coverage is 100%, so all parameters are already well-documented in the input schema. The description mentions maxResults default 30 but adds no new parameter semantics beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (insider ownership summary for a stock), and explicitly distinguishes from the sibling GetInsiderTransactions by saying to use that for underlying trades. An agent can immediately understand what this tool does and when to pick it over the 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?

Explicitly says 'Use this to understand the insider ownership structure of a company; use GetInsiderTransactions for the underlying trades.' This provides both the intended use case and a clear alternative, leaving no ambiguity about when to select this tool.

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 readOnlyHint=true already covering safety, the description adds substantial context: Form 3 vs Form 4/5 scope, the meaning of each Type code, the 10b5-1 column ('-' means pre-2023 filing), and that Owned After is restated onto today's split basis. It does not cover auth requirements or rate limits, but for a read tool it discloses a lot beyond annotations.

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?

It is dense but front-loaded, leading with purpose, then scope exclusions, then column semantics, then filters. Every sentence carries information, though the column-by-column explanation is long enough to sacrifice some scannability.

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 explain return columns, and it does: Type, 10b5-1, Shares/Price/Value, and Owned After. Combined with the fully documented input schema, an agent has everything needed to call and interpret this tool.

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%, so the baseline is 3, but the description adds real meaning by explicating the transactionType values ('Buy'/'Sell' are open-market only versus compensation/derivative mechanics) and matching the descriptive filters (date-range, transaction-type, insider-name) to their parameters. The insiderName multi-word matching nuance is left 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?

The description states a specific verb and resource ('Get recent insider trading transactions for a stock') and names its source (SEC Forms 4 and 5) and ordering ('newest first'). It also excludes Form 3 by explaining it covers initial ownership, not transactions. It stops short of distinguishing itself from sibling tools like GetInsiderOwnership or SearchInsiders.

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 context is implied by the trailing 'Use this to understand insider buying/selling activity' and by the filter list, but there is no explicit when-to-use/when-not guidance or named alternative among siblings like GetInsiderOwnership or SearchInsiders. The interpretation guidance is helpful but does not route the agent between 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?

With readOnlyHint=true already covering safety, the description adds substantial behavioral context: the legacy Total Shares field is not a pure share-ownership measure, QoQ change is like-for-like with exclusions noted, missing filings are not treated as trades, values use report-date closing prices with possible fallbacks and zeros, and the newest quarter uses a provisional combined view for non-ETF primary stocks while ETFs remain exact.

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 purpose is front-loaded in the first sentence, and the dense caveats that follow are relevant and earn their place. The description is long and clause-heavy, but the complexity of the 13F data aggregation justifies most of the detail.

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, but the description explains the key returned fields (total reported quantity, published position value, filer count, QoQ share change with exclusions) and the important caveats about provisional data and fallback values. An agent has enough information to call and interpret 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?

Schema description coverage is 100%, so both the ticker and maxPeriods parameters are already documented in the schema. The description reinforces that ticker should be an exact stock or ETF listing and mentions multiple quarters, but it adds little syntax or format detail beyond what the schema provides.

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 and resource: get the historical trend of aggregate reported 13F exposure for an exact stock or ETF listing across multiple quarters. It also names the metrics returned (quantity, position value, filer count), making the tool clearly distinguishable from siblings like GetTopHolders or GetHolderMix.

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 usage through phrases like 'exact stock or ETF listing' and 'across multiple quarters,' but it does not explicitly say when to use this tool versus alternatives such as GetInstitutionQuarterlyActivity or GetTopInstitutionalBuyersSellers. The detailed caveats are helpful but are not usage routing 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?

Annotations only supply readOnlyHint=true, so the description carries most of the behavioral load and does so well: it discloses the reconstruction methodology, the filing-lag rebalancing, raw-price valuation, that a split without a certified price basis suppresses returns, and that the window is not silently shortened. These are non-obvious operational traits that meaningfully affect interpretation.

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-loads the purpose, then layers methodology, outputs, and the failure mode in three dense but coherent sentences. The split-price caveat is slightly tangential but earns its place by setting honest expectations; overall tight with little 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?

With no output schema, the description compensates by enumerating the returned metrics (price return, CAGR, max drawdown, price-return alpha) and naming the conditions under which returns are unavailable. Nothing essential for correct invocation 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?

Schema description coverage is 100%, so the schema already documents defaults and the fromDate-overrides-windowYears precedence. The description's framing of 'either... windowYears or... fromDate/toDate range' adds only marginal interpretive value over that, 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 ('Backtest'), a specific resource (an institutional filer's reported 13F portfolio) and a comparison target (market benchmark). It is clearly distinguishable from siblings like GetInstitutionPortfolio or CompareInstitutionPortfolios, which report holdings rather than simulate performance.

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?

Explains the two operating modes clearly: a trailing window via windowYears or an anchored window via fromDate/toDate, which tells the agent when each parameter set applies. However it never names a sibling alternative or states an explicit when-not-to-use condition.

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?

annotations already declare readOnlyHint=true, so the safety profile is covered, and the description adds genuinely useful behavioral context beyond it: valuation uses report-date closing prices, may fall back to filer values, and can legitimately be zero. The 'latest common report date' selection behavior is also disclosed.

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?

Four tightly-packed sentences: purpose and scope first, then ranking, then a valuation caveat, then a parameter hint. No filler, though the valuation sentence is dense and could be split for readability.

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 must carry more of the return-value burden, and it only hints at output via 'ranks stocks by holder count, then combined value.' It never describes the returned fields or shape, and error behavior for ambiguous partial names is left entirely to the schema.

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%, so all four parameters are already documented structurally. The description largely restates schema content (minInstitutions threshold, common report date) rather than adding new parameter semantics, 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 and resource ('Combine 2-25 institutions' 13F portfolios on their latest common report date') plus the ranking logic ('by holder count, then combined value'). This is clearly distinguishable from a plain single-portfolio getter, but no sibling is named to disambiguate it from CompareInstitutionPortfolios or GetMostHeldStocks.

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 line 'Set minInstitutions to 2 or more for positions shared by multiple filers' implies when a parameter is warranted, and the '2-25 institutions' bound implies scope. However there is no explicit when-to-use-vs-alternatives guidance nor any when-not statement, leaving the agent to infer the tool's niche from the sibling list.

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 readOnlyHint=true already covering the safety profile, the description adds genuinely useful behavior: values use report-date closing prices, may fall back to filer values, can be zero when unavailable, and coverage is limited to tracked U.S.-listed common stocks plus related put/call positions. It stops short of describing pagination behavior or result ordering beyond 'largest positions by published value'.

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?

Four tightly packed sentences, front-loaded with purpose before the data caveats. Every sentence carries information, though the parenthetical about default/max rows is redundant with the schema and could be dropped.

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 usefully enumerates the returned fields and flags data-quality edge cases (zero values, options ambiguity, coverage limits). The one remaining gap is what happens for an institution with no 13F-HR filings or an out-of-range offset, but the definition is otherwise call-ready.

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%, so the schema already documents all four parameters, including clamping ranges, date snapping, and pagination math. The description only restates the default/max row count (20 / 500), adding essentially nothing beyond the schema — the baseline 3 for full coverage 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 states a precise verb and resource: view tracked stock positions of a specific institutional investor from an SEC 13F-HR filing. It also names the fields returned (share counts, value, percent of tracked 13F value, position count), which cleanly separates it from siblings like GetTopHolders or GetMostHeldStocks that aggregate across institutions.

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 advice ('Use SearchInstitutions first when the name is ambiguous') and a caveat for interpreting options data. However, it never distinguishes this tool from close siblings such as CompareInstitutionPortfolios, GetInstitutionSummary, or GetInstitutionalOwnershipHistory, so the agent must infer when this single-holder snapshot is preferred.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds substantial behavior beyond that: results are markdown sections per bucket, sorted by absolute Δ market-value descending, and Δ Value includes price movement rather than trading alone. It omits return-size/pagination behavior, but the core behavioral caveats are well disclosed.

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 front-loaded with the core purpose and then layers on filtering and output-format details. It is dense and mostly efficient, though the final 'Use this to answer...' sentence is somewhat rhetorical rather than strictly necessary.

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 explaining returns and does so: markdown sections per bucket, separate rows by Type, and sorting by absolute Δ market-value. Combined with a fully documented input schema, an agent has enough to call the tool correctly and interpret its output shape.

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%, so the schema already explains all four parameters, including bucket enum-like options, maxResults clamping, and reportDate snapping. The description reinforces the bucket filter but adds little parameter-level syntax or meaning beyond the schema, so the baseline 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?

States a specific verb and resource: getting an institution's quarterly position-change activity, with the four buckets (Initiated/Increased/Reduced/Exited) defined as quarter-over-quarter diffs. It clearly distinguishes itself from portfolio-holding siblings like GetInstitutionPortfolio by focusing on what changed this quarter, not what is held.

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?

Explicitly says to use it to answer 'what did this fund do this quarter?' and explains that `bucket` filters to one of the four buckets. It does not name alternative tools such as GetInstitutionPortfolio or CompareInstitutionPortfolios or state when not to use it, 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?

With only readOnlyHint=true in annotations, the description carries real behavioral weight: it discloses the markdown table return, descending % sort, the collapsed 'Unclassified' row, data provenance (report-date closing prices with fallback to filer values, possibly zero), and the ambiguity handling for partial names. This is far more than the 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?

Three dense sentences with the core purpose and grouping default front-loaded; the caveats about pricing fallback and ambiguous names are placed after the essential facts. Slightly heavy for the tool's simplicity, but no sentence 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?

No output schema exists, so the description properly explains the return format, ordering, and the Unclassified bucket, and it covers the default/fallback behavior for both optional parameters. Nothing an agent needs to invoke this correctly 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies that groupBy toggles fine-grained industry versus broad sector rollup and that a non-resolving name yields candidates 'instead of selecting silently.' The reportDate snapping rule largely duplicates the schema text.

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 and resource ('Get an institution's 13F portfolio allocation') plus the grouping axis and output shape, which separates it from sibling allocation tools like GetInstitutionPortfolio, GetHolderMix, and GetTopHolders. An agent can tell what it returns (industry- or sector-level allocation table) 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 clear context: use it per report quarter with a latest-date default, and route to SearchInstitutions when an exact CIK is needed. It also warns that ambiguous partial names return candidates rather than silently selecting. It stops short of explicitly naming a sibling to use instead for related portfolio views.

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?

Annotations only declare readOnlyHint=true, so the description carries most of the load, and it delivers: it discloses that bands are measured against stated thresholds rather than the firm's own description, that active share is computed against every 13F filer's combined book, and that only closed quarters are scored (the newest quarter appears once its filing window closes). It omits return format and pagination details, keeping it from a 5.

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 purpose is front-loaded in the first clause and every sentence earns its place - the enumerated measurements justify their length because no output schema exists. The single sprawling second sentence with a long parenthetical is dense, but not padded.

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 only a readOnlyHint annotation, the description must describe the return payload itself, and it does by enumerating the bands and backing measurements (equity value, stock count, active share, top 10 weight, effective positions, turnover, holding period). The quarter-closure timing rule further completes the picture; only the ordering/pagination shape of the response is left implicit.

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%, so both parameters (maxPeriods, institutionName) are already fully documented in the schema, including the default, clamping range, and partial-CIK resolution behavior. The description adds no syntax or format detail beyond what the schema provides, so 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 states a specific verb+resource ('Get an institutional 13F filer's portfolio style quarter by quarter') and enumerates the exact style/turnover/horizon bands and underlying measurements, which sharply distinguishes it from sibling tools like GetInstitutionPortfolio or GetInstitutionSummary. It stops short of explicitly naming a sibling it differs from, 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?

Usage is implied by the purpose - an agent would infer this is for time-series style analysis of a single filer - but there is no explicit when-to-use, when-not, or named alternative among the many institution siblings (GetInstitutionPortfolio, GetInstitutionQuarterlyActivity, CompareInstitutionPortfolios). The 'Closed quarters only' note is a data-availability caveat rather than routing 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?

With readOnlyHint already declaring the safety profile, the description adds substantial behavioral context: it explains that values normally use report-date closing prices, may fall back to filer values, and can include zero for unavailable valuations. It also discloses that ambiguous partial names return candidates rather than silently selecting a filer, which is important invocation 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?

The purpose is front-loaded and most of the length earns its place by enumerating return categories in the absence of an output schema. However, the description is a dense run-on sentence with repeated 'then' clauses, making it harder to scan than it could be. Slight structural improvement would raise this score.

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 read-only tool with no output schema, the description is comprehensive: it covers portfolio summary fields, concentration and turnover metrics, report-date context, profile data from regulatory records, style bands, pricing caveats, and CIK resolution behavior. An agent has enough information to call it correctly and understand what comes back.

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%, so the schema already documents both parameters, including reportDate defaulting and off-quarter snapping. The description reinforces CIK/name behavior and date-count context but adds little parameter syntax beyond the schema. Baseline 3 is appropriate when the schema carries 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?

The description states a specific verb and resource: get the portfolio summary header for an institutional 13F filer. It scopes the result with concrete contents and explicitly clarifies that the value is published tracked 13F value, not total firm AUM. It also distinguishes name resolution via SearchInstitutions from silent filer selection.

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 gives clear usage guidance for the institutionName parameter, directing ambiguous partials to candidate CIKs and exact CIKs to SearchInstitutions. However, it does not explicitly say when to use this summary tool versus siblings such as GetInstitutionPortfolio, GetInstitutionQuarterlyActivity, or CompareInstitutionPortfolios. Main tool-selection guidance is therefore implied rather than explicit.

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?

Annotations already declare readOnlyHint, so safety is covered. The description goes beyond them by warning that exempt reporting advisers do not report Item 5 figures (RAUM, employee count, fee structure), which prevents the agent from treating a missing field as an error. It doesn't describe behavior for an invalid or unknown CRD.

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 field list is front-loaded immediately after the resource, and the exempt-adviser caveat and the sibling pointer follow logically. The enumeration of returned fields is long but each element earns its place given there is no output 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?

With no output schema, the description fully enumerates what the call returns and flags the one case where fields will be absent. Nothing an agent needs to call it correctly or interpret a sparse response 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?

Schema description coverage is 100% and the schema already states 'Organization CRD number' with an example, so the schema carries the parameter explanation. The description reinforces that it is the Organization CRD (not an individual CRD) but adds little syntax or format detail beyond that. Baseline 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?

States a specific verb ('Get') and resource ('Form ADV profile') and enumerates the exact contents returned: names, CRD, SEC file number, office, website, RAUM breakdown, employee count, fee structure. It also explicitly scopes which entities are covered (SEC-registered or exempt reporting advisers), which separates it from SearchInvestmentAdvisers.

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?

Explicitly tells the agent to use SearchInvestmentAdvisers to find the CRD number, giving a clear prerequisite and alternative path. It doesn't state when-not-to-use beyond that, but the lookup-then-fetch workflow is fully implied.

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?

Annotations already mark it readOnly, so the burden is lower, and the description still adds real context: the underlying data source (FINRA daily short sale files), the definition of Short % as FINRA-facility/TRF off-exchange share, and the interpretive baseline that 40-50% is normal market-making. It does not discuss pagination limits itself (deferred to the schema), which keeps it short of a 5.

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?

Dense but front-loaded: the core purpose and scope come first, followed by disambiguation and then the tuning tip. The parenthetical sibling list is long but each reference earns its place; only the nested asides make it slightly heavier 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?

For a read-only ranked-list tool with full schema coverage and a declared readOnly annotation, this covers purpose, source, metric interpretation, and alternatives. The only gap is that returned row fields are never described, though with no output schema that omission is minor.

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 3 is the floor; the description goes beyond the schema by calling out the cross-parameter interaction (sortBy=shortPercent requires a minTotalVolume floor or illiquid names dominate) and by framing the date default. That interaction guidance is the main added semantic value.

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 a specific verb+resource+scope: the largest daily short-sale-volume securities (including ETFs) for a single trading day, sourced from FINRA's daily short sale volume files, sorted descending. It explicitly distinguishes itself from position-based siblings (GetShortInterest, GetShortInterestSnapshot) and the single-security GetShortVolume.

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?

Routes the agent away from this tool with named alternatives and the condition that selects each: positions -> GetShortInterest/GetShortInterestSnapshot, squeeze candidates -> GetShortSqueezeScores, per-security history -> GetShortVolume. It also states the internal alternative (sortBy=shortPercent plus a minTotalVolume floor) for ranking by intensity rather than raw size.

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?

Annotations only declare readOnlyHint=true, so the description carries the rest and does so well: it names the data source (legacy futures-only COT report), the reporting cadence (positions as of each Tuesday, published Friday), and the content (commercial and non-commercial net positions in contract counts). This is real behavioral context beyond the safety hint, missing only return/pagination details.

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?

Three tight sentences with no filler, front-loading the core purpose before the data-source and timing details. The category enumeration is slightly redundant with the schema but does not bloat the text.

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 covers the essentials an agent needs: one-row-per-market semantics, the fields shown, the reporting window, and the cross-reference to GetCftcPositioning. Missing only return-format specifics, but sufficient for a simple read-only snapshot tool.

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 schema already documents the single optional category parameter, making the baseline 3. The description repeats the category list but does not add filtering syntax or notes beyond what the schema provides (and spells 'Equity Indices' differently from the schema's 'EquityIndices').

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 and resource: getting the latest COT positioning snapshot across all tracked futures contracts, grouped by category. It hints at a distinction from GetCftcPositioning by noting each row carries the market code that tool accepts, though it doesn't fully articulate the division of labor. Clear and specific enough that an agent knows what it returns.

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 this is the broad 'latest across all contracts' view and that GetCftcPositioning takes a specific market code, which gestures at when to use each. However, it never explicitly says when to prefer this over the sibling or states any prerequisites. Usage is inferable 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?

Goes well beyond the readOnlyHint annotation, disclosing settlement lag (rows can have different dates; use the Date column), the exact conditions under which change is omitted, split-limited/partial 52-week range marking, and currency behavior per listing.

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 the core operation, then edge cases in descending importance. Efficient overall, though the change-omission sentence is dense and slightly unwieldy; every sentence still carries real 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 no output schema, the description carries the return-shape burden and does so: it enumerates change, volume, trailing 52-week range, the Date column, and where the currency note appears. Complete enough to call 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?

Schema coverage is 100%, so the schema already documents the tickers array, the 25-max cap, BRK-B/BRK.B handling, and the MIC:TICKER format. The description adds only the currency-per-listing nuance, so the baseline 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?

States a specific verb (Get) and resource (each ticker's newest traded, settled daily close) with scope detail on currency and the MIC:TICKER variant. The closing line 'settled history, not an intraday quote' cleanly separates it from sibling price tools like GetStockPrices.

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?

Clearly frames when to use it (settled history) and when not to (intraday), which is a genuine usage boundary. It does not name a specific alternative tool, so the routing is contextual rather than explicit.

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?

Annotations cover only readOnlyHint=true, and the description adds genuinely useful behavior beyond that: the row shape (latest stored observation + date + previous observation + change), the caveat that values are 'latest stored' and freshness must be verified via the Latest Date column, and the fact that it returns a full macro snapshot rather than a single 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?

Three sentences, front-loaded with the scope and categories before the row-format detail. Nearly every clause earns its place; only the final 'Returns a snapshot of current macro conditions' is mildly redundant with the opening 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?

With no output schema and only a readOnlyHint annotation, the description carries the burden well by describing the returned columns and freshness semantics. It is close to complete, missing only guidance on breadth vs single-series siblings and any note on whether results are paginated or cached.

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 optional category parameter is fully documented with its allowed values, so the schema does the heavy lifting. The description restates the category list but adds no filtering syntax, default behavior, or format detail beyond it, so 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 verb and resource (get latest values for economic indicators) and enumerates the covered categories, so the scope is unambiguous. It does not, however, name or contrast itself with the nearby siblings GetEconomicIndicator and SearchEconomicIndicators, leaving the agent to infer that this is the breadth/snapshot variant.

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 never states when to pick this over GetEconomicIndicator or SearchEconomicIndicators, nor any prerequisites. The only guidance is interpretive ('check the Latest Date column for freshness'), which helps read results but not select the tool.

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?

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.

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

Adds value beyond readOnlyHint annotation by explaining that values are ranges (min-max), missing years mean no electronic filing not zero, and that only electronically filed reports are read. No contradictions with annotations.

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?

Three concise sentences covering purpose, data interpretation, and prerequisite. Every sentence adds value with no redundancy or fluff.

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 key aspects: what is returned, interpretation of missing years, and how to find member names. Lacks explicit mention of output format but is sufficient for a read-only tool with simple parameters.

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 baseline is 3. Description enhances understanding by clarifying case-insensitivity of memberName and directing to SearchCongressMembers for exact names, adding value beyond schema descriptions.

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?

Description clearly states it retrieves net worth history from annual financial disclosures, with distinct verb and resource. It differentiates from sibling tools like GetCongressionalTrades by focusing on net worth.

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?

Suggests using SearchCongressMembers to find names but does not explicitly define when to use this tool versus alternatives or provide exclusion criteria. Usage context is implied rather than explicit.

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?

The readOnlyHint annotation already establishes this as a safe read, lowering the burden. The description adds useful behavioral details beyond that: results are sorted newest first, the default time window is one year, and specific fields are returned. It does not mention rate limits, pagination behavior, or output limits, but for a read-only query with rich schema documentation this is a minor 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?

Three sentences, each earning its place: the first defines the tool and scope, the second lists returned data because there is no output schema, and the third routes to alternatives. Front-loaded and free of 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 enumerating the returned fields (tickers, dates, amount ranges, asset, party). It covers default date range, ordering, and sibling routing, while the fully documented schema handles pagination and parameter details. An agent has everything needed to call it 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?

Schema description coverage is 100%, so every parameter is already fully documented in the input schema. The description does not add syntax or semantics beyond what the schema provides for memberName, ticker, dates, offset, maxResults, or transactionType. Baseline 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 states a specific verb ('Get') and resource ('a congress member's disclosed securities transactions') and adds scope details (newest first, last year by default). It explicitly distinguishes this tool from the sibling GetCongressionalTrades, which covers all members in one ticker, so an agent can route correctly 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?

It names the two relevant alternatives and their conditions: SearchCongressMembers to find the exact member name and GetCongressionalTrades for all members' transactions in one ticker. The implied when-to-use is clear from the first sentence: retrieve one member's transactions.

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?

Annotations only declare readOnlyHint=true, but the description adds substantial behavioral context beyond that: valuation uses report-date closing prices with fallback to filer values, zero can appear for unavailable valuations, only the first complete report quarter is published, and during the newest quarter's open filing window non-filers carry prior-quarter positions. This is unusually rich disclosure.

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?

Dense but front-loaded, leading with the core purpose before folding in caveats and routing. Every sentence carries information; it is tightly packed rather than padded, though the volume of caveats makes it slightly heavy.

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 naming the returned fields (Δ filers, total value, Δ value, share of the 13F universe) and explaining valuation fallbacks and availability limits. 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 description coverage is 100%, so the schema already documents sort, maxResults, and reportDate in detail (including the off-quarter snapping behavior). The description restates the sort dimensions but adds little syntax or format detail beyond the schema, so 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 verb+resource with scope: 'cross-sectional ranking of stocks by institutional 13F breadth for a quarter.' It clearly distinguishes itself from the sibling GetMarketWide13FActivity by explaining that only currently-held stocks rank here and sold-out names belong there.

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?

Explicitly routes the agent: names GetMarketWide13FActivity as the alternative for sold-out names, and flags when rankings/deltas are unavailable (pre-first-complete-quarter, boundary quarters). The conditions that select alternatives 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?

Beyond the readOnlyHint annotation, the description discloses several high-value behaviors: the FINRA file excludes consolidated tape volume (so share-of-volume must be computed elsewhere), weeks before 2025-08-11 may include case-variant sibling data, and publication is delayed by tier. This is exactly the kind of context annotations cannot carry.

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 it returns, then the caveats. It is dense and multi-sentence but each sentence carries real information (component breakdown, missing consolidated volume, data-quality window, delay). Slightly long, but 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, the description compensates by enumerating the per-week fields and flagging the consolidated-volume gap and the pre-2025-08-11 data caveat. Nothing an agent needs to interpret or correctly qualify the result 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?

Schema description coverage is 100%, so the schema already documents all four parameters with types and defaults. The description adds no parameter syntax or format detail beyond noting the listing must be exact; baseline 3 is appropriate when the schema does the heavy lifting.

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), resource (weekly off-exchange/dark pool/OTC trading volume), and source (FINRA OTC/ATS Transparency), and even defines the components returned (ATS, non-ATS OTC, total). An agent can distinguish this from volume siblings like GetShortVolume or GetOnBalanceVolume without opening any 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 description scopes usage well (exact stock or ETF listing, weekly granularity) and implicitly tells you when it applies, but it never names an alternative tool or an explicit when-not condition. With many volume-adjacent siblings, an explicit routing hint would be needed for a higher score.

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?

Annotations already establish readOnlyHint=true, but the description goes further with a real behavioral caveat: OBV is anchored at 0 on the first requested bar and absolute levels are not comparable across calls. That 'read the slope, not the level' warning is non-obvious operational context an agent would otherwise get wrong.

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?

Three tight sentences, front-loaded with the definition and followed by usage and the critical caveat; there is no filler and the most decision-relevant warning is placed last for emphasis without burying the core meaning.

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 read-only, no-output-schema indicator tool the description covers what it computes, how to interpret the series, and the cross-call comparability pitfall. It stops short of noting anything about series length or pagination behavior, but nothing essential for a correct call 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?

Schema coverage is 100% so parameter definitions carry the baseline, but the description adds genuine semantic weight by tying startDate to a data-interpretation consequence (the anchor point shifting absolute values between calls) that the schema itself does not state.

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 gives a specific resource (On-Balance Volume for a stock) plus the exact computation rule (add volume on up-closes, subtract on down-closes, flat on equal closes), which makes it clearly distinguishable from the other technical-indicator siblings like GetStochasticOscillator or GetBollingerBands.

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 states the analytic use case ('confirming or diverging from price trends with volume flow') but offers no explicit when-to-use/when-not guidance and never names an alternative indicator or the conditions that would select one.

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?

Annotations declare readOnlyHint=true, consistent with the data retrieval nature. Description adds behavioral context: sampling frequency for pre-2013 data and available types (Total, Equity, etc.). No contradictions.

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?

Description is concise with three sentences, front-loaded with purpose and key details. Slightly verbose with repeated 'available types' but still efficient.

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, but description sufficiently explains return values (ratio data, volumes). Covers data history, sampling, and interpretation. Missing explicit note about required permissions or response format.

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 description adds value by explaining the meaning of ratio values for the 'type' parameter and order for 'maxResults'. Could include more detail about date format validation.

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 it gets CBOE put/call ratio data for market sentiment, with specific verb 'get' and resource 'CBOE put/call ratio data'. It distinguishes from siblings by focusing on this unique sentiment indicator.

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 explains interpretation of high/low ratios and data availability periods, providing context for use. However, it does not explicitly mention when to use this tool over similar sentiment tools like GetShortVolume or GetVixHistory.

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?

Annotations only carry readOnlyHint=true, so the description must carry behavioral context and it does: as-reported vs derived distinction, operating margin derived as operating income / revenue for the same folded member QName and period, one table per axis, and an explicit overlap warning against summing rows. This is far beyond what the annotations disclose.

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-loads the purpose and keeps every clause informative — the overlap warning and derived-margin rule earn their space. It is somewhat dense and run-on (nested em-dash asides in a single paragraph), which slightly hurts scannability, but there is minimal 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?

No output schema exists, so the description must convey the return shape, and it does: one table per axis, a consolidated total row per table, as-reported vs derived fields. For a two-parameter read tool with thin annotations, this is complete enough to call and interpret 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?

Schema description coverage is 100% and both parameters (ticker, maxYears) are fully documented in the schema with examples, format (MIC:TICKER) and defaults/max. The description adds no parameter-level detail beyond the schema, 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 (Get) and resource (revenue disaggregated by business segment, geography, product/service) plus the extra payload (operating income by segment). It explicitly differentiates from siblings by naming GetFinancialStatement and GetFinancialFact as the route for consolidated figures. An agent can pick this tool apart from the other financial tools without inspecting either 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?

Explicit scope limits: 'Annual fiscal years only', 'latest restated values', plus a clear 'use X instead' for consolidated figures. It also flags the trap case (row overlap, never sum rows) which tells the agent how to interpret results correctly. Both when-to-use and when-not-to-use are present.

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 only readOnlyHint=true available, the description carries real behavioral load: it discloses split-restated share counts vs. as-reported days-to-cover, FINRA's 999.99 cap, and critically that the model estimate appears BELOW the table and must never be presented as a FINRA figure. That last point is a non-obvious, high-value caveat absent from structured fields.

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 payload are front-loaded, then interpretations, alternatives, and finally the estimate caveat. Dense but nearly every sentence earns its place; the squeeze-threshold remark and estimate caveat make the tail slightly long for a list endpoint.

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 describe return values — and it does: short position, prior-settlement change, average daily volume, days to cover, plus the appended model estimate. An agent has everything needed to call and interpret it 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?

Schema coverage is 100%, so ticker, startDate, endDate and maxResults are already fully documented, including the max=500 and oldest-to-newest ordering. The description adds settlement-date context but no parameter syntax 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 concrete verb+resource ('Get bi-monthly short interest history ... from FINRA') and scopes it to 'an exact stock or ETF listing'. It explicitly distinguishes itself from siblings by naming GetShortSqueezeScores and GetShortInterestSnapshot, so an agent can route without opening any 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 explicit alternatives with the selecting condition: % of shares outstanding / squeeze ranking → GetShortSqueezeScores, market-wide latest settlement → GetShortInterestSnapshot. This is exactly the when-to-use/when-not guidance the dimension asks for.

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?

Annotations already establish readOnlyHint=true, so safety is covered. The description adds non-obvious data semantics: FINRA caps days to cover at 999.99, capped rows are a sentinel from illiquid names with tiny volume denominators, and those rows are ranked after real readings. That is genuine behavioral context beyond the structured fields, though it does not cover auth, rate limits, or refresh cadence.

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?

Three sentences, front-loaded with the snapshot scope before the sibling routing rules. Dense but every sentence carries information; there is minor overlap with the schema's sortBy description of the 999.99 sentinel, which slightly dilutes efficiency.

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 supplies the key return shape ('one row per exact listed security') and default ordering, and covers the tricky filtering case. It stops short of naming any returned fields, but for a read-only market snapshot with full parameter coverage this is close to 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 description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the rationale for minAvgDailyVolume (sentinel rows inflated by a tiny volume denominator) with a concrete example value, and by restating the default days-to-cover ordering. It does not add syntax for offset/maxResults, which the schema already handles well.

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 a specific resource and scope ('market-wide snapshot of the latest FINRA bi-monthly short interest settlement — one row per exact listed security') and explicitly distinguishes itself from three named siblings (GetShortSqueezeScores, GetShortInterest, GetShortVolume/GetLargestShortVolume). An agent can identify the tool and its output granularity 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?

States explicit routing rules: use GetShortSqueezeScores for genuine squeeze candidate ranking, GetShortInterest for a single stock/ETF's history, GetShortVolume/GetLargestShortVolume for daily flow. It also gives an actionable 'when' for a parameter (pass minAvgDailyVolume to drop illiquid names), leaving nothing to inference.

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?

Annotations only declare readOnlyHint=true, so the description carries most of the burden and does well: it discloses the scoring methodology, that liquidity floors filter the board without altering scores, that floors are ignored for a single-ticker lookup, and why ETFs are excluded. It does not cover pagination or result freshness, but that gap is largely filled by the schema.

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-loads purpose and scoring inputs, then mode behavior, then the exclusion and alternative. Dense but every clause carries information; the only cost is that it packs a lot into a few long sentences, which slightly hurts scannability.

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 five documented parameters, the description supplies what an agent needs: what the score is, what universe it applies to, how modes and floors interact, and where to go for the excluded ETF case. Nothing material to correct invocation 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?

Schema coverage is 100%, so the baseline is 3, and the description adds real meaning on top: it clarifies that liquidity floors do not change scores and that they do not apply to a ticker lookup, and that a ticker query returns a factor breakdown plus universe rank rather than a board. This resolves interaction questions the schema alone does not.

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 and resource ('Rank primary operating-company stocks by a peer-relative 0-100 short-squeeze score') and enumerates the factors that feed the score. It explicitly scopes the universe (primary operating companies, ETFs excluded) and points to the sibling GetShortInterest for the ETF case, so an agent can distinguish it from GetShortInterest, GetShortVolume, and GetFailsToDeliver without opening any 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 clear context (screening/ranking for squeeze candidates) and an explicit alternative for the out-of-scope case ('use GetShortInterest for an ETF's exact FINRA series'). It also distinguishes board mode from single-ticker mode. It stops short of stating when *not* to use this tool for operating companies generally, so it is strong but not fully exhaustive.

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?

Annotations only declare readOnlyHint=true, but the description adds critical behavioral context: volumes cover FINRA off-exchange/TRF trades only, not consolidated tape, and a 40-50% Short % is a normal baseline from market-maker liquidity. These are non-obvious data quirks that prevent misinterpretation.

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 front-loaded with the primary purpose and then layers essential caveats and alternatives without wasted words. Every sentence contributes either scoping, warning, or disambiguation value.

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 still names the return fields (short volume, short-exempt volume, total volume, short volume percentage per trading day). Combined with the data-source caveat and sibling disambiguation, an agent has everything needed to call and interpret 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?

Schema description coverage is 100%, so the schema already fully documents ticker, startDate, endDate, and maxResults. The description adds no parameter-specific semantics beyond what the schema provides, which meets the baseline of 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?

The description states a clear verb and resource ('Get daily short sale volume history for an exact stock or ETF listing') and immediately scopes it to FINRA short sale volume files. It explicitly distinguishes this daily flow metric from related tools like GetShortInterest, GetLargestShortVolume, and GetShortSqueezeScores.

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 when-to-use guidance by naming alternatives and their distinct purposes: 'use GetShortInterest for positions, GetLargestShortVolume for a market-wide single-day ranking, and GetShortSqueezeScores for squeeze candidates.' It also warns against misquoting the metric as a share of total traded volume.

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 readOnlyHint=true already covering the safety profile, the description still adds real behavioral context: the warm-up on price history fetched before startDate, and the explicit guarantee that values do not depend on the requested range's left edge. That is a non-obvious trait an agent would otherwise have to discover by experiment; only pagination/row-limit behavior (found in the schema) is left unaddressed.

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?

Four sentences, all load-bearing: indicator definition first, then the two series, then the practical interpretation, then the one non-obvious caveat. Nothing is repeated and the core identity is front-loaded.

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 does supply the shape of the return conceptually (%K and %D series over the requested window), and it flags the warm-up semantics that affect results. It stops short of describing row ordering, default window size, or the maxResults cap, though those live in the schema.

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?