equibles

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

Annotations only indicate a non-read, non-destructive operation. The description adds substantial behavior: rejects unknown/expired contracts, requires verified OCC symbols for options, signed quantity semantics, positive costPerUnit, and idempotent retries within a duplicate window. This goes well beyond annotations and is critical for correct usage.

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 each sentence adds unique value. It leads with purpose, then covers inference prohibition, instrument specifics, quantity/cost semantics, and idempotency in a logical order. No redundant or filler content; 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 the tool's complexity (7 parameters, 5 required) and no output schema, the description covers all critical usage constraints: instrument selection, signed quantity, cost semantics, rejection rules, and duplicate behavior. It doesn't mention prerequisites like portfolio existence, but that's a minor gap likely handled elsewhere. Overall, it's quite complete for a write operation.

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 detailed descriptions, so the baseline is 3. The description adds meaningful cross-parameter context: that for options you must pass both the underlying ticker and the optionContract, and that costPerUnit is never the per-contract total. These relationships are not explicit in the schema, elevating the score.

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 ('Record') and resource ('a user-confirmed purchase or sale in the caller's portfolio'). It clearly indicates this is a write operation for adding lots, distinguishing it from siblings like UpdatePortfolioLot, RemovePortfolioLot, and GetMyPortfolio. The purpose is unambiguous.

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

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

The description gives clear context for instrument types (stock vs option), requires user confirmation ('Never infer or guess'), and explains idempotency for retries. It does not explicitly name alternative tools, but the context and sibling names make it obvious that this is for adding new lots. The guidance is solid but could be strengthened by explicitly saying 'use this to add a new lot, not to modify or close an existing one.'

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

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

Annotations 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 declare readOnlyHint=true and destructiveHint=false, so the description correctly doesn't repeat that. It adds behavioral detail beyond those annotations: the return format (one row per ticker, latest-restated value, separate listing for tickers with no data) and the fiscal calendar alignment caveat. This enriches the agent's understanding of the tool's output 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?

The description is two concise sentences: the first states the primary purpose and return behavior, the second provides a critical caveat about fiscal calendar variation. Every sentence earns its place, with the main purpose front-loaded and 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 read-only comparison tool with no output schema, the description adequately covers key operational details: the return row structure, treatment of missing data, and the fiscal calendar nuance. It even directs the agent to check the Period End column, which implies that column exists. This is sufficient for an agent to call the tool correctly and 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?

The schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra meaning by highlighting that fiscalYear/period refer to each company's own fiscal calendar, which is not explicitly stated in the schema descriptions but is crucial for interpreting results. This goes beyond the schema to clarify a potential source of confusion.

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: comparing a single financial concept across multiple companies for a given fiscal period, explicitly calling it 'peer comparison'. It also specifies the return structure ('one row per ticker...') and distinguishes itself from single-company tools like GetFinancialFact by its multi-company focus.

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, notably that fiscal years follow each company's own calendar and that peer rows can cover different months, urging the agent to check the Period End column. However, it does not explicitly name alternative tools or specify when not to use it, though the peer-comparison purpose implies 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 cover read-only and non-destructive behavior. The description adds valuable context: that comparisons happen on the latest common report date, that filer names resolve via SearchInstitutions, and what metrics are returned. This goes beyond annotations but doesn't fully detail pagination or maxResults behavior, though those are in 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?

Two sentences pack the core purpose, output, and usage guidance with zero waste. The primary action is front-loaded, and the alternative tool is mentioned at the end in a natural 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?

The description clearly states what the tool returns (Jaccard and dollar-weighted overlap, totals, shared/unique positions), which is essential given no output schema. It also points to SearchInstitutions for name resolution and GetFundProfile for NPORT portfolios. Missing details like maxResults clamping are covered in the schema, so overall it's sufficiently 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 schema already fully documents all four parameters (including name resolution and date snapping). The description doesn't add new parameter-level meaning beyond what's in the schema, so baseline 3 is appropriate.

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

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

The description clearly states the specific action (compare two institutions' 13F portfolios), the timing (latest common report date), and the specific outputs (Jaccard and dollar-weighted overlap, portfolio totals, shared/unique positions). This distinguishes it from siblings like GetInstitutionPortfolio (single institution) and GetFundProfile (mutual funds/ETFs).

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

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

Explicitly states when to use an alternative: 'For mutual-fund or ETF NPORT portfolios, use GetFundProfile' and tells users to resolve filer names via SearchInstitutions. This gives clear when-to-use and when-not-to-use guidance beyond the inherent 'compare two' purpose.

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 and destructiveHint=false. The description adds context: the portfolio is empty initially, holdings must be added separately via AddPortfolioLot, and duplicate names are rejected rather than merged. This provides useful behavioral detail 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?

Two sentences, front-loaded with purpose, no wasted words. Every sentence adds essential guidance.

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 tool with one parameter and no output schema, the description covers creation, uniqueness, user consent, and follow-up actions. It is fully sufficient.

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 clear description of the 'name' parameter. The description adds value by explaining uniqueness constraints and rejection behavior, which are not 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 clearly states it creates a new empty portfolio in the user's account, and explicitly mentions the sibling tool AddPortfolioLot for adding holdings, distinguishing it from other tools.

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 instructs the agent to ask the user before creating, providing explicit user consent guidance. It also notes uniqueness constraints and rejection behavior, though it does not explicitly list alternatives or when not to use.

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

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

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?

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 mark readOnlyHint=true and destructiveHint=false, and the description adds non-obvious behavior: the recursive smoothing is warmed up on price history before startDate, so output doesn't depend on the requested range's left edge. It also clarifies the unit (USD), which is useful behavioral context.

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, each informative: definition, formula, use case, and behavior. No filler; the technical description 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?

No output schema exists, and the description doesn't explicitly state the return shape, but the maxResults parameter description covers record ordering and count. The description provides the essential interpretive and behavioral context (unit, warmup, volatility interpretation) needed to use the tool confidently.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that period is a smoothing window used recursively and that startDate's left-edge warmup makes values stable; this goes beyond the schema's terse 'Start date in YYYY-MM-DD' definition.

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 'Average True Range (ATR) for a stock' and unpacks the indicator with a precise formula (True Range max of high-low, |high-prev_close|, |low-prev_close|), distinguishing it from related indicators like Bollinger Bands or Stochastic Oscillator. The scope is clear: a volatility measure for a single stock, in USD.

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

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

It states ATR is 'commonly used for position sizing and stop placement' and explains that higher ATR means wider daily moves, giving clear applied context. It doesn't explicitly name alternatives or when-not-to-use, but the domain is sufficiently specialized.

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 two important behaviors: the inclusion of %B and bandwidth columns, and the warm-up of the moving-average window on price history before startDate, which ensures values do not depend on the requested range's left edge. This adds significant context about data computation and edge-case handling that annotations alone do not provide.

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

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

The description is concise—three sentences that front-load the tool's purpose, then explain the calculation, interpretation, included columns, and a nontrivial edge-case behavior. Every sentence contributes meaningful information without waste 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?

Despite the absence of an output schema, the description adequately explains what the tool returns (BB bands, %B, bandwidth) and how the indicator behaves relative to the requested date range. It also covers the key formula components and the smoothing effect of the warm-up, providing enough detail for an agent to understand the tool's behavior without missing critical information.

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 adds value by explaining how parameters affect the output: 'moving average of close' corresponds to period, 'standard deviations above and below' corresponds to stdDev, and the warm-up behavior clarifies startDate semantics. This is more than just restating the schema, though it does not delve into every parameter detail, hence a 4.

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 'Bollinger Bands for a stock', clearly identifying the tool's purpose. It provides specific details about the calculation (middle band, upper/lower bands, standard deviations), distinguishes it from sibling indicators like GetAverageTrueRange or GetStochasticOscillator, and mentions included columns (%B, bandwidth), making the tool's scope unmistakable.

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

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

Usage context is provided through interpretive guidance: 'Bands widen when volatility rises and contract when it falls; price touching the upper/lower band is a common overbought/oversold cue.' This helps an agent decide when to use Bollinger Bands. However, it does not explicitly name alternatives or state when not to use this tool, so it falls 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?

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 declare readOnlyHint and destructiveHint false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: results are newest first, date range defaults to one year, amounts are disclosed ranges rather than exact values, and Asset identifies the filed instrument type (stock, option, bond). This enriches the agent's understanding 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?

Three sentences with no fluff: the first sentence states the core function and defaults, the second clarifies data semantics, and the third directs to the sibling tool. All information is front-loaded and each 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?

With no output schema, the description appropriately explains what the response contains: members, purchase/sale, transaction/filing dates, amount ranges, and instrument type. It also covers defaults and ordering. Given the tool's moderate complexity, the description is sufficiently complete for an agent to know what to expect and how to invoke it.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying semantic nuances not fully explicit in the schema: that amounts are ranges not exact values, that Asset identifies instrument type, and that transactions are reported by members of Congress. This supplements the parameter descriptions meaningfully.

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 congressional securities transactions for a specific ticker, with a scope qualifier ('newest first, last year by default'). It distinguishes itself from siblings by explicitly pointing to GetMemberTrades as the alternative for one member's transactions across tickers.

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

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

Usage context is explicit: use for a specific ticker, and 'Use GetMemberTrades for one member's transactions across all tickers' directly names the alternative. This provides clear when-to-use guidance and prevents confusion with sibling tools.

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

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

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?

Beyond the readOnlyHint annotation, the description explicitly says it is read-only, never triggers a live run, and preserves the last good result after a newer failure. This gives the agent important behavioral expectations that annotations alone do not 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 concise sentences, each earning its place: the core purpose, the behavioral guarantee, and the management redirect. The description is front-loaded with the primary action and contains 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?

For a single-parameter read-only tool with no output schema, the description covers what is retrieved, the read-only and failure-preserving behavior, and where to manage data sets. Nothing essential is missing for an agent to call 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% and the dataSet parameter already explains that it accepts 'the custom data-set name or full id shown by ListCustomDataSets.' The tool description adds no additional parameter meaning, so the high-coverage 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 a specific action ('Get'), an exact resource ('the latest independently verified stored result for one of the caller's custom data sets'), and the scope ('caller's'). This clearly distinguishes it from the many other Get* siblings, especially ListCustomDataSets.

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 solid context: use this tool to retrieve a stored result, not trigger a live run. It also explicitly redirects creation/management to the Equibles Portal. It does not explicitly name ListCustomDataSets as the sibling to list available data sets, but the parameter schema fills that in.

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 and destructiveHint false, so the safety profile is covered. The description supplements this with ordering behavior, row fields, ex-date semantics, the possibility of future ex-dates, and the primary-ticker/issuer-level restriction—valuable 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?

The description is four dense sentences with no filler. The core action and result ordering are front-loaded, followed by only high-value caveats that an agent needs before calling 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?

Even without an output schema, the description tells the agent what each returned row contains, how results are ordered, how filters apply, and a critical ticker restriction. Combined with the schema's parameter documentation, this 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 coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics by stating that date filters apply to the ex-dividend date and that records are tied to the current primary ticker, clarifying startDate/endDate and ticker beyond their schema descriptions.

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

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

The description states a specific verb and resource: 'Get a company's stored declared cash dividends newest first.' It clearly identifies the row contents, ordering, and the primary-ticker constraint, and no sibling tool covers dividend history, so an agent can distinguish it.

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 invocation context: date filters apply to the ex-dividend date, records are issuer-level, and only the current primary ticker is valid. It does not explicitly name alternatives or say when not to use this tool, but that is a minor gap given no sibling directly overlaps.

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 discloses significant behavioral nuances: the narrative shift 'is derived from approved bullets and is not separately verifier-approved', comparisons 'use filed GAAP XBRL facts, never estimates', ordering is 'Newest quarter first', and quarters can be absent from the sequence because only approved briefs appear. These caveats prevent the agent from misinterpreting missing quarters or over-trusting the shift metric.

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 (four sentences) but every sentence earns its place: each adds a disambiguating constraint ('not analyst consensus', 'not separately verifier-approved', 'quarters can be missing'). It is front-loaded with the core content definition before the caveats. The density is justified given the tool's complexity, though it could trim some redundancy around ordering.

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 retrieval tool with no output schema, the description lists the return elements (TL;DR, points, quotes, shift, guidance deltas, reported quarter vs guidance) plus all caveats (verification status, missing quarters, XBRL facts). Annotations already cover the read-only safety profile. The only gap is that the exact return structure/field naming isn't specified, but the content inventory is sufficient for an agent 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% — every parameter (ticker, limit, fiscalYear, fiscalQuarter) is already well-documented, including the clamp range for limit and the exact-period semantics for the fiscal fields. The description's 'Newest quarter first' and 'Omit both period fields for newest briefs' reinforce schema text but add little new meaning. Baseline 3 is appropriate since the structured schema carries the parameter 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 opens with a specific verb and resource — 'Get the AI Earnings Brief for a company's recent earnings calls' — and enumerates the exact content: verifier-approved TL;DR, bullish/bearish points, verbatim pull-quotes, and a narrative shift. It also carves out the data provenance ('company guidance, not analyst consensus... filed GAAP XBRL facts, never estimates'), which sharply distinguishes it from siblings like GetGuidance, GetEarningsCallTranscript, and GetEarningsCallToneAndThemes 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 provides rich context about what the tool returns and its data constraints ('Only calls with an approved brief appear, so quarters can be missing from the sequence', 'Newest quarter first'). However, it never explicitly names sibling alternatives or states when NOT to use this tool in favor of GetGuidance, GetEarningsCallTranscript, or GetFinancialStatement. Usage context is implied through content specificity, but no explicit routing or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered; with annotations present the bar is lower. The description adds real behavioral context beyond that: the selection semantics (omit both period fields for the latest call; year alone selects the latest in that year; quarter alone selects the latest matching quarter) and the group-scope behavior that distinguishes this from single-artefact tools. It discloses what the call returns (status, artefact availability, linked document ids, guidance rows) 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?

The description is front-loaded with the core purpose before moving to return content, sibling routing, and a concrete usage example. Every sentence earns its place — the return enumeration is useful given there is no output schema, and the sibling routing is essential. It is on the longer side (roughly 90 words) for a read-only getter, with slight redundancy between the artefact enumeration in sentence one and the return-content detail in sentence two, but it remains well organized and not wasteful.

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 nuanced nullable-period selection rules and the absence of an output schema, the description carries the full burden of explaining return values — and it does: id (usable with GetInvestorEventTranscript), title, call date, status, artefact availability, transcript/earnings-release document ids, and extracted guidance rows. It also covers the period-selection semantics and onward routing. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 even with no parameter details in the description. The schema already documents ticker, and the nullability/defaults and omission rules for fiscalYear and fiscalQuarter. The description echoes the 'omit the fiscal period for the latest call' rule but does not add material syntax or format detail beyond the schema. Value added is marginal but not absent, so a defensible 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 opens with a specific verb+resource+scope: 'Get the earnings-call event for a company's fiscal quarter — the single record that groups the quarter's call artefacts.' It clearly distinguishes itself from siblings by naming GetEarningsCallTranscript, GetEarningsBrief, GetEarningsCallToneAndThemes, and GetInvestorEventTranscript as the tools for the underlying artefacts rather than the grouping event. An agent can tell this apart from the adjacent investors-event and transcript tools without inspecting either schema.

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

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

Usage direction is explicit and actionable: 'Use this to ask "what do we have for AAPL FY2025 Q3?" rather than chasing each artefact separately — or omit the fiscal period for the company's latest call.' It also routes onward behavior: 'When a transcript is available, read it with GetEarningsCallTranscript, or get the AI read via GetEarningsBrief / GetEarningsCallToneAndThemes.' When-to-use and alternatives are both spelled out, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond that: verifier-approved calls only, potential missing quarters with gap notes, and AI-scored nature of the data. It does not contradict annotations and enriches understanding of data quality and completeness.

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—with the primary purpose stated upfront, followed by key data quirks and a usage hint. Every sentence adds value and there is 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 tool with four parameters, full schema coverage, annotations covering safety, and a clear description of return content (tone scores, themes, mention counts), nothing essential is missing. The description even explains the gap-note behavior and ordering, making the tool fully navigable for an 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?

Schema description coverage is 100%, so all four parameters (ticker, limit, fiscalYear, fiscalQuarter) are already documented in the schema with meaningful descriptions. The tool description does not add any additional parameter-level detail beyond what the schema provides, so a 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 clearly states the exact resource (company earnings calls), the specific outputs (net tone score, hedging score, key themes with mention counts and per-theme tone), and the ordering (newest first). It distinguishes itself from similar siblings like GetEarningsBrief and GetEarningsCallTranscript by focusing on AI-scored tone and themes.

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 provides clear context on when to use the tool ('to gauge how confident or guarded management sounded') and explains data availability quirks (verifier approval, gaps in quarters). However, it does not explicitly name alternative tools or state conditions for selecting this one over others, leaving some routing inference to the agent.

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 when speaker identities appear (only trusted resolution) and how unverified voices are labelled (role or neutral number). This adds meaningful behavioral context about output reliability 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?

Two sentences with zero fluff. The core purpose is front-loaded, followed by behavioral nuance and a usage directive. Every word 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?

For a tool with no output schema, the description explains the output format (ordered speaker turns with attribution) and the identity resolution rule. It also provides a prerequisite check. The agent has enough context to decide and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the fiscal quarter focus but adds no new parameter details; the schema already documents each parameter adequately. No compensation is needed.

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 'Get', the resource 'speaker-labelled transcript of a company's earnings call', and the scope 'for a fiscal quarter'. It also distinguishes from GetEarningsCallEvent by implying that tool checks existence, making the purpose 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?

The description explicitly directs the agent to 'Use GetEarningsCallEvent first to check a transcript exists', which is a clear alternative tool and an explicit precondition. This is a strong usage guideline that prevents failed calls.

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 declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context: extraction from narrative text, verification before publication, newest-first ordering, and a back-filling coverage caveat that explains empty results. 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?

The description is front-loaded with the core purpose, then details return fields, source, and coverage caveat. Every sentence earns its place, and the length is justified by the lack of an output schema and the need to explain empty-result semantics.

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 compensates by enumerating returned fields (person, role text, normalized role, action, effective date, verbatim disclosure, source filing) and clarifying ordering and coverage limitations. It is sufficiently complete for an agent to invoke and interpret results 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?

Input schema covers all 5 parameters with descriptions at 100% coverage, so the description need not repeat parameter details. It mentions action filter values and date fields contextually but adds no new syntax or semantics 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?

Description uses a specific verb ('Get') with a clearly defined resource ('executive and director changes') and narrows scope via '8-K Item 5.02 filings' and 'newest filing first'. This distinguishes it from sibling tools like 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 sets clear expectations about the data source, ordering, and coverage caveat, which helps an agent decide when to use it. It does not explicitly name alternatives or state exclusions, but the purpose is specific enough to imply appropriate use.

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

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

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 description goes well beyond the readOnly and destructive hints by disclosing crucial behavioral quirks: Quantity is a balance not daily new fails and should never be summed; Price is the previous trading day's closing price per SEC convention; the coverage window and partial-coverage caveat; the two-week publication lag; and the interpretation of high/persistent balances. This is exemplary transparency.

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

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

The description is longer than a simple one-liner, but every sentence earns its place by disclosing a necessary caveat or convention. It starts with a clear purpose statement and then expands with critical usage details. It is well-structured and not bloated, though it 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?

Given there is no output schema, the description fully explains the return semantics: Quantity, Price, Value, coverage windows, missing dates, publication lag, and interpretation. It covers all aspects an agent needs to correctly use the tool and interpret its results, making it highly complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not directly explain parameters further but adds context about output semantics (e.g., missing dates, lag) that indirectly affects parameter interpretation (e.g., endDate default trails today). This is marginal value, not enough to raise the score.

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 fails-to-deliver (FTD) data for a stock from the SEC's twice-monthly FTD files.' It clearly differentiates this from siblings like short interest or short volume by focusing on FTD specifically. The scope and source are 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?

The description provides clear context on when this tool is relevant, noting that 'High or persistent FTD balances may indicate naked short selling or settlement issues.' While it doesn't explicitly name alternative tools or exclude them, the context is sufficient for an agent to infer appropriate use cases. It stops short of explicit when-to-use vs. alternatives guidance, so not 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, 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 mark the tool as read-only and non-destructive. The description adds valuable behavioral context: returns a time series with latest restated values unless asOriginallyReported is set, each row includes actual period start/end, fiscal periods follow the company's own calendar, and a warning is raised when the selected alias ends materially before other facts (indicating a possible XBRL tag change). 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 a single dense paragraph that efficiently conveys purpose, usage, and behavioral details. It front-loads the core action and then adds specifics. While it could be slightly more structured (e.g., bullet points for the warning or parameter clarifications), it is not overly long and every sentence adds value.

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

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

Given the tool has 8 parameters, no output schema, and moderate complexity, the description is highly complete. It explains the return type (time series, one row per fiscal period with period start/end), the default data treatment (latest restated), the warning mechanism, and scope exclusions. No output schema is needed because the description sufficiently describes the output structure.

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 adds extra meaning beyond the schema: it explains the default behavior of asOriginallyReported, mentions that calling concept with an unknown value lists supported aliases, and clarifies the fiscalPeriod note about discrete Q4 rows. This pushes the score above baseline.

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

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

The description clearly identifies the tool as retrieving a single financial concept over time for a company from SEC XBRL data, naming example concepts. It explicitly distinguishes from sibling tools (GetFinancialStatement for full statements, CompareFinancialFact for peer comparison) and mentions that dimensioned disclosures are out of 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?

The description provides explicit guidance on when to use this tool versus alternatives: 'For a full statement use GetFinancialStatement; to compare peers use CompareFinancialFact.' It also notes that dimensioned disclosures (e.g., customer concentration) are outside this tool, and instructs calling with an unknown concept to list supported aliases.

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 the tool as read-only and non-destructive, and the description adds meaningful behavioral detail beyond that: it returns latest-restated values, targets one exact period end, derives discrete quarterly flow rows from cumulative YTD values when necessary, and marks those rows as Derived. This gives the agent a clear picture of what the tool actually does at runtime.

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 longer than average but every sentence earns its place: scope, output behavior, derived-quarter caveat, and sibling routing are all covered without redundancy. It is front-loaded with the core purpose and then layers in necessary constraint details.

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 responsibility for explaining return semantics, and it does so: standard line items, latest-restated value, one exact period end, discrete quarterly rows, and the Derived flag are all disclosed. It also covers source provenance, exclusions, and alternatives, making it complete for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the description is not burdened with compensating for undocumented parameters. It restates the statement types and period concept already covered by the schema, and the Q4 caveat is already present in the period parameter description. It adds little parameter-level meaning beyond the structured 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 specific action and resource: get a company's income statement, balance sheet, or cash-flow statement for a fiscal year and period. It also differentiates itself from siblings by explicitly excluding dimensional facts and naming GetRevenueBreakdown, GetFinancialFact, and CompareFinancialFact as the alternatives for those cases.

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 when-to-use guidance, including the note that most filers do not report discrete Q4 income/cash-flow facts and that 'FY' should be used for annual figures. It also tells the agent exactly when to prefer sibling tools such as GetRevenueBreakdown and GetFinancialFact.

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 does not contradict these. The description adds valuable behavioral context: results are sorted by recency, a note flags when more results exist than returned, and crucial caveats that proposals may never execute and completed sales may appear later on Form 4/5. This goes beyond the annotation coverage.

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 comprehensive yet efficiently structured, starting with the core purpose, then detailing notice contents, then ordering and scoping advice, and finally an important execution caveat. Every sentence contributes information, with no repetition or filler. It is front-loaded with the primary function.

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 lacking an output schema, the description thoroughly explains what each notice contains (seller, relationship, shares, market value, sale date, broker, remarks, 10b5-1 plans), result ordering, the existence flag for more results, and the caveat that proposals may not execute. This gives an agent enough context to correctly interpret the response and decide when to use the tool, completing the picture for a read-only data fetch.

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 provides 100% coverage for all four parameters with clear descriptions (ticker, toDate, fromDate, maxResults). The description adds rationale for using date parameters (avoid flooding) but does not introduce new parameter semantics beyond what the schema specifies. Per the baseline rule, a score of 3 is appropriate when schema covers parameters.

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

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

The description clearly states the tool retrieves proposed insider sales from SEC Form 144 notices, with a specific verb ('Get') and resource ('proposed insider sales'), and details the content of each notice. It stands apart from siblings like GetInsiderTransactions or GetInsiderOwnership by focusing on Form 144 proposals, making the purpose 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?

The description provides practical guidance on when to use fromDate/toDate, noting that heavy 10b5-1 filers can flood the recency window, and explains results are ordered most-recent-first with a flag for additional data. It does not explicitly name alternative tools for different use cases, but the context implies this is for proposed sales rather than completed transactions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description goes beyond this by explaining the behavioral quirks of Form D data—how ongoing offerings are re-noticed via D/A amendments and the need to group by first-sale date and offering amount. This adds substantial context about data semantics and potential aggregation pitfalls that annotations do not convey.

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

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

The description is longer than average but every sentence adds value: it defines the resource, lists key fields, warns about a data quirk, and gives a use case. The most critical information (purpose and D/A warning) is front-loaded, and there is no filler. It could be slightly trimmed, but it is well-structured and efficient for the 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?

There is no output schema, so the description compensates by enumerating the fields returned (issuer, first sale date, offering amount, etc.) and the amendment behavior. It covers the main data aspects an agent needs to interpret results. It omits minor details like error handling or pagination behavior, but these are either in the schema (maxResults) or not critical for a read-only tool. Overall, it is sufficiently 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 all parameters (ticker, toDate, fromDate, maxResults) are already documented with types and descriptions. The description does not add extra meaning about parameter syntax or format beyond what the schema 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 description states a specific verb ('Get'), a clear resource ('SEC Form D notices'), and the scope ('recent exempt securities offerings for a company'). It explicitly distinguishes itself from sibling tools like GetForm144ProposedSales by focusing on private placements and Form D, making selection obvious.

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 provides a clear use case ('track how a company is raising private capital alongside its public filings') and gives important operational guidance about D/A amendments and grouping to avoid double-counting. It does not name explicit alternatives, but the specificity of the tool makes the intended usage 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 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, covering the safety profile. The description adds valuable nuance: it mentions the multi-series trust caveat (only tracked-stock positions stored) and clarifies that reported counts still reflect the full filing. This goes beyond what annotations provide without contradicting them.

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 purpose and then details, caveat, and alternative. It is slightly dense but every sentence adds value. It avoids fluff and is appropriately sized for a tool that returns a profile plus holdings.

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?

While there is no output schema, the description lists the returned fields (registrant, series, assets, holding counts, largest positions) and notes the multi-series trust caveat. It also references the inverse tool. For an agent, this is sufficient to understand return expectations and when to use the tool, though it does not mention error cases or pagination beyond maxResults.

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 covers both parameters with descriptions, and the tool description adds extra meaning by explaining the accepted identifier types and giving examples (e.g., 'S000004344', 'IWM'). The maxResults description is also clear with default and max. The description enriches the schema rather than merely repeating it.

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') and clearly distinguishes it from the inverse lookup tool GetFundsHoldingStock. It leaves no ambiguity 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?

It details acceptable input types (profile ID, SEC series ID, ticker, alias) and references SearchFunds for verified aliases. It points to GetFundsHoldingStock for the inverse lookup, but doesn't explicitly state conditions for choosing alternative tools beyond that. This is clear context, though a short 'use when' clause would strengthen it.

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 richly discloses behavioral traits beyond the readOnlyHint annotation: CUSIP matching against each fund series' most recent report, exclusion of series that stopped filing more than 18 months ago, no exited positions shown, and per-report as-of dates. It also enumerates return fields since no output schema 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?

The description is appropriately sized for a complex tool, with each sentence providing substantive value: source, matching logic, output fields, ordering, as-of-date caveat, and use case. There is no redundancy or vague language.

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 lacking an output schema, the description fully enumerates the returned fields (registrant, series, period, position size, value, share of net assets, payoff profile), explains the as-of-date mixing nuance, and states the use case. This provides complete guidance for an agent to invoke and 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% for all three parameters, so the baseline is 3. The description adds minimal extra semantics—it reiterates ordering ('largest positions first') and the registrantOrSeries filter's purpose, but these are already well documented 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 states the tool's function with a specific verb ('Get') and resource ('registered investment companies holding a given stock'), and identifies the data source (SEC Form NPORT-P). It clearly differentiates from the sibling GetFundHoldings by focusing on the inverse direction—funds holding a stock rather than a fund's holdings.

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 a clear usage context: 'Use this to see which funds and ETFs own a stock and how concentrated each position is.' It does not explicitly mention alternative tools or exclusion criteria, but the directionality and purpose are unambiguous.

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

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

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 non-obvious behavioral context: 'total value (obligated dollars plus unexercised ceiling — not revenue received)', 'outlays when reported', and coverage limitations ('only prime contract awards of $1M or more... sums understate total federal revenue'). This goes well beyond 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 every sentence earns its place: purpose, key fields, data coverage caveats, and sibling alternative are all covered in a compact paragraph. It is front-loaded with the primary action and avoids 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 burden of explaining return values, and it does: award date, recipient, agency, total value, outlays, period-of-performance end date, and description. It also addresses data source, coverage thresholds, and how to interpret understatement, making it complete for a tool of this complexity.

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 of the 6 parameters already well-described. The tool description itself does not add parameter-specific semantics beyond what the schema provides, so the baseline 3 is appropriate. It does contextualize the meaning of 'total value' but that is an output field, not a 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 opens with a specific verb and resource: 'Get federal government contract awards (from USAspending.gov) won by a specific public company.' It clearly identifies the target (specific public company) and differentiates from sibling GetTopGovernmentContractors by noting 'use GetTopGovernmentContractors to rank companies market-wide.'

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: 'Useful for gauging a company's reliance on federal spending; use GetTopGovernmentContractors to rank companies market-wide.' It also clarifies coverage limitations (prime awards ≥ $1M) that help the agent decide when this tool is appropriate versus alternatives.

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

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

Annotations only declare readOnlyHint, openWorldHint, and destructiveHint, but the description adds rich behavioral detail: how closed periods are marked, how revenue/EPS guidance includes actuals once comparable XBRL facts exist, the non-GAAP comparison rule, and coverage notes distinguishing unprocessed documents. This transparency goes 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 compact yet information-dense, front-loading the primary purpose and then efficiently covering ordering, period marking, comparison rules, and coverage notes. No redundant sentences; each clause 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 the single parameter, no output schema, and read-only annotations, the description provides a thorough explanation of the returned content: source types, ordering, period status, comparison behavior, and coverage classification. This suffices for an agent to invoke correctly and 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?

The schema fully describes the only parameter 'ticker' with an example and type, achieving 100% schema description coverage. The description does not add extra parameter-level detail, which is unnecessary given the baseline of 3 for high 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 clearly states the tool retrieves company guidance from Item 2.02 earnings releases and transcripts, newest first, with specific attributes like range, unit, GAAP basis, fiscal period, and provenance. This specific verb+resource combination distinguishes it from siblings such as GetEarningsBrief or GetFinancialFact.

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

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

The description implies the tool is for guidance data from written earnings releases and call transcripts, and notes nuances like non-GAAP never being compared to GAAP actuals. However, it does not explicitly name alternative tools or conditions for when not to use it, relying on the detailed purpose to guide 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?

Annotations already mark the operation as read-only and non-destructive, and the description adds substantial behavioral transparency beyond that: it explains window-based dating, collapse of duplicate records across funds, and the reporting lag. These are exactly the non-obvious traits 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?

The first sentence is a clear front-loaded purpose statement, and every subsequent sentence adds necessary nuance about derivation, timing, deduplication, and reporting behavior. It is longer than the minimal case, but the complexity of the tool justifies each sentence with no filler.

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

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

For a two-parameter read-only list tool with no nested objects and no output schema, the description is unusually complete. It covers what the tool returns conceptually, the meaning of the returned events, the data source derivation, and key caveats such as window granularity and deduplication.

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 "index" and "maxResults" are already documented with examples and defaults. The description adds context about index change events but does not need to repeat parameter mechanics; the baseline of 3 is appropriate because the schema carries the parameter 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 opens with a specific verb and resource: "Get the companies that have joined or left a major US stock index, newest first." It clearly identifies this as a change-history tool for index constituents and distinguishes it from related index tools by emphasizing observed membership rather than an announcement feed.

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 for when the data is available: changes appear only after a tracking fund has reported them, and overlapping fund reports are collapsed. It also explicitly frames the tool as "observed membership, not an announcement feed," which is a useful exclusion, though it does not name alternative tools such as GetIndexComposition or GetIndexForecast.

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?

The description adds substantial behavioral detail beyond the annotations: shares come only from the most recent Form 3/4/5 filing, options and derivatives are excluded, figures are restated onto today's split basis, Indirect can understate because only the last vehicle balance is kept, and former insiders may show stale dates or zero shares. These nuances materially affect how an agent interprets 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 dense but efficient: it front-loads the core purpose, then packs several important caveats into compact sentences, ending with clear usage guidance. Every sentence contributes meaningful information about behavior or usage, with no filler or tautology.

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 responsibility of explaining what the result contains, and it does so thoroughly: source filings, ownership buckets, split adjustment, exclusions, indirect holding limitations, max results, and ranking order. An agent has enough context to call the tool and correctly interpret the response.

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 adds useful contextual semantics like the maxResults default and implicit ranking by total shares, but it does not significantly extend the meaning of individual parameters beyond what the schema provides. 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 the exact verb and resource ('Get a summary of insider ownership for a stock'), specifies the ranking basis ('ranked by total shares held'), and clearly differentiates itself from sibling tools like GetInsiderTransactions and GetInsiderSentimentScores. It is unambiguous about what the tool returns.

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

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

The description explicitly states when to use this tool ('Use this to understand the insider ownership structure of a company') and names the alternative for the underlying trades ('use GetInsiderTransactions'). This gives an agent clear routing guidance without needing to infer usage from the schema.

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 significant behavioral context: it defines the scoring components (net buyers, shares bought as % of outstanding, net buy value), explains the data source (Forms 4/5, excluding 10b5-1) and crucially states 'Filters never renumber the universe rank' — essential for interpreting results. Goes well 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?

Three sentences, front-loaded with the core purpose, then methodology, then usage options. No wasted words; every sentence contributes value. The structure flows logically from what to how to when.

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 conveys key output components (score, factors, rank, net buyers, shares bought, buy value) and behavior (filters don't renumber rank). It also cross-references GetInsiderTransactions for raw filings. An agent can understand what to expect and how 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 all parameters have individual descriptions. The tool description adds contextual usage semantics: 'pass ticker for one stock's factors and universe rank' and 'request the bottom ranking for distribution' clarify how bottom and ticker interact with filters. This adds meaning beyond the schema, though not exhaustive.

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 (rank) and resource (stocks) with a precise definition: 'peer-relative 0-100 insider-accumulation score over 90 days'. It also outlines the methodology (Form 4/5, excluding 10b5-1) and differentiates from siblings by pointing to GetInsiderTransactions for filings. Clear 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 context on when to use: for ranking by insider sentiment, with options for cluster buys, liquidity, bottom ranking, or single-ticker lookup. It explicitly directs to GetInsiderTransactions for raw filings, but does not contrast with all alternative scoring tools (e.g., GetInsiderOwnership). Still, usage scenarios are well implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context about the 'Owned After' split basis, per-security and ownership-form restatement, and the '-' for pre-2023 10b5-1 filings. It doesn't mention pagination or rate limits, but this is a read-only data fetch with thorough column semantics, so a 4 is fair.

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

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

The description is a single, information-dense paragraph. It front-loads the core purpose and then adds semantic details about the columns and filters. Slightly long but every sentence adds value; for a complex SEC data tool this is acceptable.

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 explains the key columns (Type, 10b5-1, Shares/Price/Value, Owned After) and their meanings, plus date-range and filter support. It doesn't explicitly state the response ordering beyond 'newest first', which is covered. For a 6-param tool with no output schema, this is quite complete, though it could note that maxResults clamping behavior is in the schema already.

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 params are documented in the schema. The description adds meaning beyond the schema by explaining the transactionType semantics (Buy/Sell vs Award/Conversion etc.), and the insiderName matching behavior ('contains every word, case-insensitive'), which is not in the schema. This compensates 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 precise verb+resource statement: 'Get recent insider trading transactions for a stock from SEC Forms 4 and 5, newest first.' It clearly distinguishes from siblings like GetInsiderOwnership, GetInsiderSentimentScores, and GetCongressionalTrades by focusing on Forms 4/5 transactions.

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 says 'Use this to understand insider buying/selling activity' and distinguishes Form 3 as 'initial ownership rather than a transaction.' It explicitly cautions that Buy/Sell are only open-market trades, versus compensation/derivative mechanics, and explains the 10b5-1 column meaning, which guides the agent on what this tool is good for.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond these: it explains the provisional combined view during the newest quarter's filing window, including the carry-forward of prior-quarter positions and that this is flagged in the output. This is exactly the kind of nuance an agent needs to interpret the data correctly. 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, each adding value: the purpose and output, the provisional-quarter behavior, and the intended use case. It is front-loaded with the primary action and resource. It is efficient with no filler, though it could be tightened slightly if desired. Deserves a 4 for good structure without waste.

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

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

For a read-only tool with two parameters and no output schema, the description covers the essential context: what data is returned, the time dimension, and the special provisional-quarter caveat. It does not specify the exact response format, but given the tool's simplicity and the presence of annotations for safety, this is adequate. Missing a few details like specific output fields (though some are mentioned) keeps it from a 5, but it is otherwise complete.

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

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

The input schema provides full descriptions for both parameters: ticker (example usage) and maxPeriods (default and clamp range). Since schema description coverage is 100%, the description does not need to re-explain these and indeed does not add any additional meaning. The baseline of 3 is appropriate because the description adds nothing 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 the historical trend of institutional ownership across multiple quarters, specifying the resource (institutional ownership) and the dimension (trend over time). It also lists the key output fields (total shares, market value, holder count). However, it does not explicitly name sibling tools or differentiate from them by name, though the 'historical trend' scope distinguishes it from related tools like GetInstitutionQuarterlyActivity or GetTopHolders. Missing explicit sibling differentiation keeps it at 4 rather than 5.

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

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

The description gives a clear use case: 'Use this to understand whether institutional interest in a company is growing or declining.' This tells the agent when the tool is appropriate. It does not mention explicit alternatives or exclusions (e.g., 'for a single quarter use X'), so it lacks the when-not-to-use guidance that would earn a 5. The context is clear 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 meaningful behavioral details beyond these: dividends are excluded from returns, split ratios are handled with a fallback to exclude earlier closes when unusable, and the valuation uses raw closing prices. These are non-obvious behaviors that materially affect results and are not inferable from the schema or 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 verbose paragraph, but every sentence earns its place—purpose, mode selection, reconstruction/rebalancing details, return metrics, and split handling are all packed in. It is front-loaded with the core purpose. While it could be broken into bullet points for readability, it is not bloated and remains efficient for its 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?

Given the tool's complexity (backtest logic, snapshot reconstruction, split handling) and the absence of an output schema, the description does a thorough job. It specifies the exact return metrics (price return, CAGR, max drawdown, alpha), explains the date range logic, institution resolution, and benchmark default. An agent has enough information to invoke the tool correctly without ambiguity about inputs or expected outputs.

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

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

Schema description coverage is 100%, so every parameter has a description. The tool description adds value by clarifying interactions: fromDate overrides windowYears, windowYears is clamped to 1-20, and institution accepts names/CIKs with resolution behavior (unique partials, aliases, ambiguous partials return candidates). This enriches the schema descriptions without being redundant.

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 the specific verb 'Backtest' and a precise object: how cloning an institutional filer's reported 13F portfolio would perform against a market benchmark. It clearly distinguishes this from the many other institution-related tools (e.g., GetInstitutionPortfolio, GetInstitutionQuarterlyActivity) by focusing on backtest performance, not holdings or activity. The first sentence alone fully defines the tool's purpose.

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 explains the two modes of operation (trailing window via windowYears, or explicit fromDate/toDate range) and notes that fromDate overrides windowYears when both are supplied. It also mentions the rebalancing on the SEC filing lag, giving context for how results are produced. However, it does not explicitly contrast with alternative tools (e.g., 'use this instead of X when...'), though given the unique purpose, this is a minor omission.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so no contradiction. The description adds value beyond annotations by disclosing the ranking behavior, the 2-25 institution range constraint, the snapping behavior of reportDate implied by 'latest common quarter', and the partial-name resolution semantics. These are behavioral traits 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?

Two sentences with no filler. The primary function and ranking logic are front-loaded, and the minInstitutions usage tip is placed at the end as practical guidance. 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?

For a read-only aggregation tool with 100% parameter schema coverage and no output schema, the description covers the purpose, ranking, key constraint (2-25), and parameter intent. It omits explicit mention of return format, but without an output schema that is a minor gap given the tool's straightforward list-oriented nature.

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 meaning beyond the schema by explaining the purpose of minInstitutions in the ranking context ('shared by multiple filers') and by framing institutionNames as supporting partial names and CIKs with ambiguity resolution. This enriches but does not reinvent 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 verb ('Combine'), resource (institutions' 13F portfolios), and ranking logic (holder count, then combined value). It distinguishes itself from single-institution tools by emphasizing multi-institution consensus, though it does not explicitly name sibling alternatives like GetFundsHoldingStock or 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?

The description conveys context via 'latest common report date' and 'positions shared by multiple filers', and gives a concrete tip (set minInstitutions to 2+ for shared positions). However, it does not explicitly state when to prefer this over similar tools (e.g., GetInstitutionPortfolio, GetFundsHoldingStock) or when NOT to use it.

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, and the description adds beyond that: it discloses the output structure (largest holdings, share counts, market values, percent of portfolio, total value, position count), default/max results, and the ambiguity handling behavior ('ambiguous partial returns candidate CIKs instead of selecting silently'). This is useful context not available from annotations or schema.

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

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

The description consists of two well-structured sentences. The first sentence defines the tool's function and outputs; the second provides usage guidance. Every phrase contributes essential information—no filler, no redundancy, and the most critical details are front-loaded.

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

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

With no output schema, the description carries the burden of explaining returns, and it does so thoroughly: it lists the specific data included (share counts, market values, percent of portfolio, total value, position count). It also covers defaults (20, max 500), ambiguity resolution, and the predecessor tool. For a read-only tool with four well-documented parameters, this is contextually 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?

The schema descriptions cover all four parameters (100% coverage), providing clear field-level details. The main description adds contextual meaning around the 'largest tracked holdings' concept and confirms default/max limits, which helps understand the offset/maxResults parameters without duplicating schema text. It adds value beyond the schema rather than merely restating it.

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 'View the stock portfolio of a specific institutional investor (fund manager) from their SEC 13F-HR filing,' with a specific verb and resource. It enumerates the output scope (largest holdings, share counts, market values, portfolio total) and distinguishes itself from search tools like SearchInstitutions by pointing users to resolve ambiguous names first.

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 tells users when to use this tool ('Use this to understand what stocks a particular fund manager or institution is investing in') and instructs them to use SearchInstitutions first when the name is ambiguous. While it does not mention alternatives like GetFundHoldings or GetTopHolders, the provided guidance is clear and actionable for common scenarios.

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 adds valuable behavioral details: it returns one markdown section per bucket, sorts by absolute Δ market-value descending, and clarifies that Δ Value includes price movement, not just trading. It also explains the diffing logic against the prior quarter, giving the agent a clear picture of the output and interpretation.

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

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

The description is two sentences, front-loaded with the verb and resource, and every clause contributes value. It efficiently conveys the core functionality, return format, sorting, and a usage example 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?

Given the tool's moderate complexity, the 100% schema coverage, and the read-only annotations, the description is fully complete. It explains the return format (markdown sections), sorting rationale, the meaning of Δ Value, and the applicable question it answers. No output schema exists, but the description sufficiently covers expected 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 already covers all four parameters with detailed descriptions (bucket values, default maxResults, date snapping, and institution name resolution). The description does not add new parameter-level semantics beyond what is already present in the schema, 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 clearly specifies the verb ('Get') and resource ('institution's quarterly position-change activity'), and enumerates the exact buckets (Initiated / Increased / Reduced / Exited) and the temporal comparison (vs. immediately prior quarter). This distinctly separates it from sibling tools like GetInstitutionPortfolio and GetFundHoldings, which focus on current holdings rather than changes.

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 a concrete use case: 'Use this to answer "what did this fund do this quarter?"' and explains how to filter with the `bucket` parameter. However, it does not explicitly name alternatives or state when NOT to use this tool, such as when a user needs a current holdings snapshot rather than change activity.

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 annotations (readOnlyHint=true, destructiveHint=false), the description adds substantial behavioral details: defaults to the latest quarter, grouping via groupBy, markdown table output sorted by % descending, unclassified stocks collapsed into a single row, and ambiguous partial names returning candidates instead of silent selection. This enriches the agent's understanding of what the tool actually does.

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 long, each earning its place: the first states the main function and grouping options, the second describes the output format and sorting, and the third gives a crucial usage hint about name resolution. It is front-loaded with the core purpose and contains no fluff 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?

There is no output schema, so the description properly explains the return format (markdown table, sorted by % of portfolio, unclassified row at the end). It also documents defaults for reportDate and groupBy, and warns about ambiguous name behavior. For a tool with 3 parameters and no output schema, this covers all essential aspects an agent needs to use it correctly.

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

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

Schema description coverage is 100%, so a baseline of 3 is appropriate. The description does not add significant new meaning to the parameters beyond the schema: groupBy's meanings and reportDate's snapping behavior are already in the schema, and institutionName's ambiguous partial handling is also in the schema. The only slight addition is the usage guideline to use SearchInstitutions for exact CIKs, which is more of a usage guideline than a semantic enrichment.

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: getting an institution's 13F portfolio allocation for a given report quarter, grouped by industry or sector. It uses a specific verb ('Get') and identifies the resource ('institution's 13F portfolio allocation') with clear scope (grouping levels). This distinguishes it from sibling tools like GetInstitutionPortfolio or GetFundHoldings by emphasizing the sector/industry rollup.

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 an explicit alternative: 'Use SearchInstitutions for an exact CIK' and warns that ambiguous partial names return candidates. This gives clear guidance for the institutionName parameter. However, it does not explicitly contrast with other allocation tools (e.g., GetInstitutionPortfolio), so it lacks a full when-to-use vs. alternatives discussion, but the context is sufficiently 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 read-only and non-destructive behavior, so the safety is known. The description adds valuable context: it reports 13F value for long U.S. positions only (not total AUM) and highlights that ambiguous partial names yield candidate CIKs rather than an implicit pick. These are non-obvious behaviors that help the agent set expectations.

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 two sentences with no filler. The first sentence packs a dense list of returned fields; the second succinctly gives resolution guidance. Every phrase 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?

For a simple 2-parameter, read-only tool with full schema coverage, the description conveys the scope, key output fields, and edge-case behavior (ambiguous names). The schema already handles reportDate snapping, so nothing crucial 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% – both parameters have clear descriptions (institutionName resolution rules, reportDate default and snapping behavior). The tool description does not add any parameter-level detail beyond the schema, so the baseline score 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 clearly states the tool returns a portfolio summary header for institutional 13F filers, enumerating specific metrics (13F value, position count, concentration, turnover, dates, quarters tracked). This distinguishes it from sibling tools like GetInstitutionPortfolio or GetInstitutionQuarterlyActivity by positioning it as the summary-level view.

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 to resolve CIKs using SearchInstitutions and notes that ambiguous names return candidates rather than being silently resolved, which is a clear usage hint. It also clarifies scope ('not total firm AUM'), but does not explicitly tell the agent when to choose this tool over other institution-related 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds behavioral context by enumerating the specific data fields returned (legal/business names, SEC file number, etc.), which gives the agent a better sense of what the response contains. It does not discuss error handling or rate limits, but this is a simple read operation.

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

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

Two sentences: the first packs the scope and all key fields in a list, the second gives a pointer to the search tool. No redundant words, no repetition of schema content, and the most important detail (Form ADV profile by CRD number) 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?

For a single-parameter read-only tool with no output schema, the description is highly complete. It specifies the input (CRD number), the exact domain (Form ADV), the list of fields returned, and how to obtain the necessary input via SearchInvestmentAdvisers. The only minor omission is error handling, but this is not essential for a simple getter and the annotations cover safety concerns.

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 covers the parameter with type and description (100% coverage), but the tool description adds semantic detail by specifying it is for 'SEC-registered' advisers and that it is the 'Organization' CRD number, distinguishing from other possible identifiers. It also explains how to find the CRD value via the sibling tool, enriching the parameter meaning.

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

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

The description uses a specific verb 'Get' with a precise resource, 'full Form ADV profile', and identifiers it by 'Organization CRD number'. It clearly distinguishes from the sibling SearchInvestmentAdvisers by explicitly noting that CRD numbers can be found with that tool.

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

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

The description gives explicit guidance on when to use this versus the alternative: 'Find CRD numbers with SearchInvestmentAdvisers' implies you need a CRD number to use this tool and should use the search tool if you lack one. No exclusions are stated, but the prerequisite and an alternative are clearly named.

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 read-only nature is given. The description adds valuable behavioral detail: it returns metadata and access paths, not the binary contents, and explicitly lists the response fields including the distinction between PDF and image-slideshow paths. This goes beyond annotations by explaining what the response contains and what it does not.

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 that front-loads the purpose and then details the return fields. It avoids redundancy and each clause adds information, but it is slightly longer than necessary and uses a semicolon-heavy structure. Still, it is efficient and easy to parse.

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 by listing all returned metadata fields and the two possible path types. It also clarifies that binary content is not embedded, which prevents an agent from expecting it. The prerequisite for the id is explicitly stated. This is complete for an agent to call 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 single parameter eventId is fully described in the schema with the same source guidance ('from ListInvestorEvents or GetEarningsCallEvent'). Since schema description coverage is 100%, the baseline is 3; the description does not add additional semantic meaning beyond what the schema already provides.

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

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

The description clearly states it 'Get[s] metadata and access links for a captured investor-event slide deck by event id,' specifying the resource and action. It distinguishes itself from sibling tools like GetInvestorEventTranscript by detailing the exact fields returned (deck metadata, PDF vs. image-slideshow kind, page count, etc.) and by noting that binary content is not embedded, making its purpose 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?

The description provides clear context on how to obtain the required event id ('Get the event id from ListInvestorEvents or GetEarningsCallEvent'), which serves as a prerequisite. It implies this tool is the one for slide-deck metadata, distinct from transcript tools, though it does not explicitly list alternatives or exclusions. This is clear contextual guidance without explicit 'when not to use' phrasing.

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 about speaker resolution: 'every speaker turn in order, attributed to the real person... when the resolution is trusted; unverified voices show as a role label... or a neutral speaker number.' This explains the output's trustworthiness and fallback behavior, which is beyond the annotation. A 4 is appropriate because it enriches understanding without redundancy.

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 starts with the core function, then details output attributes, then gives usage context. Each clause carries useful information—no filler. It is slightly dense due to the speaker-resolution details, but that is directly relevant to the tool's purpose. Overall, it is well-structured for its length.

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 one required parameter and well-documented schema, the description covers the output format (speaker turns, attribution), the source of the id, and the scope (non-earnings events). It does not discuss error cases or edge behavior, but those are not critical given the read-only nature and existing pagination notes in the schema. The tool is sufficiently contextualized among its siblings.

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%: each parameter (eventId, limit, offset) has a description, including the clamping range for limit and paging purpose for offset. The description only adds a sourcing hint for eventId ('Get the event id from ListInvestorEvents'), which already appears in the schema's eventId description. Since the schema does the heavy lifting, the description adds little extra meaning, so baseline 3 is correct.

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

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

The description states a specific verb ('Get'), a clear resource ('speaker-labelled transcript of a specific investor event'), and the means of identification ('by its event id'). It explicitly contrasts with earnings calls, distinguishing it from the sibling GetEarningsCallTranscript, so an agent can immediately tell them apart without reading 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?

The description gives explicit guidance: 'Use this for conferences and other non-earnings events, which have no fiscal quarter to key on,' which tells when to use this tool and implies when not to (earnings calls). It also directs the agent to obtain the event id from ListInvestorEvents, providing a clear prerequisite. This is nearly complete 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?

The annotations already declare readOnlyHint=true and destructiveHint=false. The description goes beyond by detailing the return structure (headline, publish date, summary, link), reverse-chronological order, and crucially the partial coverage caveat that an empty result may be a coverage gap, with the response indicating which case. No contradiction.

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 about four sentences, all substantive: main purpose, return format, usage guidance, coverage caveat. No fluff.

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

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

For a simple read-only list tool with no output schema, the description covers what the tool returns, ordering, and the important edge case of empty results. Combined with the schema and annotations, the user has enough to select 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?

Schema coverage is 100%, with clear descriptions for 'since' and 'maxResults'. The description doesn't add additional parameter semantics beyond the schema, so 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 uses a specific verb ('Get') and resource ('investor-relations press releases... from the company's IR website'), clearly distinguishing this from sibling tools like GetInvestorRelationsEvents and third-party news sources.

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 tells the user when to use it: 'Use this to see a company's latest official announcements straight from its IR page, and notes it is 'distinct from third-party news.' However, it doesn't name specific alternative tools or exclusion cases, so a 4.

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 valuable interpretive context: that missing underwriters/risk factors distinguish pending/rejected extractions, and that all data is 'verified against the filing text and never estimated.' This goes beyond the structured annotations without contradicting them.

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

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

The description is a single dense sentence with a long semicolon-separated list. It front-loads the main action but would benefit from bullet points or shorter sentences for readability. Every item is informative, but the structure is not optimized for quick comprehension.

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 burden of explaining return values. It inventories all major data groups (lifecycle, offering, prospectus, risk factors, financials, filing chain) and even clarifies interpretation of missing fields. The tool is simple (one input), so this seems sufficiently 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?

The only parameter, cik, is fully described in the schema (CIK with or without leading zeros). The description adds a minor contextual note that the CIK comes from GetIpoFeed, but this does not alter the schema's meaning. Since schema coverage is 100%, 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 'Get one S-1/F-1 registration's full picture by the filer's SEC CIK (as listed by GetIpoFeed)', which clearly specifies the verb, resource, and differentiation from the list-oriented GetIpoFeed. The enumerated output categories (lifecycle status, offering classification, financials, filing chain) make the tool's purpose unmistakable.

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

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

It explicitly references GetIpoFeed as the origin of the CIK, implying the intended workflow of listing IPOs first and then retrieving details for a specific filer. While it does not state 'use this instead of X' or provide exclusions, the context is clear enough for an agent to understand when this tool applies.

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, so the description doesn't need to cover safety. It adds valuable behavioral context by explaining that terms come from the newest effective prospectus or latest filing and never a superseded document, and by listing result contents (lifecycle, proposed listing, offer terms, XBRL financials). This goes beyond what annotations provide, though it doesn't mention operational limits like rate limits or pagination.

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, front-loaded with the core purpose, and each sentence contributes new information. It is dense but not verbose, effectively covering scope, data provenance, result contents, filtering, and sibling routing without redundancy. It earns a 4 for good structure and conciseness.

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 sufficiently describes the result content (lifecycle, proposed listing, offer terms, financials) and provides filtering guidance, plus routing to GetIpoDetails. For a read-only tool with three optional parameters, this covers what an agent needs to call it correctly, including data selection logic and output variety.

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 (limit, status, filerType) already documented. The description adds minimal parameter-specific detail—it mentions filtering by lifecycle and SPAC vs operating, which aligns with status and filerType, but doesn't elaborate on allowed values or formats beyond the schema. With full schema coverage, a 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 clearly states the tool's purpose: getting the US S-1/F-1 registration pipeline with newest filing activity first. It specifies the resource (US S-1/F-1 registrations), the verb (Get), and differentiates from the sibling GetIpoDetails by explicitly routing users to it for filing chains. The scope and unique behavior are 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?

The description tells users when to use this tool (to obtain the registration pipeline) and explicitly directs them to GetIpoDetails for detailed filing chains using a CIK from this tool. It also notes filtering options (lifecycle, SPAC vs operating), giving clear context for selecting this tool over alternatives.

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 explains semantic nuances beyond the readOnlyHint/destructiveHint annotations: what 'Short %' means, a normal market-making baseline (40-50%), and clarifies that this is not short interest. It also discloses the default date behavior, sort order, and data source. 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 information-dense sentences cover the core purpose, clarify a potentially confusing metric (short % vs short interest), and provide usage guidance. The main action is front-loaded, and every clause adds value 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?

For a read-only ranked list tool, the description is complete: it states the data source, default date, sort ordering, output semantics, and when to use alternatives. No output schema is present, but the description sufficiently implies the return shape (a sorted list of stocks with volume/short % metrics) for reliable 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 parameters are already well-documented. The description adds contextual guidance for sortBy and minTotalVolume (e.g., the need for a floor when using shortPercent), but it does not deeply elaborate on each parameter beyond what the schema provides. 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 uses a specific verb ('Get') and clearly identifies the resource: stocks with the largest daily short sale volume for a single trading day, sourced from FINRA. It explicitly distinguishes this from sibling tools like GetShortVolume and GetShortInterest, making the tool's unique purpose 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?

The description provides explicit guidance on when to use this tool versus alternatives, naming GetShortInterest/GetShortInterestSnapshot for positions, GetShortSqueezeScores for squeeze candidates, and GetShortVolume for single-stock history. It also gives a concrete usage tip for ranking by shortPercent with a minTotalVolume floor.

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 known. The description adds meaningful behavioral context: it specifies the report is the legacy futures-only COT report, the data timing (as of Tuesday, published Friday), and the grouping by category. This goes beyond annotations and gives agents a clearer picture of what the data represents, though it does not discuss pagination or error handling.

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 with no fluff. The main purpose is front-loaded ('Get the latest COT positioning snapshot'), and the subsequent sentence provides essential details (data type, source, timing, and cross-reference to a sibling). Every clause 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?

For a tool with one optional parameter and no output schema, the description covers the core aspects: what data is returned (net positions), grouping, the report vintage, and a cross-reference to the market code. It does not describe the exact row structure or whether all rows are returned, but given the simplicity of the tool and existing annotations, the information is sufficient for an agent 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?

The single parameter (category) is fully documented in the schema (100% coverage), so the description adds no additional semantic value beyond the schema. The listing of categories in the description is redundant with the schema's enum-like list, so the baseline score 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 clearly states the tool retrieves the latest COT positioning snapshot across all tracked futures contracts, grouped by category, and specifies the data type (commercial/non-commercial net positions). It implicitly differentiates from GetCftcPositioning by referencing the market code accepted by that tool, but does not explicitly state the boundary (e.g., 'this returns all; GetCftcPositioning returns a specific market').

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