Equibles

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

Annotations only cover the safety profile (readOnly=false, destructive=false, openWorld=false); the description adds real behavioral detail beyond that: unknown or expired option contracts are rejected, and identical retries inside the duplicate window return the existing lot instead of creating another. That idempotency disclosure materially changes how an agent should retry.

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 core action and the no-guessing rule are front-loaded, and nearly every sentence carries a distinct rule (symbol format, signed quantity, price convention, currency units, idempotency). It is a dense single block, however, so the option/stock and currency rules are harder to scan than they need to be.

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 8-parameter mutation tool with no output schema and no parent annotations beyond safety hints, the description covers validation behavior, currency handling, and duplicate-window semantics well. It does not describe permissions/authorization or what the successful response contains beyond the duplicate-retry case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-cutting meaning the schema states only piecewise: quantity is signed (negative for short/written), costPerUnit is always the positive per-share/per-contract premium and never the per-contract total, and prices are in the listing's currency in major units (pounds not pence).

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 opens with a specific verb+resource+scope: 'Record a user-confirmed purchase or sale in the caller's portfolio.' It also implicitly separates itself from UpdatePortfolioLot/ClosePortfolioLot by framing the action as recording a new buy/sell rather than amending or closing an existing lot.

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 strong precondition guidance ('Never infer or guess the instrument, quantity, price or date') and per-instrument guidance (ticker for stock, underlying ticker + verified OCC symbol for options). It stops short of naming alternatives for correcting or removing an existing lot (UpdatePortfolioLot / RemovePortfolioLot).

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 indicate readOnlyHint=false (mutation) and destructiveHint=false (not destructive). The description adds valuable context: 'The lot moves out of the open positions and its realized profit is kept.' It explains partial close splitting behavior and how options work. This goes beyond annotations and provides necessary behavioral 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?

The description is well-structured: first paragraph states the primary action with a critical user instruction, second explains partial close behavior, third handles options edge cases. Every sentence adds value, no redundancy, and key information 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?

Given the tool's complexity (partial close, options handling) and the absence of an output schema, the description covers the recording action, user interaction requirement, splitting behavior, and connection to AddPortfolioLot. A brief note on the expected response (e.g., confirmation or updated portfolio) would make it fully complete, but the current level is strong.

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. The description adds meaning: clarifies that quantity is optional (omit to close all), closeDate cannot be future or before acquisition, and closePrice is per share received/paid (zero for expired worthless). This adds value beyond the schema's own descriptions, especially for the zero-price case and the partial close behavior.

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 identifies the verb 'Record that the USER sold (or covered, or let expire)' and the resource 'all or part of a lot'. It distinguishes from siblings by noting that options exercised/assigned require a separate AddPortfolioLot for resulting shares, and implies a difference from RemovePortfolioLot by focusing on recording a sale with price and date.

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 guidance: 'Ask the user for the closing price and date; never guess them from a market quote.' It explains how to handle options (expired worthless at price 0, exercised/assigned leads to AddPortfolioLot). While it does not explicitly list when not to use this tool versus RemovePortfolioLot or UpdatePortfolioLot, the context and examples are clear enough for correct usage.

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 cover the read-only, non-destructive safety profile, but the description adds genuinely non-obvious behavior: one row per ticker with the latest-restated value, tickers lacking data listed separately, and the critical caveat that each company's own fiscal calendar governs year/period so peer rows may span different calendar months. The Period End warning is exactly the kind of context an agent cannot infer from 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?

Front-loads the core action and scope in the first clause, then layers return-shape and the fiscal-calendar caveat in descending priority. Every sentence carries distinct 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?

With no output schema, the description carries the return-value burden and does so: it describes row granularity, the latest-restated semantics, missing-ticker handling, and the Period End column to inspect. Combined with the fiscal-calendar caveat, an agent has enough 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 coverage is 100%, so the baseline is 3, but the description adds interpretation meaning: fiscalYear/fiscalPeriod are resolved against each company's own fiscal calendar (NVDA example), which changes how an agent should set and read those parameters. It stops short of adding per-parameter 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?

States a specific verb and resource: compare one financial concept across several companies for the same fiscal period, and labels the use case (peer comparison). This clearly separates it from the single-company GetFinancialFact sibling by scope (several tickers vs one) without needing to open 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?

'Peer comparison' implies when the tool is appropriate, and the multiple-tickers framing suggests its context versus single-fact tools. However, it never explicitly names GetFinancialFact as the alternative or states when NOT to use this tool, leaving routing 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?

The description goes beyond the readOnlyHint annotation by disclosing operational nuances: published values normally use report-date closing prices, may fall back to filer values, and can be zero when unavailable. This is material behavioral context that an agent needs to interpret results correctly.

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 carrying distinct value: what the tool does, what it returns, how to interpret data caveats, and which sibling to use instead. The most important information is front-loaded and there is no filler or repetition of schema content.

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 and minimal annotations, the description covers purpose, return values, data caveats, name resolution, and the key alternative tool. For a read-only comparison tool with four well-documented parameters, this is sufficient for an agent to select and invoke 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 schema already fully documents all four parameters. The description adds some context about the 'latest common report date' and the fact that inputs are institution names, but it does not materially enrich parameter understanding beyond the schema. 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 starts with a strong verb and resource: 'Compare two institutions' 13F portfolios' and specifies the exact output: Jaccard and dollar-weighted overlap, portfolio totals, and shared or unique positions. It also distinguishes itself from GetFundProfile for NPORT portfolios, making it clear what the tool is not for.

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 explicitly says to use SearchInstitutions for resolving filer names and to use GetFundProfile for mutual-fund or ETF NPORT portfolios instead. This gives clear routing guidance and tells the agent when this tool is appropriate versus when an alternative should be chosen.

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=false and destructiveHint=false, so the mutation and safety profile is already known. The description adds genuinely new behavior: names are unique per account, duplicate names are rejected rather than merged, and totals are reported in the portfolio currency while holdings remain in their listing currency. It stops short of describing failure modes or response shape.

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 core action and workflow next step. The closing currency sentence overlaps somewhat with the schema's own parameter description, so it is slightly less efficient than it could be, but nothing is padding.

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 only two parameters, full schema coverage, and no output schema, the description supplies everything an agent needs to decide and call correctly: purpose, workflow handoff, confirmation requirement, and uniqueness constraint. Only the response/error behavior 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 schema already documents both name and currency, including the ISO-code list and default. The description's currency sentence largely restates the reporting semantics that the schema parameter description already carries, 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 verb and resource ('Create a new, empty portfolio') and scopes it to the user's own account, which cleanly separates it from siblings like GetMyPortfolio and DeleteMyPortfolio. It also names the follow-up tool AddPortfolioLot, so the agent understands its place in a workflow.

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 what to do next ('add holdings to it with AddPortfolioLot') and adds an operational guardrail ('Ask the user before creating one, since it is their account'). That is a clear when-to-use plus a precondition, which is more than most definitions provide.

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 description goes beyond the destructiveHint=true annotation by detailing exactly what is destroyed: 'every lot in it, open and closed', and what is lost: 'recorded cost basis and realized-profit history'. It emphasizes irreversibility. No contradiction 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, each substantive. First sentence states action and scope, second explains consequences and irreversibility, third provides safety guidance. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only one parameter, no output schema, and annotations are present, the description fully covers purpose, usage guidelines, behavioral transparency, and parameter context. The agent can confidently select and invoke this tool correctly after reading the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'name' has 100% schema description coverage, stating it requires 'The exact name of the portfolio to delete'. The description adds only contextual emphasis (confirming the name) but no new semantic details beyond the schema. 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 clearly states the verb 'permanently delete one of the USER's own portfolios and every lot in it', specifying the resource (portfolio) and scope (including lots). It distinguishes this tool from sibling tools like RemovePortfolioLot or AddPortfolioLot by mentioning deletion of the entire portfolio.

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 explicitly instructs the agent to 'ALWAYS confirm with the user first, naming the portfolio and how many lots it holds' and to call GetMyPortfolio if the number of lots is unknown. This provides clear contextual guidance on when and how to use the tool safely.

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 the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial behavior beyond that: holders are matched by CIK and SEC reporting links never by name, shares are restated onto today's split basis, change is versus the same holder's previous filing in the same source, % Out is of shares outstanding, and funds are never summed because their shares sit inside adviser 13F reports. These are non-obvious correctness rules an agent could not infer.

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 purpose and dense with substance; almost every clause carries a rule or a distinction. There is mild duplication with the schema on view/source definitions and the prose runs long as a single block, but it is 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 six parameters over a complex ownership domain, the description still conveys the shape of the result (one row per holder, nested filings, restated shares, change basis, % Out), the view/source modes, and the routing to GetOwnershipSummary for totals. 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 coverage is 100%, so the baseline is 3, but the description adds real semantics on top of the schema text — how the default view nests other filings and contained 13D/G, insider and fund disclosures, that view=all includes stale rows, and that view=ultimate lists each parent's members with the linking evidence. It does not add anything for offset/maxResults 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?

States a specific verb and resource and enumerates exactly what 'holders' means (13F institutions, 13D/G filers, Forms 3/4/5 insiders, N-PORT funds), which is far more precise than the title alone. It only partially disambiguates from the crowded sibling set — GetOwnershipSummary is named, but GetTopHolders, GetHolderMix, GetBeneficialOwnership and GetFundsHoldingStock are not addressed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for use and one explicit alternative ('Use GetOwnershipSummary for the totals'), plus in-line guidance on which view/source to pick. It stops short of stating when-not-to-use this versus the other holder-oriented siblings.

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 readOnly/destructive/openWorld annotations by disclosing provenance behavior (prefers IR consensus, falls back to compiled, and states which kind answered each time), that coverage varies by issuer, that output carries units/accounting basis/statistical labels, and that it reads stored verified data and never scrapes on demand.

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 earning its place, with the core read purpose front-loaded and provenance/return caveats following. Slightly dense but no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description helpfully characterizes the return shape (units, accounting basis, mean/median/range/count labels, snapshot history, publication dates) and the coverage caveat. Only the absence of alternative-tool guidance keeps it from full 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 description coverage is 100%, so the schema already documents all nine parameters, including asOf, snapshotId, and the snapshot/metric/period/dimension labels. The description adds no syntax or defaults beyond 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 ('Read') and resource ('analyst consensus forecasts for a company') with the exact metric families covered (revenue, EPS, product, segment, operating). This clearly distinguishes it from estimation-adjacent siblings like GetGuidance, GetValuationMultiples, and GetCompanyKpis.

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 the internal preference logic (IR-published consensus over a compiled fallback), which implies when it's useful, but it gives no explicit when-to-use/when-not or comparison against competing siblings such as GetGuidance or GetFinancialFact. Usage is implied rather than routed.

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 annotation openWorldHint=false implies the tool returns complete results, while the description explicitly states that only the last ~13 months of filings are scanned and an empty result is not proof of absence. This is a direct contradiction, so per rubric transparency is 1. Despite extensive additional detail about normalization and estimation, the contradiction makes the description unreliable.

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 long but every sentence adds value: return field list, normalization caveat, source/coverage limitation, and estimation disclaimer. It's front-loaded with the core purpose and logically structured, with no wasted words.

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 complex financial data tool with no output schema and minimal parameter schema, the description is exceptionally complete. It lists all output components, explains the source filings (10-K, 10-Q, 8-K), the time-window limitation, and the confidence level. The only minor gap is explicit response format, but it's not necessary given the field enumeration.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, ticker, is fully described in the schema with examples and 100% coverage. The description doesn't add parameter-level detail, but none is needed for this self-evident parameter. 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 clearly states 'Get a company's at-the-market (ATM) equity offering programs' and enumerates specific returned fields (agreement date, capacity, sales, availability, status, source filings). This is a specific verb+resource statement that distinguishes it from sibling tools like GetBuybackPrograms by focusing on ATM offerings.

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 clear usage context, explaining the 13-month filing scan window and warning that an empty result does not prove the company runs no ATM program. It also explains the data source and XBRL limitation, helping an agent interpret results appropriately. However, it doesn't explicitly name alternative tools or state when-not-to-use, but the caveats are sufficient.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: results are denominated in the listing's quote unit, and smoothing is warmed up on pre-startDate history so values are independent of the requested range's left edge.

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 definition, then interpretation, then units, then a subtle warm-up caveat. Dense but each sentence earns its place; the parenthetical formula is slightly verbose for a definition field but still 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?

For a single-indicator read tool with a fully-documented schema and no output schema, the description covers computation, interpretation, unit denomination, and warm-up semantics. It omits what the returned records look like (a date-ordered ATR series) and pagination/range limits, but those are largely implied by maxResults and the date params.

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 formats, date defaults, period, and maxResults ordering. The description's warm-up note implicitly clarifies startDate behavior, but adds no new parameter-level syntax 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?

States a specific verb+resource (ATR computation for a stock), gives the underlying formula and Wilder smoothing, and is clearly distinguishable from sibling technical-indicator tools like GetBollingerBands and GetStochasticOscillator.

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 supplies implied usage context ('commonly used for position sizing and stop placement'), which helps an agent decide relevance, but it never states when to prefer this over siblings or what conditions select it. No explicit alternatives or exclusions.

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, openWorldHint=false, destructiveHint=false, so safety is covered. The description adds real behavioral value beyond that: shares are restated onto today's split basis, the change is computed against the filer's previous 13D/13G, results are ordered largest block first, and reporting persons on one filing must not be summed. Pagination behavior for offset/maxResults is left to 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?

The purpose is front-loaded in the opening clause and the trailing sentences carry high-value caveats rather than filler. The field enumeration is dense but every clause names a returned attribute, so little could be cut without losing 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?

There is no output schema, so the description correctly carries the return-value burden and does so thoroughly – listing the per-filer fields and the cover-page reporting-person fields. The only gaps are pagination/result-count behavior, which the schema already covers, and no explicit note on empty results when a ticker has no 13D/13G filings.

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% – ticker, offset, and maxResults are each documented in the schema, including the 1-500 clamp and default. The description adds no parameter syntax, format, or edge-case meaning beyond what the schema already provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource (Schedule 13D/13G beneficial-ownership records for a stock or ETF listing) and enumerates the exact payload: filer, event date, split-adjusted block, percent of class, change since prior filing, and cover-page reporting persons. This clearly separates it from sibling 13F/insider tools such as GetInsiderOwnership, GetInstitutionalOwnershipHistory, and GetTopHolders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: an agent can infer you call it with a ticker to see 13D/13G filers, and the 'never add them together' rule is genuinely useful interpretation guidance. However, no sibling alternative is named and no when-not condition is given, so the agent must still decide on its own between this and the various other ownership 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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds genuinely useful behavior: the warm-up on price history fetched before startDate means values are stable regardless of the requested range's left edge, plus the exact output columns (%B, bandwidth). That is real 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?

Reasonably front-loaded, but a full sentence is spent on general indicator education (bands widen when volatility rises, touching bands is an overbought/oversold cue) that does not help an agent select or call the tool. The warm-up note is the only sentence that clearly earns its place.

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 compensates by naming the returned columns (%B, bandwidth, bands). All six parameters are documented in the schema, and the warm-up caveat removes a subtle correctness pitfall. Only the absence of routing guidance against siblings keeps it from a 5.

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 period, stdDev, ticker, dates and maxResults, making 3 the baseline. The description clarifies the derived columns and the date-warmup semantics, but adds nothing about period/stdDev syntax or date formatting beyond what the schema 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 resource (Bollinger Bands for a stock) and even defines the computation (SMA of close plus upper/lower bands at N standard deviations). An agent knows exactly what it gets. However, it never distinguishes itself from the sibling technical indicators (GetAverageTrueRange, GetStochasticOscillator, GetOnBalanceVolume), so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the indicator means but never says when to reach for it versus the other technical-indicator siblings or GetStockPrices. The overbought/oversold remark is interpretive background, not routing guidance, and there are no prerequisites or exclusions 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 and destructiveHint=false, and the description aligns with these. It adds valuable context beyond the annotations: data sources (XBRL facts + verified filing extractions), the 'nothing is estimated' guarantee, and explicit staleness labeling for non-restated figures.

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 are used, and each earns its place: the first enumerates outputs, the second explains data provenance and staleness, and the third names the alternative tool. It is somewhat dense, but appropriately so for a complex data retrieval 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?

Even without an output schema, the description thoroughly covers what the agent will receive: program details, authorization figures, history fields (cash spent, shares, average price), and data provenance. The staleness label and explicit sibling reference complete the picture for a single-ticker read-only 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?

There is only one parameter, ticker, and the input schema already describes it clearly ('Stock ticker symbol (e.g., AAPL, MSFT)'), giving 100% schema coverage. The description does not add specific parameter-level semantics, but none are needed given the schema's completeness.

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 uses a specific verb ('Get') and clearly identifies the resource: a company's share-repurchase picture, including tracked programs, authorization figures, and repurchase history. It explicitly differentiates from the sibling GetAtmPrograms by naming the at-the-market mirror image.

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 final sentence explicitly directs the agent to GetAtmPrograms when ATM equity offerings are the focus, providing a clear alternative. It also gives context that figures come from XBRL facts and document extractions, helping the agent judge when this tool is appropriate.

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 read-only and non-destructive behavior. The description adds valuable context about the data source (legacy futures-only COT report), the reporting schedule (as of Tuesday, published Friday), and that values are contract counts, enhancing expectations 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?

The description is concise, three sentences, with the purpose front-loaded in the first sentence. Every sentence adds value—purpose, data characteristics, and a pointer to a related tool—with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description conveys the essential output characteristics (positions over time, contract counts, futures-only report). It could more explicitly describe the response format or number of reports returned, but the provided context is largely sufficient for a capable agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema descriptions cover all four parameters with 100% coverage, so the description adds little beyond the structured data. It does suggest using SearchCftcMarkets to obtain marketCode values, which is a minor useful hint, but this aligns with the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves COT positioning data for a specific futures contract and explains it shows commercial and non-commercial positions over time. It does not explicitly differentiate from the sibling GetLatestCftcData, but the purpose is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context for when to use this tool (historical COT positions for a specific contract) and explicitly directs users to SearchCftcMarkets for finding market codes. No exclusions are stated, but the intended use case is evident.

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 and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail: values retain the company's stated scale, GAAP-to-non-GAAP reconciliation includes its stated bridge, and transcripts are not sources. These details explain what the tool does and does not return beyond the schema, enriching the agent's mental model without contradicting 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?

The description is dense but efficient, with every sentence earning its place. It front-loads the core purpose, then details the parameter-dependent output, and ends with two important constraints (transcripts not sources, reconciliation bridge). There is zero fluff, and the structure leads with the most critical information for an agent deciding whether to use the 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?

The tool has no output schema, so the description must explain the return format. It does: 'period, filing date, source quote and exactly comparable year-over-year change.' It also specifies the scale handling and reconciliation behavior. While it doesn't mention pagination or limits, the tool is a read-only lookup with only two parameters and the description covers the essential facets an agent needs to invoke 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% and the schema already describes the parameters, but the description goes further. It explains the metric parameter's behavior in detail: matching case-insensitively, listing candidates when multiple metrics match, and omitting for the latest reading. It also clarifies that values retain the company's stated scale, which is a semantic nuance not fully captured by the schema. This adds significant meaning 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?

The description states a specific verb ('Get'), a precise resource ('company-stated operational and non-GAAP KPIs extracted from written 8-K earnings releases and 10-K/10-Q MD&A'), and details the output fields (period, filing date, source quote, YoY change). It also distinguishes itself from related tools by explicitly limiting sources to written filings, not transcripts or other data types, so an agent can separate it from siblings like GetEarningsCallTranscript or GetNonGaapBridge.

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 context about when to use the tool (to get company-stated KPIs from written filings) and an explicit exclusion: 'Earnings-call transcripts are not figure sources.' It provides a 'when-not' but does not name specific alternative tools for transcript-based data, so it stops short of a full 5. The parameter usage guidance (omit metric for latest reading, pass metric for history) also informs when to call with or without the metric.

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 the tool as read-only, and the description adds several useful behavioral details: results are newest first, the default lookback is one year, transaction amounts are disclosed ranges rather than exact values, and Asset refers to the filed instrument type. These are exactly the kind of behavioral nuances that prevent misinterpretation beyond what annotations 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?

Three sentences, no filler, with the core action and defaults front-loaded before the alternative routing. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema, the description compensates well by describing what the response contains: members of Congress, transaction and filing dates, amount ranges, and the Asset field. Combined with thorough parameter schemas and a clear sibling pointer, nothing essential is missing for correct invocation and interpretation.

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 because the schema already documents all parameters clearly. The description adds little beyond what the schema states; it echoes 'specific ticker' and 'last year by default' but does not materially enhance understanding of offset, maxResults, or transactionType.

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: getting congressional securities transactions for a specific ticker. It also clearly differentiates from the sibling GetMemberTrades by scoping this tool to one ticker, so an agent can select it without inspecting 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 description explicitly names GetMemberTrades as the alternative for one member's transactions across all tickers, giving a clear routing condition. This tells the agent when to use this tool versus that sibling, which is strong usage 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?

Beyond the readOnlyHint annotation, the description discloses critical behavioral details: the correlation is computed on log returns, not raw price levels, dividends are excluded, only overlapping trading days are used, and candidates must meet a $100M market cap and sufficient overlapping days. It also notes that each row reports the observation count, adding transparency about data quality without contradicting 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?

The description is a single dense paragraph that front-loads the main action and method, then efficiently covers scope options, direction, filters, output details, and alternatives. Every sentence adds value, with no redundancy or filler, making it highly information-dense yet concise.

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 the absence of an output schema, the description is nearly complete: it explains the computation method, candidate selection criteria, output semantics (each row reports observation count), and provides explicit cross-references to related tools. It gives users a thorough understanding of what to expect and when to use it, with no significant gaps for a read-only data retrieval 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?

With 100% schema coverage, the schema already documents parameter basics. The description adds meaningful context for scope (e.g., 'Industry ranks the subject's direct industry peers; Market surfaces cross-industry relationships') and direction (negative for hedge candidates), which goes beyond the schema's brief descriptions. However, it does not add much for days or maxResults, which are adequately covered by the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: finding stocks whose daily price returns are most or least correlated with a given stock. It specifies the statistical method (Pearson correlation of daily log returns) and distinguishes itself from sibling tools by emphasizing correlation rather than price or fundamentals.

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 explicitly instructs when to use this tool versus alternatives: 'Use GetStockPrices for the underlying series and the screener for fundamentals-based peer sets.' It also explains the scope choices (Industry, Sector, Market) and when negative correlation is useful for hedging, providing clear context for tool selection.

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 description discloses key behavioral traits beyond the annotations: it explains the two data sources (XBRL-tagged vs narrative extraction with verbatim quotes), clarifies that a 'miss is never a statement of no risk,' and describes the trend functionality with maxFilings. This adds significant context that is not captured in the readOnlyHint or destructiveHint 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?

The description is concise at roughly 4 sentences, with no filler. It is front-loaded with the core purpose, then efficiently covers data sources, interpretation of results, and parameter guidance. Each sentence serves a distinct purpose without redundancy.

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 provides a comprehensive picture of what the tool returns: example of the disclosure, fields included (basis, customer count, percentage, period, source filing), and the difference between XBRL and narrative extraction. It also notes the important caveat about misses and the trend option. This is sufficient for an agent to understand and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters have descriptions in the schema (100% coverage). The description adds value by explaining the use case for maxFilings (>1 shows concentration trend), which goes beyond the schema's description of 'how many of the newest disclosing filings to return.' This extra context helps the agent decide when to adjust the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a company's customer-concentration risk disclosure, specifying the types of data returned (percentage, basis, customer count, period, source filing). It distinguishes from siblings like GetFinancialFact by focusing on this specific risk and mentioning examples (NVDA, AAPL) and the use of XBRL vs narrative extraction.

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 clear context for when to use the tool (to get customer concentration risk) and gives explicit guidance on the maxFilings parameter ('Pass maxFilings > 1 to also see earlier filings' disclosures'). However, it does not explicitly mention when not to use this tool or suggest alternative tools for related queries, such as GetFinancialFact for general financial data.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses the shape of the payload (balances, covenant bullets, exact quotes, SEC documents) and that history, covenants, and documents page independently, which tells the agent the response is multi-section and paginated.

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, no filler. The identity/return summary is front-loaded, the paging caveat follows, and the prerequisite is stated last as an actionable next step. Every sentence carries distinct 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?

For a 10-parameter read tool with no output schema, the description supplies the missing pieces: what the response contains, that it is three independently paged sections, and how to obtain the required identifier. There is no output schema, so enumerating return content is the correct use of the description.

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 a baseline of 3 would be warranted on its own. The description earns above baseline by clarifying that the three collections are paged independently, which explains why there are separate offset/max pairs for history, covenants, and documents rather than a single paging control.

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 one durable debt instrument by its Equibles identifier') and enumerates the returned content. It clearly distinguishes itself from the sibling GetDebtProfile by positioning that tool as the identifier source rather than a substitute.

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 prerequisite flow ('Use GetDebtProfile first to obtain the instrument identifier' and that the id is 'returned by GetDebtProfile'), which is exactly the routing an agent needs. It stops short of stating when-not to use it or what to do if the identifier is unknown, so it is strong but not 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the annual-report baseline, that interim reports update durable instrument records rather than duplicating, and that unmatched observations are disclosed but excluded. It stops short of describing pagination/return-size behavior, so a 4 rather than 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?

Three sentences, front-loaded with purpose, then data-update semantics, then sibling routing. Dense but every clause earns its place; minor density in the middle sentence keeps it from 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?

No output schema exists, but the description summarizes the return shape ('Results summarize each instrument and provide its ID'). Combined with full schema coverage and annotations covering safety, the definition is nearly complete; only explicit paging/evidence-reading guidance 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 all seven paging/evidence parameters are already documented in the schema. The description adds no parameter-level syntax or format detail; the baseline 3 applies 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 and resource ('Get a company's source-linked reported debt balances, total debt history, and identified notes, loans, and revolving credit facilities') and explicitly distinguishes itself from the sibling GetDebtInstrument. An agent can tell what this tool 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?

Names the alternative tool and the exact condition for using it: 'use GetDebtInstrument for paged covenants, filing observations, exact evidence, and governing SEC exhibits.' This is explicit when-to-use routing, not 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 and destructiveHint=false, so safety is covered. The description adds substantial behavioral context beyond that: currency handling per exchange, that date filters bind to the ex-dividend date, that future ex-dates may appear post-declaration, and the non-inheritance rule across share classes and fund series. This is genuinely useful value, though it omits pagination/return-format notes.

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 action, then the return format, then the semantics and edge cases. Sentences are dense but each carries distinct information; the listing-isolation rule is verbose but earns its place by preventing a common misinterpretation.

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 does so (ex-div date + cash amount per share, ordering, currency). Safety is covered by annotations. Only minor gaps remain around pagination behavior, which offset/maxResults in the schema partially address.

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. The description goes further by explaining that startDate/endDate filter on the ex-dividend date specifically and how the ticker format (MIC:TICKER) works, adding meaning beyond the schema's field 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?

States a specific verb and resource: 'Get the stored declared cash dividends of an exact stock or ETF listing, newest first.' The scope (declared cash dividends, exact listing, newest-first ordering) is precise enough that an agent can distinguish it from siblings like GetStockPrices or GetFundProfile 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 clarifies scope and edge cases (per-listing isolation, future ex-dates) but never explicitly says when to choose this tool over a sibling or names an alternative. Usage is implied rather than stated.

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

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

Well beyond the annotations, the description discloses provenance and caveats an agent must know: the brief is verifier-approved, the narrative shift is NOT separately verifier-approved, guidance is company guidance rather than analyst consensus, and comparisons use filed GAAP XBRL facts and never estimates. It also warns that quarters can be missing from the sequence when no approved brief exists.

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, then caveats. Each sentence carries distinct information (content, guidance behavior, provenance limits), though the single dense paragraph packs a lot and could be split for scanability.

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 four parameters, the description fully covers what is returned, the trust level of each component, the comparison methodology, and the sparse-data caveat. An agent has everything needed to call it correctly and interpret the result.

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 already 100%, so the baseline is 3, but the description adds real meaning: 'Newest quarter first' corroborates ordering intent behind limit, and 'quarters can be missing from the sequence' explains why fiscalYear/fiscalQuarter filtering may return gaps. It adds context without restating field syntax.

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 verb and resource ('Get the AI Earnings Brief for a company's recent earnings calls') and enumerates the exact payload — verifier-approved TL;DR, bullish/bearish points, verbatim quotes and a derived narrative shift. That content profile makes it distinguishable from near-siblings like GetEarningsCallTranscript, GetEarningsCallToneAndThemes and GetGuidance without needing to name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: 'Only calls with an approved brief appear' and 'Newest quarter first' hint at when results will be sparse, but it never says when to prefer this over GetEarningsCallTranscript, GetEarningsCallToneAndThemes or GetGuidance. No explicit when/when-not or alternative routing 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 already establish the safe read-only, closed-world profile, so the description's job is to add context beyond that, and it does: it enumerates the artefact status vocabulary (available, pending, notPublished, failed, notAttempted, noCallHeld) with reasons and capture times. It doesn't discuss pagination, auth requirements, or rate limits, but for a read tool that is a minor omission.

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 return contents, then usage notes; no filler sentences. The return-value enumeration is dense but earns its place because there is no output schema, and it is organized rather than rambling.

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 itself and does so thoroughly, covering identifiers, dates, statuses, document ids, and guidance rows. Combined with the parameter rules and the cross-reference to GetEarningsCallTranscript, 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% and the schema already explains ticker format, the year/quarter combination rules, and the omit-both-for-latest behavior. The description's 'Omit the fiscal period for the latest call' largely restates the schema, adding little new parameter meaning, 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 verb and resource ('Get the earnings-call event for a company's fiscal quarter') and immediately clarifies what the record is: one grouping of audio, transcript, slide deck and 8-K. It names the sibling it is not (GetEarningsCallTranscript), so an agent can separate it from the other GetEarningsCall* tools 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 concrete operating guidance ('Omit the fiscal period for the latest call') and routes the agent to the correct follow-up tool for transcripts. It stops short of stating explicit when-not-to-use conditions versus the other earnings-call siblings (Questions, Tone and Themes, Theme History), but the 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 already declare readOnlyHint/openWorldHint=false/destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: analyst names appear only for trusted identity resolutions, and audio offsets exist only for audio-transcribed calls. It omits pagination/volume behavior for a potentially long Q&A list.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the tool's purpose and a compact enumeration of returned fields, then the invocation modes. Dense but every clause carries information; only minor trimming is possible.

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 by naming the fields (analyst, firm, question text, answerer, turn range, audio offsets) plus two caveats and the sibling interlock. It lacks any note on result volume or limits, which is the remaining 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 the schema already documents ticker, eventId, fiscalYear and fiscalQuarter including their mutual-exclusion rules. The closing sentence restates the same ticker-or-eventId choice without adding syntax or format detail beyond the schema, which is the expected baseline at full coverage.

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 opens with a specific verb+resource ("Get the analyst questions asked in a call's Q&A") and narrows scope with granularity ("one entry per analyst turn at the microphone, follow-ups included"), which is exactly what separates it from GetEarningsCallTranscript. An agent can distinguish it from its transcript and tone siblings 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?

It gives the two input modes (ticker with optional fiscal period, or eventId) and explains how the returned turn range interlocks with GetEarningsCallTranscript/GetInvestorEventTranscript for reading the full exchange. It does not state when to prefer this over GetEarningsCallToneAndThemes or GetEarningsBrief, so it stops short of full when/when-not coverage.

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 a safe read (readOnlyHint, destructiveHint=false), and the description adds genuinely useful behavior: the 'Verifier-approved reads only' coverage constraint, how themes are paired across calls (name or shared keywords), and the four-way status semantics including the 'unknown' case when an unscored quarter intervenes. This is behavioral detail well 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?

Dense but front-loaded: the table shape is described first, then pairing logic and status, then the sibling pointer. Every clause carries information, though the single long sentence plus fragment is on the heavy side.

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 multi-quarter comparison tool with no output schema, the description covers the return structure (mention counts, tone, per-theme latest status), the ordering, the pairing mechanism, and the data-quality constraint. Nothing essential to correct invocation or interpretation 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 schema already documents ticker and the calls count with its default and clamping. The description's phrasing about 'last scored calls' and 'oldest first' gives slight alignment but adds no format or syntax 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 (track themes quarter over quarter) and precisely describes the output shape (fiscal-quarter table of mention counts and tone, oldest first, with latest status). It explicitly distinguishes itself from the sibling GetEarningsCallToneAndThemes, which covers a single call, 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?

The contrast with GetEarningsCallToneAndThemes ('gives one call's scores and keywords') implicitly tells the agent when to pick this multi-quarter tool instead. There is clear context, but no explicit when-not conditions or prerequisite statement beyond the 'Verifier-approved reads only' note.

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 a safe read-only, closed-world operation, so the bar is low, and the description clears it by disclosing non-obvious behavior: only verifier-approved scored calls appear, so quarters can be missing and a gap note flags non-consecutive quarters, and results are ordered newest-first. It does not cover latency, coverage limits, or score ranges, 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?

One dense paragraph that front-loads the payoff (what you get) before the availability caveat and the use case. Every clause carries information, though the return-value inventory and the caveat could be tightened slightly.

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 the work of naming the returned fields (tone score, hedging score, themes with mention counts and per-theme tone) and the newest-first ordering. Missing only the semantics of the scores themselves (scale/units), a modest gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents ticker, fiscalYear, fiscalQuarter, and the limit clamp. The description only echoes 'recent'/'newest call first' and adds no 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 and resource — AI-scored tone and themes for a company's earnings calls — and enumerates the concrete outputs (net tone score, hedging score, themes with mention counts and per-theme tone). This content profile cleanly separates it from nearby siblings like GetEarningsCallTranscript and GetEarningsCallEvent, which return raw material rather than scored insights.

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 a clear when-to-use: 'gauge how confident or guarded management sounded and what they talked about most.' It does not name alternatives or state exclusions (e.g., that raw quotes live in GetEarningsCallTranscript), so an agent must infer the boundaries from context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds genuinely non-obvious behavior: identity resolution rules (trusted resolutions show real names; unverified voices degrade to a role label or neutral speaker number) and speaker-turn ordering. It omits any statement about pagination ceiling behavior on longer calls.

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 what the tool returns and followed by the attribution caveat and the prerequisite. Dense but every sentence carries information; no padding.

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 properly explains what the return content looks like (ordered speaker turns with attribution). For a 5-parameter read tool with full schema coverage and safe annotations, this is close to complete, only missing explicit guidance on long-call pagination.

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 format, limit clamping, offset paging, and the fiscal-year/quarter omission semantics. The description adds no parameter detail beyond what the schema provides, 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 verb and resource ('speaker-labelled transcript of a company's earnings call for a fiscal quarter') with added scope detail about ordering and attribution. This clearly distinguishes it from GetEarningsCallEvent, GetEarningsCallToneAndThemes, and GetInvestorEventTranscript.

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: 'Use GetEarningsCallEvent first to check a transcript exists.' That is a real prerequisite, not implied. It does not, however, state when to prefer this over GetInvestorEventTranscript, so it stops short of full alternative coverage.

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=true annotation, the description adds rich behavioral context: it defines the importance tiers (High/Medium/Low) with specific examples, explains why FOMC meetings are excluded, and notes the default date range (next 30 days). These details help the agent understand the tool's limits and output semantics without needing to invoke it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a dense single paragraph but logically structured: it starts with the main purpose, then defines tiers, mentions exclusions, defaults, and usage tips. Every sentence adds value, but the density makes it slightly less scannable than bulleted sections; still, it is concise and well-organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema, the description carries the burden of explaining behavior. It covers data coverage, tier filtering, exclusions, defaults, and related tools, which is sufficient for correct invocation. It doesn't describe the exact return format (e.g., array of objects with fields), but the calendar concept is straightforward enough that 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% for all four parameters, so the baseline is 3. However, the description adds meaningful semantics: it defines the minImportance tier values (low/medium/high) and explains the default date behavior ('Defaults to the next 30 days'), clarifying startDate/endDate usage. It doesn't add much for maxResults beyond the schema's 'chronological' note.

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 opens with 'Get the economic release calendar — scheduled (upcoming) and recent publication dates of US macro data releases', which clearly states the verb, resource, and scope. It distinguishes itself from sibling tools by specifying US macro data and explicitly excluding FOMC meetings, setting it apart from GetMarketCalendar and GetEconomicIndicator.

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 alternatives: 'FOMC meetings are NOT included ... use the Federal Reserve's published meeting calendar for those' and 'use GetEconomicIndicator to fetch a series' data after it prints.' It also gives usage advice with 'Use minImportance=high to see only the market movers' and states defaults, making when-to-use 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds useful behavioral context by emphasizing the tool only covers a curated set (not all of FRED) and returns historical observations. 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?

The description is three sentences and front-loaded with the primary purpose. Each sentence adds essential information: what it does, examples, and scope limitation with a pointer to SearchEconomicIndicators. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters, no output schema, and annotations, the description provides key context: historical observations, a curated series set, and where to search for more. However, it does not describe the return format or observation frequency, which would be helpful since there is no output 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?

The input schema already documents all parameters with 100% coverage, so baseline is 3. The description adds value by listing concrete example series IDs (FEDFUNDS, CPIAUCSL, UNRATE, etc.) and noting that seriesId accepts standard indicator names in addition to FRED IDs, enriching the schema's description.

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 uses a specific verb ('Get time series data') and identifies the unique resource (FRED economic indicators). It clearly distinguishes itself from siblings by noting this covers only a curated ~40-series set, not the full FRED catalog.

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 context on when to use this tool: for historical time series of specific FRED indicators. It explicitly names SearchEconomicIndicators as the alternative to discover available series, and clarifies the curated scope, helping the agent choose correctly.

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 cover read-only and non-destructive behavior. The description adds useful behavioral context: data coverage nuances (full/partial/unknown when counts are missing) and the ordering convention. It does not describe potential errors or return format, but with annotations in place, this is a strong addition.

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 convey the core function, a data-quality caveat, and pagination guidance. Each sentence adds distinct information without redundancy. It is front-loaded with the main purpose, making it easy to parse quickly.

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 query tool with pagination, the description covers the essential aspects: source (NPORT-P), ordering, coverage, and how to paginate. The lack of an output schema is mitigated by the fact that the tool's purpose is straightforward. A mention of return structure would be nice, but it is not critical given the simplicity.

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 three parameters (ticker, offset, maxResults) are already documented. The description adds a note about offset for 'broad portfolios', but this largely mirrors the schema's 'Number of ranked holdings to skip'. Thus the description provides minimal extra value beyond the schema, warranting the baseline score 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 uses a specific verb ('Get') with a clear resource ('an ETF's stored portfolio holdings') and specifies the data source ('latest SEC Form NPORT-P report') and ordering ('largest position first'). This distinguishes it from sibling tools like GetEtfProfile (profile data) and GetTopHolders (likely stock-focused), even without naming them.

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 context about data coverage ('full, partial, or unknown') and pagination ('Use offset to continue through broad portfolios') but does not explicitly state when to use this tool versus alternatives. It neither names sibling tools nor provides exclusion criteria, leaving the selection logic to the agent's 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 readOnly, non-destructive, closed-world, so safety is covered. The description adds value beyond them by naming negative scope ('Issuer-trained short-interest forecasts and squeeze scores are not ETF analytics') and by flagging the sibling-fund caveat for the SEC registrant tools.

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 and every clause is functional, but the middle routing sentence is a long run-on enumerating many siblings that is dense to parse. Efficient overall with no filler, though structure could be tighter.

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-ticker, closed-world read tool with no output schema, the definition covers purpose, scope, sibling routing, and negative boundaries. Nothing 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?

Only one parameter with 100% schema description coverage, so the schema fully documents 'ticker' (including SPY/VOO/IVV examples). The description reinforces 'this same exact ETF ticker' but adds no format or syntax detail beyond the schema, which is the expected baseline 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 and resource ('Get ETF settled performance, SEC assets, allocation and top holdings') and explicitly differentiates from the closest sibling: 'GetEtfHoldings instead returns investments inside the ETF.' An agent can distinguish 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?

Explicitly routes the agent to alternatives by data need (GetStockPrices/GetLatestClosingPrices for prices, GetLiveQuote for intraday, option tools, short interest, 13F exposure, dividends, congressional trades). It also warns which tools return the wrong entity scope (ListFilings/SearchDocuments may include sibling funds).

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 readOnly/openWorld=false/destructive=false, and the description adds substantial context beyond them: coverage is limited to Sweden's register, matching is by LEI or ISIN so rows may include other instruments, only captured publication days exist, and the register is not a complete insider-ownership record. These caveats materially affect how the agent should interpret results.

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 and identifier format are front-loaded, and the routing hint is saved for last, which reads well. It is dense and slightly long, but nearly every clause carries informational weight for interpreting coverage or results.

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?

Although there is no output schema, the description enumerates the returned fields (date, person/role, related person, type, instrument/ISIN, volume, price, currency, source status including amendments) and states the coverage limits. Nothing an agent needs to call or interpret this tool 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 three parameters. The description restates the MIC:TICKER format and the bare-ticker fallback, which mirrors the schema's own ticker description, so it adds little beyond structured data. 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: fetch director/PDMR transactions published by a regulator for one non-US listing, with the exact identifier format (MIC:TICKER). It explicitly distinguishes itself from the US counterpart GetInsiderTransactions, so an agent can route correctly 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 explicit when-to-use context (non-US listing, coverage in Sweden's Finansinspektionen register) and a named alternative for the US case ('For US Form 4 filings use GetInsiderTransactions'). The boundary between the two tools is unambiguous.

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

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

Annotations cover the safety profile (readOnly, non-destructive), but the description adds substantial context beyond them: coverage scope, publication lag, excluded fund types, and the critical caveat that the reported weight is not a share of the company. This prevents misreading of the returned numbers.

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 that are front-loaded with the core action and input format, followed by scope caveats and the sibling pointer. Every sentence carries information, though the block is on the heavier side.

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 row fields (fund, manager, quantity, SEK market value, weight) and defining what each means. 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 coverage is 100%, so the schema already documents offset, maxResults, periodEnd and the ticker format. The description still adds value by clarifying the MIC:TICKER convention and the fallback behavior for a bare ticker, though most of the ticker semantics are also present in 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?

States a specific verb and resource (European fund positions in a given listing) and immediately distinguishes itself from GetFundsHoldingStock for US-registered funds and from SEC-filing data. An agent can identify this tool's domain 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 route ('For US registered funds use GetFundsHoldingStock'), states the required input format MIC:TICKER, and sets expectations about coverage and exclusions (Swedish UCITS only, special funds excluded, ~2-month delay). This is when-to-use and when-not in one place.

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 cover the safety profile (readOnly, non-destructive), and the description adds substantial semantics the annotations cannot: registers are never summed, values are percentage points of issued share capital, these are dated disclosures rather than live positions, and unmatched/stale registers are named at the end. It also pre-empts the 'no row = zero' misreading, which is exactly the kind of trap this tool needs to 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?

A single dense paragraph, but it is front-loaded with the identifier format and scope before moving to caveats, and every clause carries distinct meaning. It is long, though a few clauses (the full register list) could be trimmed without loss.

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 does so: percentage points of issued share capital, one row per register, and unmatched registers named at the end. Nothing needed to call or interpret the tool 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 both parameters are self-documented, so the description's MIC:TICKER examples and bare-ticker fallback largely restate the schema. Baseline 3 is appropriate since 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 and resource ('net short positions disclosed to European regulators') plus a precise scope ('one listing outside the US'). It also explicitly separates itself from the US counterpart 'For US listings use GetShortInterest', 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?

Gives both when-to-use (non-US listing, registers by MIC:TICKER/ISIN/LEI) and when-not ('For US listings use GetShortInterest'), and contrasts against adjacent concepts the agent might otherwise confuse it with: total short interest, current holdings, short 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?

Annotations already establish read-only and non-destructive behavior; the description goes beyond them by disclosing extraction from narrative text, verification before publication, reverse-chronological ordering, and the back-filling coverage caveat with explicit empty-result semantics. This adds real behavioral context without contradicting 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?

Every sentence earns its place: scope, source, return fields, ordering, extraction/verification behavior, and the coverage/empty-result caveat. The most important scoping information is front-loaded before the detailed behaviors.

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 properly enumerates the returned fields: person name, raw and normalized role, action, effective date, verbatim disclosure, and filing source. Combined with full parameter documentation and safety annotations, nothing needed to invoke the 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?

All six parameters are fully documented in the input schema, so the description does not need to add parameter-level meaning. The prose adds useful output and coverage context but does not materially extend the semantics of ticker, date filters, action, offset, or maxResults.

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 precise verb and resource: getting a company's executive and director changes from 8-K Item 5.02 filings. The event types are enumerated, and the source filing basis distinguishes it clearly from siblings such as GetExecutiveCompensation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the use case clear: an agent needing executive/board appointment, resignation, termination, or retirement events from a company's 8-K filings. It does not explicitly name alternative tools or exclusion conditions, but the source-specific scope gives clear selection context.

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

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

Beyond the read-only/destructive annotations, the description adds substantial transparency about data integrity: figures are exactly as disclosed, Total is the filer's own figure (never recomputed), and the tool states the newest proxy on file to surface stale coverage. This goes well 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?

The description is concise but information-dense, with three well-structured sentences. Each sentence adds value: output specification, data integrity caveat, and coverage limitations. No filler or redundancy.

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 explains the return content (salary, bonus, awards, etc., per executive per fiscal year, newest first). It also covers coverage limitations and data quality indicators, making it complete for a data retrieval 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% (ticker and maxYears are both documented). The description adds some context about year ordering and the 'newest year first' behavior, which aligns with maxYears, but it does not significantly enhance the parameter meaning 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?

The description clearly states the tool retrieves named-executive compensation from DEF 14A proxy statements' Summary Compensation Table, listing components and per-executive/per-year granularity. It distinguishes itself from siblings like GetExecutiveChanges, which deals with changes rather than compensation.

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 important usage context by specifying coverage is limited to US DEF 14A filers and noting the data is back-filling, which guides when to use it. It also implies the tool is for compensation data, not other executive-related data, though it does not explicitly name alternative 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?

The annotations already mark this as read-only and non-destructive, and the description adds substantial non-obvious behavior: Quantity is an outstanding balance rather than new fails and must not be summed, Price follows the SEC prior-day close convention, coverage windows explain missing dates, and publication lag means newest rows trail today. This goes well beyond annotation signals.

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 first sentence front-loads the core purpose, and every subsequent sentence adds a distinct, necessary caveat or definition. Though lengthy, it is dense with useful information and contains no filler or redundancy.

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 explaining Quantity, Price, Value, date coverage, missing-date semantics, and data lag. It provides enough interpretive context for an agent to call the tool and correctly understand its 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?

The input schema has 100% description coverage for all four parameters, so the description does not need to restate them. It adds no new input-parameter meaning beyond the schema, and the baseline of 3 applies because the schema handles the 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?

The description states a specific verb and resource: retrieving fails-to-deliver data for an exact listed stock or ETF from the SEC's twice-monthly FTD files. It is clearly distinguishable from related short-selling tools like GetShortInterest or GetShortVolume because it anchors the data source and metric.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the intended use clear: analyzing SEC-reported FTD balances for a single ticker, with coverage and lag caveats. It does not explicitly name alternatives or say when not to use this tool, but the FTD-specific framing leaves little ambiguity about its niche.

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 and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns links to FDA meeting pages, defaults to a 90-day window, and has limited historical coverage starting late 2025. This exceeds the annotation information without contradicting it.

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 compact (three sentences) and front-loaded: the first sentence states the core function, the second clarifies defaults, and the third clarifies limitations and scope. No filler or redundant 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?

For a simple read-only calendar tool with no output schema, the description covers the essentials: what is returned, the source, defaults, coverage limitations, and what it is not. It does not detail the exact output fields, but that is not critical given the simplicity and the provided link. It is complete enough for an agent to decide when and how to call 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?

The schema already fully describes all three parameters with defaults and formats (100% coverage). The description's mention of 'next 90 days' and 'date range' echoes the schema without adding new meaning. Thus the description adds no significant value for parameter understanding, though it is consistent with 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 clearly states the tool's purpose: retrieving scheduled FDA advisory-committee meetings from the FDA.gov calendar, each with a link to its meeting page. It also specifies the scope (forward-looking, not historical) and the coverage start date, which distinguishes it from other calendar tools in the sibling list like GetEconomicCalendar or GetMarketHolidayCalendar.

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 usage context: it is for forward-looking FDA advisory-committee meetings, not a historical archive, and coverage starts in late 2025. It also notes entries are not linked to stock tickers, indicating it is not for market-impact analysis. While it does not name specific sibling tools, it clearly frames when this tool is appropriate and when it is not.

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 this a safe read (readOnlyHint=true, destructiveHint=false) and closed-world, so the description is free to add higher-value behavior: default restated-vs-as-reported semantics, row granularity per period type (flows vs balances), use of the company's own fiscal calendar, and a warning when an alias ends before other structured facts, hinting at an XBRL tag change.

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 action and scope, and every sentence carries distinct information (source, granularity, restatement default, warning, exclusions, alternatives). It is a single dense block rather than scannable segments, which slightly hurts structure but not economy.

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 8-param read tool with no output schema, the description supplies what the schema cannot: the shape of the returned time series, row granularity, default restatement behavior, and the caveat around sparse/truncated series. Combined with full schema coverage and annotations, 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 schema already documents all 8 params and the baseline is 3. The description goes one step further by explaining the observable effect of asOriginallyReported ('latest restated value unless set') and how fiscalPeriod interacts with the filer's fiscal calendar, which is meaning the schema alone doesn't convey.

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 ('Get a single financial concept ... over time for a company') and immediately names the data source (SEC Company Facts XBRL, or non-US issuer filings). It draws a boundary against sibling tools by naming GetFinancialStatement and CompareFinancialFact and by excluding dimensioned disclosures like customer concentration.

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 routing: 'For a full statement use GetFinancialStatement; to compare peers use CompareFinancialFact,' plus a stated out-of-scope case ('Dimensioned disclosures such as customer concentration are outside this consolidated-series tool'). Both when-to-use and when-not-to-use are 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 already establish the safe read profile (readOnlyHint=true, destructiveHint=false), and the description adds substantial context beyond that: data provenance (SEC Company Facts XBRL vs non-US issuer filings), latest-restated selection rule, exact-period-end semantics, discrete-quarter derivation with a 'Derived' marker, and which facts are out of scope.

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 and resource, then layered with provenance, derivation rules, and exclusions. It is a dense paragraph rather than scannable sentences, but each clause carries distinct value (source, return set, quarter derivation, sibling routing) 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?

With no output schema, the description still describes the return set (standard line items such as revenue, net income, total assets, operating cash flow) and the exact-period/latest-restated semantics. Combined with provenance and explicit exclusions, it covers everything an agent needs 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 all four parameters are already documented in the schema, including the 'FY'/'Q1'..'Q4' semantics and default behaviors. The description reinforces rather than extends the parameter details, 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 precise verb ('Get') and resource class ('company's income statement, balance sheet, or cash-flow statement') scoped to fiscal year and period. It explicitly distinguishes itself from siblings by naming GetRevenueBreakdown, GetFinancialFact, and CompareFinancialFact and describing what each covers instead, so an agent can route correctly without opening 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?

Explicit when-not guidance: company-specific dimensional facts are excluded, and the description routes segment/geographic revenue to GetRevenueBreakdown and single-line-item/multi-period or cross-company lookups to GetFinancialFact or CompareFinancialFact. The 'FY for annual figures' hint further guides correct period selection.

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 annotations only declare the tool read-only and non-destructive. The description adds valuable behavioral context: results are sorted with the most recent notices first, a note flags when more results exist than returned, heavy 10b5-1 filers can flood the recency window, and a Form 144 proposal may never execute. These details go well beyond the structured 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?

The description is dense but not padded; every sentence contributes value: purpose, returned fields, sort order, overflow behavior, date-scoping rationale, and legal caveats. It is front-loaded with the core capability and then fills in the nuances an agent would need to interpret results correctly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there is no output schema, the description compensates well by enumerating the key returned fields: seller, relationship, shares, aggregate market value, percent of shares outstanding, approximate sale date, broker, and remarks/10b5-1 plans. It also covers ordering, overflow, date filtering, and the caveat that proposals may never execute. Nothing essential for correct invocation or interpretation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema documents all 5 parameters with descriptions, so the baseline is 3. The description adds extra meaning by explaining why fromDate/toDate matter — heavy 10b5-1 filers can flood the recency window — and noting that an overflow flag appears when more results exist than were returned. This goes slightly beyond the schema's basic 'filter' language.

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 begins with 'Get recent proposed insider sales for a stock from SEC Form 144 notices,' a specific verb and resource. It makes clear these are declarations of intent, not completed trades, which distinguishes it from actual insider transaction tools like GetInsiderTransactions. The subsequent Form 4/5 note further reinforces the precise scope.

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 concrete guidance to use fromDate/toDate to scope the period because heavy 10b5-1 filers can flood the recency window with small notices. It also warns that a proposal may never execute and that completed sales may only show up on Form 4 or 5 when reportable, which helps agents know when not to over-interpret results. However, it does not explicitly name a sibling tool as the alternative for executed sales, so it stops short of a 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 description discloses a critical non-obvious behavior: D/A amendments restate the same offering, and warns the agent to group by first-sale date and offering amount and use only the latest notice to avoid double-counting. This goes well beyond the readOnlyHint/destructiveHint annotations and provides essential operational guidance.

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, then provides a useful field enumeration, then ends with a vital deduplication warning. Each sentence contributes meaning; the second sentence is slightly dense but earned because there is no output schema to document the fields.

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 lookup tool with no output schema, the description is complete: it explains what the data represents, lists the important data points, and warns about the duplicate-amendment trap. The schema covers parameter constraints, and annotations cover safety, so nothing essential is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents ticker, offset, fromDate, toDate, and maxResults. The description does not add parameter-level detail beyond what the schema already provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb ('Get'), a specific resource (SEC Form D notices), and a specific subject (exempt securities offerings / private placements for a company). This clearly distinguishes it from sibling tools like GetForm144ProposedSales and ListFilings, and the final sentence reinforces its intended tracking use case.

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 an explicit use case: 'Use this to track how a company is raising private capital alongside its public filings.' It does not explicitly list alternative tools or exclusion conditions, but the context is clear enough for an agent to select this tool among the many finance-focused siblings.

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 readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: N-CEN is filed at registrant level, ingestion happens through tracked issuer feeds, and a series in an untracked multi-series trust may have no record. It also clarifies the 'operating companies return no data' boundary. No contradiction with annotations, and it enriches beyond the structured hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured paragraph. It leads with the purpose, then details accepted inputs, the data returned, and important caveats about data availability and filing scope. Every sentence adds value without redundancy. It is appropriately sized for the tool's complexity.

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 two parameters and no output schema, the description covers the essential usage context: accepted identifiers, report contents, data availability limitations, and filing eligibility. It does not explicitly describe the return format (e.g., list vs. single record) or pagination behavior for maxResults, but maxResults is self-explanatory and the listed fields imply a structured response. Minor gaps exist but are not critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 100% of parameters with descriptions and examples. The description adds meaning by specifying that identifiers come from SearchFunds and detailing the accepted identifier types (profile id, SEC series id, stored series ticker, verified share-class alias). This goes slightly beyond the schema's generic 'Fund or ETF ticker' and clarifies the data source relationship.

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 operational data for a registered investment company from its SEC Form N-CEN annual reports.' It clearly distinguishes from sibling tools like GetFundProfile by focusing on N-CEN filings, and it enumerates the data fields returned. No ambiguity or tautology.

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 context: it accepts tickers or identifiers from SearchFunds, and notes that only registered funds file N-CEN, with operating companies returning no data. It implies when to use this tool, but does not explicitly name alternative tools or state when not to use it. The guidance is solid but not 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral nuance: it notes that multi-series trusts may store only tracked-stock positions but that reported counts and asset totals still reflect the full filing. This explains potential data quirks without contradicting annotations, adding value beyond the 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?

The description is compact and front-loaded: it states the core purpose first, then details return values, then notes a data quirk, and finally points to the alternative. Every sentence serves a purpose, with no redundancy or 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 fund profile tool with three parameters and no output schema, the description provides a complete picture: what it returns (registrant, series, assets, holding counts, largest positions), the acceptable input formats, the underlying SEC form, and a relevant data caveat. Given the annotations and schema, nothing critical is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter (fund, offset, maxResults) already documented in detail, including examples for the fund identifier. The description adds no meaning beyond the schema; it only repeats the accepted identifier types and mentions pagination control indirectly. Baseline of 3 is appropriate because the schema carries the full semantic load.

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 a registered fund's profile and largest stored holdings from its latest SEC Form NPORT-P report.' It clearly distinguishes from siblings by naming the inverse tool, GetFundsHoldingStock, and specifying the input types accepted. The purpose is unambiguous and distinct.

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 explicitly says 'Use GetFundsHoldingStock for the inverse lookup,' providing a direct when-not condition and naming the alternative. It also implies when to use this tool by describing the return values and the source data, making the decision between this and related fund tools 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 already cover the safety profile (readOnly, non-destructive, non-openWorld), and the description adds substantial behavior: the matching key, the 18-month filing exclusion so exited positions don't appear current, largest-first ordering, and the caveat that report dates differ per series so cross-row totals mix as-of dates.

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 data source are front-loaded, and each subsequent clause earns its place (matching, exclusion, returned fields, date caveat). It is dense and long for a single paragraph, but nothing is redundant or 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, the description carries the return burden and does so: registrant/series, reporting period, position size, dollar value, share of net assets, payoff profile, and ordering. Combined with the as-of-date caveat, an agent has everything needed to interpret 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 schema already documents offset, ticker, maxResults and registrantOrSeries. The description adds only minor value (confirming largest-first ordering and the MIC:TICKER/ISIN matching form), so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — registered investment companies (mutual funds/ETFs) holding an exact stock/ETF listing — with the data source named (SEC Form NPORT-P). This clearly separates it from siblings like GetEtfHoldings (holdings OF a fund) and GetTopHolders (13F institutional holders), so an agent can pick it 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 clear context for when it applies: an exact listed security, matched by authoritative CUSIP/ISIN against each fund series' most recent report. It does not, however, explicitly name alternatives or state exclusions (e.g. use GetTopHolders for 13F institutions), so it stops short of full 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?

The description enriches the annotations substantially by disclosing the extraction methodology (from newest 10-K/10-Q narrative, verified before publication), the semantic of 'no doubt' when language is absent, and the coverage boundary. This goes well beyond the readOnlyHint and destructiveHint 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?

The description is packed into two dense sentences, front-loaded with the main purpose. The first sentence is long but every clause adds value—scope, output, and history. The second sentence clarifies coverage limitations. No wasted words, though slightly complex sentence structure prevents a perfect 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?

Even without an output schema, the description fully explains what the agent will receive: verbatim disclosure, filing identifier, and history of doubt episodes. It also explains methodology and coverage limits, making it complete for a one-parameter read-only 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?

The input schema covers ticker with a clear description (e.g., AAPL, MSFT), and schema coverage is 100%. The description does not add any parameter-specific semantics beyond the tool's overall purpose, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states exactly what the tool does with a specific verb and resource: it retrieves a company's going-concern doubt status from its latest examined SEC filing, including verbatim disclosure, filing source, and history of doubt episodes. This clearly distinguishes it from sibling tools like GetFdaCatalysts or GetEarningsBrief.

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?

While no alternative tools are explicitly named, the narrow purpose makes the intended use obvious. The description adds important context about coverage limitations (examined filings only, with no analysis of earlier periods), which helps an agent know when the data may be incomplete.

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 and destructiveHint=false, and the description adds substantial behavioral context beyond that: data source (USAspending.gov), coverage limitations (only prime awards of $1M+ resolving to a listed company), and the key caveat that reported total value is 'not revenue received.' It also notes that sums understate total federal revenue, which helps agents interpret results correctly. No contradiction with annotations is present.

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 appropriately sized for a tool with 7 parameters, packing source, scope, field semantics, coverage caveats, and an alternative into a compact paragraph. The main action is front-loaded in the first sentence, and later clauses are information-dense rather than padded. A slightly tighter organization could help, but it is not bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the moderate complexity, 7 parameters, and no output schema, the description covers everything an agent needs: what data is returned, source, coverage/exclusions, definition of key values, defaults context, and when to use a sibling tool. Pagination and date defaults are already in the schema, so the description complements rather than duplicates structured info. This is effectively complete for correct invocation and result interpretation.

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; the description adds additional meaning by clarifying that total value is 'obligated dollars plus unexercised ceiling — not revenue received,' which informs how sortBy='amount' and maxResults should be interpreted. It also expands on the meaning of output fields such as outlays and period-of-performance end date, enriching parameter context. The description does not repeat parameter names or formats, keeping value-add high.

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 opens with a specific verb and resource: 'Get federal government contract awards ... won by a specific public company.' It clearly differentiates from the sibling GetTopGovernmentContractors by noting the per-company scope versus market-wide ranking. The title and annotation reinforce the same purpose, and no ambiguity remains about what the 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?

The description states the tool is 'useful for gauging a company's reliance on federal spending' and explicitly directs agents to 'use GetTopGovernmentContractors to rank companies market-wide.' This provides clear when-to-use guidance and names the alternative, so an agent can select between the two without opening schemas.

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 cover the safety profile (read-only, non-destructive, closed-world), so the description carries the rest and does so richly: closed target periods are marked 'ended', revenue/diluted-EPS guidance gets an actual-plus-verdict comparison once comparable XBRL facts exist, non-GAAP is never compared to GAAP actuals, and coverage notes distinguish unprocessed documents from sources with no guidance.

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 action and sources before the comparison/coverage caveats; no filler. It is dense but each clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully characterizes the return shape (ranges, units, basis, fiscal period, provenance, actuals and verdict, coverage notes). It stops short of error or no-coverage edge behavior beyond the coverage-notes hint, but is adequate for a single-parameter read 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 a single fully documented ticker parameter (including the MIC:TICKER non-US form), so the schema does the work. The description adds nothing about the parameter, making the baseline 3 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 company guidance') and pins down the two source types (Item 2.02 earnings releases, earnings-call transcripts) plus the ordering and the returned fields (range, unit, GAAP basis, fiscal period, provenance). This clearly separates it from siblings like GetEarningsBrief, GetEarningsCallTranscript, and GetNonGaapBridge.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for when the tool is the right one: it draws guidance only from earnings releases and call transcripts, newest first. It does not name an alternative tool or state exclusions, so the agent still has to infer routing against GetEarningsBrief/GetNonGaapBridge.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuine methodological context beyond that: data is regulatory and never names holders, the active-holder like-for-like change excludes index-like books, and fund positions are never added to 13F totals, all of which affect interpretation of results.

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 core purpose is front-loaded and every clause carries information, but the prose is dense with run-ons and repeats the dimension list (style, turnover, horizon, etc.) that the schema already enumerates, then returns to fundtype at length. For a three-parameter tool it is longer than 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 and three fully documented parameters, the description is largely self-sufficient: it explains the returned metrics, the split dimensions, and the key accounting caveats for fund positions. Only the absence of cross-tool guidance keeps it from being fully 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, but the description adds real meaning: it expands what each dimension split represents and clarifies the exception for fundtype (Form NPORT-P positions split by N-CEN fund type as a share of shares outstanding, not folded into 13F totals). That nuance goes beyond the enum listing in 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 names a concrete verb and resource ('Who holds a stock or ETF listing, by kind of 13F filer, quarter by quarter') and enumerates the specific outputs: share of 13F common shares, like-for-like change, and new/exited filers. It is clearly distinguishable in substance from siblings like GetTopHolders or GetInstitutionalOwnershipHistory, but it never names an alternative tool, so the differentiation is implicit rather than explicit.

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 phrase 'Who holds a stock or ETF listing' and by the methodological notes, but there is no explicit when-to-use or when-not-to-use guidance, and no sibling such as GetTopHolders, GetAllHolders, or GetHolderTypeFlows is referenced. The agent must infer the appropriate context.

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

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

Annotations already establish the safe read-only, non-open-world profile, so the bar is lower; the description goes well beyond them by disclosing the ranking algorithm, the fallback-to-sector behavior, the fund-returns-nothing case, and the fields each target carries. It stops short of auth or rate-limit context, but for a read-only lookup this is 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?

The purpose is front-loaded in the first sentence, but that sentence is extremely long and heavily nested with parentheticals ('operating companies whose active holders overlap most, funds excluded'), making it dense to parse. Most content earns its place, but the structure could be broken up for scanability.

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 enumerating what each target shows (13F book, peers' share, top peers, style, holder type). Combined with the fallback and fund edge cases, an agent has enough to call and interpret the tool, though the fallback trigger ('no overlap peers') could be defined more concretely.

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 all three parameters (ticker, sort, maxResults) are documented in the schema, including the sort enum values and the 1-500 clamp. The description adds no parameter-level detail beyond that, 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?

The description states a specific resource (13F filers) and a precise selection rule: filers of the newest closed quarter that hold holder-overlap peers but hold no class of the stock itself. This sharply distinguishes it from siblings like GetTopHolders, GetAllHolders, and GetSuperInvestors, which describe current holders rather than non-holding prospects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: the definition makes clear it is a prospecting tool (filers who do NOT yet hold the stock), and it names two edge conditions (no overlap peers falls back to sector holdings; a fund has no targets). But it never explicitly says when to prefer it over GetTopHolders or GetOwnershipSignals, nor does it state prerequisites.

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 readOnly/safe/openWorld=false, so the description's job is marginal. It earns credit for disclosing non-obvious behavior: trades priced at quarter-average prices, filers with no prior-quarter 13F contributing no flow, and the buckets being regulatory records that never name individuals.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the purpose and metrics before the caveats. The second sentence is dense with an eight-item bucket list, but every clause carries information and nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry the return-value burden, and it does describe the measures produced and two important computational caveats. For a four-parameter, fully documented read tool this is largely complete, though bucket-by-sector output shape could be clearer.

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 restates the dimension options and the sector split in prose, adding a little interpretive context (e.g. that bucket implies groupBy=sector) but no syntax or meaning 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?

States a specific verb and resource: market-wide 13F money flows by kind of filer, and enumerates the measures returned (net flow, net flow as % of prior book, net buyers vs sellers). It is clearly a market-aggregate tool rather than an institution-level one, but it never names its nearest siblings (e.g. GetMarketWide13FActivity, GetTopInstitutionalBuyersSellers), so an agent must infer the distinction.

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 when the tool fits (closed-quarter flow analysis, optional sector split) and notes the 'with ETFs apart' handling, but gives no explicit when-not or alternative-tool routing. 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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial behavior beyond that: changes are derived by diffing consecutive constituent lists, dated to reporting windows rather than announcements, and de-duplicated across funds by keeping the narrowest window. It also flags that additions carry an estimate rather than a record of implied fund buying, which is a meaningful caveat not expressed anywhere in 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?

The purpose is front-loaded in the first sentence and each subsequent sentence contributes distinct information (derivation, dating granularity, de-duplication, estimate caveat). The middle de-duplication sentence is fairly sprawling and could be tightened, but nothing is pure 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 does well to imply the shape of a change record (company, direction, window, implied buying in shares and days of volume). It does not spell out the concrete response fields or pagination/truncation behavior for maxResults, which leaves a modest gap for a two-parameter read tool with no output 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 both parameters (index format, maxResults default/max) are already fully documented in the schema. The description adds no format hints, slug conventions, or guidance beyond what is structured. 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?

It states a specific verb and resource ('companies that have joined or left a major US stock index') and adds an ordering guarantee ('newest first'). This clearly distinguishes it from siblings like GetIndexComposition (current membership) or GetIndexForecast, so an agent can route 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?

The description gives strong context on what the data represents and explicitly excludes a competing reading ('This is observed membership, not an announcement feed'), which is effectively a when-not statement. However, it never names an alternative sibling tool for the announcement-style or point-in-time-membership use cases, so routing is left partly 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 mark the tool as read-only and non-destructive, but the description goes far beyond that: it reveals the data provenance (SEC Form N-PORT or daily holdings file), the fact that the fund name and date are returned, that partial filings are never served, and that unmatched rows are preserved under their reported names rather than dropped. These are significant behavioral traits that an agent needs to know and are not present in 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?

The description is long but every clause earns its place: it states the purpose, lists supported indices, explains data source, notes handling of partial filings and unmatched rows, and gives explicit alternatives—all in a logical flow. It is front-loaded with the key action and scope, and there is no redundant or filler wording.

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 tool has only three parameters, no output schema, and no nested objects, yet the description provides a thorough account of the response structure (rank, ticker, share), data provenance, and edge-case behavior (unmatched rows, partial filings). It even covers what the tool does not do via pointers to sibling tools. For a simple read-only list tool, this is complete and exceeds what is needed.

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% for all three parameters (index, offset, maxResults), and the schema already includes defaults and explanations such as 'heaviest first' for maxResults. The description does not add any new information about the parameters themselves; it only describes output structure and behavior, which is not the focus of this dimension. Thus, a baseline score of 3 is appropriate because the schema handles parameter semantics 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?

The description opens with a specific verb and resource: 'Get the current constituent list of a major US stock index' and enumerates seven concrete indices, immediately making the tool's scope clear. It also distinguishes itself from siblings by referencing GetIndexChanges and GetIndexForecast as alternatives for different queries, which prevents confusion.

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 usage guidance is provided: 'Use GetIndexChanges for what has joined or left, and GetIndexForecast for who the published rules point to next.' This tells the agent when not to use this tool and names the alternatives. The description also explains the data source (fund filings) and the guarantee about complete listings, offering clear context for when to rely on 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?

Annotations only establish read-only and non-destructive behavior. The description adds essential behavioral detail: estimates are not guarantees, missing figures produce no entry verdict, unmeasured members are handled differently across indices, and model revisions are immutable with a highest-revision rule. This materially changes how an agent should interpret results.

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 operation and then organized by index family, edge cases, and revision semantics. Although dense, every sentence contributes a distinct and material constraint; there is no 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?

This is a complex endpoint with no output schema, yet the description covers the output form (candidates with evidence, probabilities, departure buckets), index-specific forecast certainty, edge-case behavior, and versioning. That is sufficient for an agent to invoke 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?

The input schema already documents both parameters with 100% coverage, including accepted index forms, the Dow limitation, and maxResults bounds. The description reinforces index-level semantics but does not add new parameter syntax or formatting details, 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?

The first sentence states a specific verb ('Apply'), a resource ('an index's published entry rules'), and a concrete deliverable ('return candidates with rule-by-rule evidence'). It also distinguishes this from sibling tools by framing it clearly as a forecast rather than a historical change report.

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 explicit guidance on when results are SCREENS vs PROJECTIONS and states that the Dow has no forecast, so an agent knows where the tool applies and where it does not. It does not explicitly name alternative sibling tools for actual index changes, which keeps it from a 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description goes well beyond that: it explains the aggregation methodology (direct vs indirect vehicles, derivative exclusion, split-basis restatement), and discloses real caveats — vehicles absent from the newest filing are not counted, and former insiders may linger with stale dates or zero shares. That is exactly the kind of data-quality context an agent needs to interpret results.

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 the sibling routing are front-loaded, and the dense methodology is placed after the headline so an agent can stop reading early. It is somewhat long and the middle clause chains many qualifiers, but nearly every sentence carries information an agent would otherwise have to infer.

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 it does, specifying the ranked ordering, the Direct/Indirect columns, the split-basis restatement, and the row cap tied to maxResults. Combined with the parameter coverage, nothing an agent needs to call or interpret this tool 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%, including detailed pagination semantics for offset and clamping rules for maxResults, so the schema already does the heavy lifting. The description only restates the default of 30, adding no meaning beyond the structured fields. 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 opens with a precise verb+resource ('summary of insider ownership for a stock, ranked by total shares held') and immediately qualifies the scope with the data source (SEC Form 3/4/5 closing balances). It also differentiates from the nearest sibling by naming GetInsiderTransactions for underlying trades, 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?

It gives an explicit use case ('understand the insider ownership structure of a company') and names one alternative (GetInsiderTransactions) with the condition that selects it. It does not, however, disambiguate against other ownership-adjacent siblings such as GetBeneficialOwnership, GetTopHolders or GetAllHolders, so the routing guidance is clear but incomplete.

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 readOnly, non-destructive, and closed-world behavior, but the description adds important methodology: the score components, the 90-day window, the use of qualifying open-market Forms 4/5, the exclusion of mere 10% owners and Rule 10b5-1 trades, and the fact that filters never renumber the universe rank. These are substantive behavioral details 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?

The description is four sentences and front-loads the scoring concept, then methodology, then usage. It is dense but every sentence contributes relevant information, with no obvious 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 still explains what a caller gets (leaderboard ranking, single-ticker factor breakdown and universe rank) and how filters affect results. Combined with full schema coverage and annotations covering safety, the definition is complete enough for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and each parameter is already well documented. The description adds little per-parameter meaning beyond reinforcing filter behavior and noting that filters do not renumber ranks; the baseline of 3 is appropriate when the schema carries the parameter definitions.

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?