TipRanks

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

Beyond annotations that mark it read-only and idempotent, the description discloses regeneration behavior ('reports regenerate on new earnings or a significant price move'), the meaning of an older as_of date, and how missing reports are handled (not_covered vs no_report_from_provider). It also explains that detail is ignored on multi-ticker calls and that consensus.reports_dated appears only when model runs differ.

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 structured with a lead definition, usage bullets, caveats, field explanations, and an Args/Returns breakdown. While long, each section serves a purpose for a tool with complex return variations; it is slightly repetitive with the schema but well-organized and 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?

The absence of an output schema is compensated by a detailed 'Returns JSON' block defining ai_score, consensus, upside_pct, as_of, and the coverage edge cases. The description covers what the score is, how to request it, what the fields mean, and how missing coverage is reported, making the tool fully usable without external docs.

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 Args section largely restates the schema's descriptions, e.g., tickers max 25 and provider's 'Omit for the headline score' line. No new parameter semantics beyond the schema are added, so the baseline 3 applies.

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

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

The description opens with 'TipRanks AI Stock Analysis — the 0-100 AI score for one or more stocks' and details the six frontier models contributing scores. It explicitly distinguishes this from the Smart Score sibling, stating 'This is NOT the Smart Score (1-10, eight quantitative factors)', making the tool's specific purpose and 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?

The description provides explicit 'Use for:' examples and advises passing all tickers in one call for watchlist/ranking queries. It excludes ETFs and explicitly differentiates the tool from Smart Score, giving the agent clear when-to-use and when-not-to-use guidance relative to 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds significant behavioral context: it discloses that several symbols are non-mnemonic and instructs using the display name in the response. It also details the response fields (display name, changePercentage derived from price and change, raw price, change, volume). This is valuable operational guidance not present in 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 and well-structured: the first sentence states the core purpose, and the second paragraph provides a crucial caveat about symbols. Every sentence earns its place without 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?

Given zero parameters and no output schema, the description compensates by explaining exactly what the response contains (display name, changePercentage, raw price, change, volume) and the non-mnemonic symbol issue. This is complete for a simple list-all tool and leaves no critical ambiguity about the return data.

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

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

The tool has zero parameters, so the baseline is 4 as per guidelines. The description does not need to add parameter semantics since the schema is empty; the focus shifts to output semantics, which it covers.

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 real-time quotes for all commodities in a single request, using a specific verb ('Returns') and resource. It distinguishes itself from siblings like get_commodity_quote (which likely returns a single quote) and get_commodity_historical by emphasizing the 'all commodities' 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 implies usage through 'in a single request', suggesting this is for bulk retrieval rather than individual calls, but it does not explicitly state when to use this tool versus alternatives like get_commodity_quote or get_commodity_historical. It lacks explicit exclusions or recommended alternative 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?

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: the 4,771-coin feed is alphabetically stored but returned by market cap, the response reports how many coins were left out, and `volume` is venue-specific and not comparable across coins. This is exactly the kind of insight annotations 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?

Though longer than average, every sentence earns its place: the lead sentence states purpose, the next explains scaling and alternatives, then caveats about `note` and `volume` are given, and an Args section wraps up. It is well-structured and front-loaded without filler.

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

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

With no output schema, the description compensates by describing key response elements: display names, slice size ('note'), left-out count, and the non-comparable `volume` field. For a two-parameter, read-only list tool, this is complete enough for an agent to use correctly and avoid summarisation errors.

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 both parameters with descriptions, defaults, maximums, and interactions, so schema coverage is 100%. The description paraphrases 'symbols overrides the ranked slice' and 'limit is how many ranked coins to return,' but adds no new semantic value 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 provides real-time crypto quotes and explicitly distinguishes from the singular get_crypto_quote tool by saying 'or call get_crypto_quote for a single one.' It also differentiates by asset class and market-cap ordering, making its scope unambiguous.

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

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

It gives explicit usage guidance: use `symbols` for specific coins or call get_crypto_quote for a single one, and warns to read the `note` before summarising to avoid misrepresenting the slice as the whole market. This goes beyond mere context and directly tells when to use this tool 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses crucial behavioral quirks: the feed has 1,550 pairs but returns a limited slice, the response states how many were left out, and 'volume on a forex row is a per-venue tick count, not market turnover... It does not rank the market.' This is significant context 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?

The description is front-loaded with the core purpose, then each paragraph addresses a distinct, necessary concern: the oversized feed and limit, the note field, the volume caveat, and parameter summaries. Every sentence earns its place—there is no filler or repetition of the schema.

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

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

Given that there is no output schema, the description does a thorough job of explaining what to expect: a ranked slice, a note indicating coverage, and the caveat about volume. It also covers the main alternatives and data limitations, making it complete for an agent to decide when and how to call the 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 schema already provides full description coverage for both parameters, so the baseline is 3. The description adds value by explaining why `limit` exists (the feed exceeds response capacity) and how it interacts with `symbols` (symbols overrides the ranked slice), plus the significance of the `note` field in interpreting the result. This goes beyond the 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 opens with 'Real-time forex quotes: the most-traded pairs, each with a display name,' which clearly identifies the resource (forex quotes) and the specific scope (most-traded pairs, with display names). It distinguishes itself from sibling tools by explicitly mentioning 'call get_forex_quote for a single one' and by its focus on a ranked overview versus other asset-class quote 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 provides explicit usage guidance: 'Pass `symbols` for specific pairs, or call get_forex_quote for a single one.' It also explains when the ranked slice is appropriate versus using symbols, and warns to 'Read `note` before summarising' to avoid misrepresenting the data coverage. This effectively tells an agent when to use this tool and what to watch out 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds valuable behavioral details: case-insensitive substring matching, deduplication by analyst name keeping best rank, sort order, and the output shape change when sector is provided. This significantly enriches the agent's understanding.

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, beginning with the core action, then output format, behavioral rules, and parameter details. It is information-dense without redundancy—every sentence provides necessary context.

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

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

With only two simple parameters and no output schema, the description is complete: it explains return row structures for both with/without sector, matching behavior, deduplication, and sorting. An agent can confidently invoke this tool without further clarification.

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 only provides names and defaults, but the description adds substantive meaning: firm is a case-insensitive substring (with example matching 'Goldman' to 'Goldman Sachs'), sector is optional lowercase and affects the result row shape. This fully compensates for the 0% schema description 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's function: 'List analysts at a given firm' with specific output rows. It distinguishes from sibling tools by focusing on firm-based analyst listing, which is unique among the many get_* 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 clearly implies when to use it—when you need analysts for a firm. It does not explicitly compare to alternatives like get_recent_analyst_ratings, but provides clear context and parameter guidance, satisfying the 'clear context, no exclusions' level.

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 idempotentHint=true, which covers safety. The description adds non-obvious behavior: HTML-stripped text, an 8000-character cap, and a JSON error response when no matching article exists. This goes beyond annotations and helps 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 compact (~80 words), front-loaded with the core purpose, and structured with Args/Returns sections. Every sentence adds useful information; 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?

For a single-parameter read tool with no output schema and strong annotations, the description is fully complete. It covers input types, the exact return fields, the 8000-character limit, and the error behavior — everything an agent needs to invoke and interpret the result.

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

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

Schema coverage is 100% and the schema already describes the identifier as numeric post id, slug, or full tipranks.com URL. The description echoes this and adds the source hint (from get_latest_news / get_assets_news), which is slight added value but not substantial 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 opens with a specific verb+resource: "Fetch the full text of a single TipRanks article." It clearly distinguishes this from sibling news tools like get_latest_news and get_assets_news by focusing on resolving a single article identifier to its full content.

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 by stating the identifier can come from get_latest_news / get_assets_news, implying when to use this tool. It also notes an exclusion (URLs to aggregated third-party sites are not stored), which counts as a when-not. However, it does not explicitly name alternative tools for those excluded cases, 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 mark readOnlyHint=true, destructiveHint=false. The description adds orthogonal behavioral details: response size is 'tuned to stay small enough for a whole portfolio,' floats are rounded, dates are day-resolution, and it instructs agents to 'quote daysUntilEarnings rather than computing the gap.' 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?

Although long, the description is well-structured: a one-sentence summary, input format, return wrapper, and a bulleted field list. Every line adds value—required to document the many output fields. Front-loaded with the core purpose and followed by logically grouped 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?

Given one parameter and no output schema, the description covers everything: input format, full field semantics, return structure, and guidance on when to use sibling tools. It is complete enough for an agent to invoke and interpret results without additional lookups.

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 only says 'tickers' is string or array with no description (0% coverage). The description compensates fully: 'a comma-separated string ("AAPL,MSFT,C") or a JSON array (["AAPL","MSFT","C"]). Both are accepted.' This adds crucial format details 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 opens with a clear, specific statement: 'Returns key TipRanks stock data for one or more tickers.' It enumerates the fields returned, distinguishing it from sibling tools by describing it as a compact portfolio-level summary.

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 not to use: 'For deeper per-ticker detail ... use the dedicated tools (get_stock_prices, get_hedge_fund_holdings, get_insider_transactions, get_financials, ...).' This gives clear alternatives and context for when the 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 readOnly/idempotent/non-destructive, and the description adds meaningful context about the returned event types (dividend, earnings, coupon) and date parameter semantics. 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 a compact, front-loaded docstring with a one-line summary followed by clear Args and Returns sections. Every sentence provides necessary information with no 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 simple read-only tool with no output schema, the description is complete: it explains what the tool returns (dividend, earnings, coupon dates), what inputs are required, and the optional date range format. No critical gaps remain for an agent 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?

With 0% schema description coverage, the description compensates by documenting tickers as comma-separated symbols and from_date/to_date as optional ISO-format dates. It adds format and optionality semantics beyond the raw schema, though it does not mention the array alternative for tickers.

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 'Returns upcoming dividend and earnings events for tickers,' using a specific verb, resource, and scope. It distinguishes itself from sibling historical/earnings tools by emphasizing per-ticker upcoming events and coupon dates.

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: use for upcoming dividend/earnings/coupon events for specified tickers, with optional date range filtering. It does not explicitly name alternatives or exclusions, but the use case is 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, openWorldHint, idempotentHint, and non-destructive nature. The description adds significant context beyond annotations: it explains the tool returns only headlines (no article body), that from_date only trims the recent set rather than pulling older articles, and details the redundant date fields, specifically advising to prefer publishTime over addedOn. This is rich behavioral context with no contradictions.

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

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

The description is longer than average but well-structured with 'Args' and 'Returns' sections. The opening sentence immediately conveys the core purpose, and subsequent lines provide necessary detail about behavior, usage limits, and return fields. Some redundancy in listing return fields could be trimmed, but every sentence contributes meaningful information, so it earns a 4 rather than a 5.

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

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

The tool has no output schema, so the description fully documents the return structure including the assetNewsArticles container and all fields: ticker, companyName, sentiment bucket, siteName, url, title, and date variants. It also explains the sentiment classifier, the meaning of addedOn vs publishTime, and the tool's limitation to current news. This is complete for a news-retrieval tool with no output schema.

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

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

Schema description coverage is only 33% (only from_date has schema-level description), so the description must compensate. It does so by explaining 'tickers' as comma-separated symbols, 'count' as number of articles with default 10, and 'from_date' as a recency floor with format and behavioral nuance. Minor mismatch: schema allows tickers as array, but description says comma-separated only, slightly limiting the semantics. Overall adds strong value beyond 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 opens with a specific verb and resource: 'Returns recent news articles for tickers, aggregated from many news sites, each with a sentiment tag and source URL.' It also explicitly distinguishes itself from get_latest_news, stating this tool is for ticker-specific news and headlines only, which clearly separates it from siblings.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'For general/market TipRanks news without a specific ticker, or for an article excerpt, use get_latest_news.' It also clarifies the tool's limitation to the current news window and instructs to use get_latest_news with from_date + to_date for past date ranges, giving clear 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 already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the return includes warning type, date, and detail fields, which is useful but does not go beyond what annotations already establish.

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 and well-structured: a one-sentence purpose, then Args and Returns sections. No unnecessary words or repetition, and it is front-loaded with the primary purpose.

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 tool with one parameter and no output schema, the description provides the essential return fields (warning type, date, detail). It could be more explicit about the array type acceptance, but overall it is sufficiently complete for the tool's 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?

The description says tickers are comma-separated ticker symbols, but the schema allows both a string and an array of strings. This is incomplete and potentially misleading, as an agent may not realize an array is also accepted, though it does add some meaning beyond the bare 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 returns risk warnings for tickers. It uses a specific verb ('Returns') and distinct resource ('risk warnings for tickers'), distinguishing it from sibling tools like get_assets_data and get_assets_events.

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 no guidance on when to use this tool versus alternatives. There is no mention of suitable contexts, exclusions, or comparisons to sibling tools, leaving the agent to infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds ranking criteria and a max of 25 results, but does not disclose error behavior or whether results are sorted ascending/descending beyond the stated ranking.

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 short sections: a purpose line and a parameter list with defaults and constraints. No fluff, front-loaded purpose, easily skimmable.

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

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

For a simple read-only query with two optional parameters and no output schema, the description covers what it returns and how to call it. It doesn't specify the return structure, but that's not critical for this simple 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?

For expert_type, the description repeats the schema's allowed values, but for num it adds the max 25 constraint that the schema lacks. This compensates for the schema's 50% coverage and clarifies usage.

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?

Clearly states it returns the best-performing experts ranked by TipRanks success rate and average return, which is specific and distinguishes it from sibling tools like get_analysts_by_firm or get_top_rated_stocks.

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

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

No guidance on when to use this tool versus alternatives. It does not mention exclusions or provide context such as 'use this for leaderboard rankings' or 'not for detailed analyst profiles'.

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 idempotentHint=true, so the safety profile is covered. The description adds context about the return structure (consensus and articles) and parameter constraints (limit default 20, max 50), exceeding what annotations provide.

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

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

The description is well-structured with a clear purpose statement, sibling differentiation, and organized Args/Returns sections. Every line provides useful information without fluff 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?

The tool is simple (2 params, no nested objects), and the description covers purpose, parameters, and return structure in detail. No output schema exists, but the description outlines the exact JSON shape, making the tool's behavior fully transparent.

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

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

Schema description coverage is 0%, but the description fully compensates by explaining both parameters: ticker with an example ('AAPL') and limit with default and max values. This gives the agent complete understanding of how to invoke the tool.

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 financial-blogger consensus for a stock plus underlying articles, which is specific and distinct from siblings. It explicitly names get_recent_analyst_ratings and get_investor_sentiment as different, ensuring no ambiguity about 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 explicitly distinguishes this tool from two related sibling tools, explaining what each alternative covers (Wall Street analysts vs. TipRanks crowd positioning). This gives the agent clear guidance on when to choose this tool over similar ones.

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, idempotentHint=true, and destructiveHint=false, covering safety. The description adds behavioral context by explaining the discrete sentence-bullet format and the exact JSON return structure (ticker, updatedOn, bullish, bearish, key_points). It does not discuss auth/rate limits, but for a read-only list tool with these annotations, this is adequate and adds value 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 structured with sections for Args and Returns, using bullet-like formatting for clarity. It is longer than the TDQS high bar but still efficient; the returns section is lengthy but necessary since there is no output schema. No redundant fluff, though the opening sentence is slightly verbose.

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?

Since there is no output schema, the description carries full burden for return values and does so thoroughly: it gives the JSON structure, per-ticker fields, and the nested key_points with sentiment/topic/point. It also covers the parameter format. For a read-only data retrieval tool, this is complete enough for an agent to invoke and parse the result.

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

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

The input schema has 0% parameter description coverage, so the description must compensate. It explains the tickers arg as 'Comma-separated tickers (e.g. 'AAPL,TSLA')', giving a concrete format and example. However, it does not mention that an array is also accepted per the schema, which is a minor gap but still adds substantial 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 clearly states it returns 'the discrete bull and bear key points for stocks' with a specific resource (TipRanks stock pages) and detailed output structure. This distinguishes it from sibling tools like get_ai_stock_analysis or get_stock_quotes, which serve different purposes.

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

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

The description implies usage (when you need bull/bear key points for stocks) but gives no explicit when-to-use vs alternatives, no exclusions, and no mention of preferred contexts. It is not misleading, but guidance is only implicit.

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, which the description does not contradict. Adds useful behavioral context: cross-market results are sorted by dollar amount, a company may appear multiple times for different fiscal quarters, and per-ticker returns are chart-ready time series.

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

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

The description is well-structured with clear sections for modes, arguments, and returns. Every sentence adds value, and the formatting makes it 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?

Since there is no output schema, the description provides comprehensive return field details for both modes, including example field names and the chart-ready nature of per-ticker data. It covers all parameters and operational modes thoroughly.

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?

Description fully explains each parameter beyond the schema. It clarifies that limit and page are cross-market-only with defaults and max, and that ticker determines mode. This compensates for the sparse 33% schema description 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?

States 'Returns share-buyback / stock-repurchase activity' with two distinct modes, making the tool's purpose clear. It clearly distinguishes from sibling get_* tools by focusing specifically on buyback/repurchase data.

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 provides example queries for each mode: 'biggest buybacks', 'top repurchase companies' for cross-market, and 'AAPL buyback history', 'MSFT repurchase trend' for per-ticker. Also specifies when to omit versus provide ticker, giving clear directional guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context beyond annotations: a fixed window ('today − 14 days to today + 60 days'), sorting ('by date ascending'), and the exact return structure. While it does not discuss error handling or rate limits, the added details meet the lowered bar set by 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 compact and well-structured: a one-sentence summary, a sentence on the fixed window and sorting, a sentence on intended use, and a formatted return layout. Every sentence earns its place with no fluff 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 its simplicity (no parameters, no output schema), the description is fully self-contained. It communicates the purpose, the exact data window, the ordering, the intended application, and the shape of the returned array. Nothing essential is left unexplained for the agent to invoke the tool successfully.

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

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

The tool has zero parameters, so the schema is trivially 100% covered. Per the rubric, 0 params earns a baseline of 4. The description does not need to explain parameters and instead clarifies the fixed data scope, which is the only relevant input detail.

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

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

The description begins with a specific verb 'Returns' and names the exact resource: 'FDA / clinical-trial calendar — upcoming drug approval target dates and the tickers behind each drug.' This clearly differentiates from sibling calendar tools like get_earnings_calendar or get_economic_calendar by specifying the domain and content.

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 use cases: 'Use for upcoming FDA decisions, PDUFA dates, biotech catalysts.' This gives clear context for when to select this tool, but does not explicitly state when not to use it or name alternative tools, so it falls one point short of full guidance.

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

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

Annotations already mark this as read-only/idempotent, but the description adds substantial behavior beyond that: automatic aggregation into coarser OHLC bars for long ranges, absence of `vwap` in aggregated bars, chart-ready ordering, and the semantics of `summary` being computed from the full requested window. 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 longer than average but every section (purpose, aggregation, summary, args) adds unique value. It is front-loaded with the core purpose and uses paragraph breaks effectively, though the interval explanation could be tightened.

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 shape (fields, ordering, aggregation), the meaning of `summary`, and important edge cases like the 52-week distinction. It is 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 coverage is low (33%), but the description compensates by documenting all three args with formats ('YYYY-MM-DD') and an example symbol. However, it also references an `interval` concept that does not appear in the input schema, which could confuse—though it does explain how interval affects bar structure.

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 action and resource: 'Daily OHLC price history for a commodity, covering the whole date range you ask for.' It clearly distinguishes itself from the sibling quote tool by noting 'For the current level alone, call get_commodity_quote.'

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

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

Explicitly names an alternative for current prices ('For the current level alone, call get_commodity_quote'), advises requesting a narrower date range for daily rows, and clarifies when to rely on `summary` for claims like 'a year ago'. It also warns against conflating window high/low with 52-week quote fields.

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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds context about real-time data and lists common symbols, but it doesn't disclose potential latency, data source, or error behavior for invalid symbols. This is adequate but not rich given 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 two concise sentences plus an Args line. It is front-loaded with the primary purpose, followed by the symbol list. Every sentence serves a purpose with no redundancy or filler.

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

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

Given the tool's simplicity (one parameter, no nested objects), the description covers the essential purpose, input, and scope. With good annotations and no output schema, the lack of return-value details is acceptable for a quote tool. The only notable gap is explicit mention of alternatives, but the context 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 a description with two examples, and the description expands on this with a list of six common symbols (GCUSD, SIUSD, CLUSD, etc.), which is helpful for selecting valid inputs. Since schema coverage is 100%, the added symbol list is a meaningful enrichment 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 'Returns the real-time price quote for a specific commodity' with a specific verb, resource, and scope. It distinguishes from siblings like get_all_commodities_quotes (all vs. specific) and get_commodity_historical (real-time vs. historical) by explicitly qualifying 'specific commodity' and 'real-time'.

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

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

Usage is implied by the phrase 'specific commodity' and the provided symbol list, but there is no explicit guidance on when to use this over get_all_commodities_quotes or get_commodity_historical. No alternatives are mentioned, so the agent must infer the appropriate context from the name and description.

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, idempotentHint, openWorldHint, and non-destructive. The description adds valuable behavioral context: the data is large (history back to 2014), the default limited to recent periods, and the exact return structure. This goes beyond what annotations provide and outlines expected behavior.

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

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

The description is concise and well-structured: a clear purpose sentence, a brief note on data size and defaults, the Args list, and the return format. Every sentence adds meaningful information 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?

Given the lack of an output schema, the description provides a complete return format with nested structure. It covers all three parameters, default behavior, and return fields, making it self-sufficient for an AI agent to understand what the tool does and what it will return.

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

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

Schema description coverage is only 33% (only 'group' has a description), but the description's Args section explains all three parameters including default count (8), max count (40), the special value 0 for full history, and that group accepts slug or title. This fully compensates for the schema gaps and adds crucial semantics.

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

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

The description clearly states the tool 'Returns company-specific operational KPIs' and lists concrete examples (segment revenue, geographic breakdown, active users/devices, gross margins by type, opex breakdown). This specific verb+resource combination distinguishes it from sibling tools like get_financials or get_earnings_*.

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 use the tool: it explains the default behavior (most recent count periods), when to use count=0 for full history, and how to fetch a single group with the group parameter. However, it does not explicitly mention alternatives or when-not-to-use this tool versus siblings, hence 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, idempotentHint, and non-destructive behavior. The description adds substantial context beyond annotations: it explains aggregation behavior for long ranges, the meaning of summary fields, the absence of vwap in aggregated bars, and distinguishes windowHigh/Low from 52-week figures. This is a model of 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 long but structured logically, with the core purpose in the first sentence and important behavioral details in separate paragraphs. Every sentence adds useful information, but it could be tightened (e.g., the example row schema and repeated caution about summary might be condensed) without losing 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?

There is no output schema, so the description must explain return values. It thoroughly describes the daily row fields, aggregated bar fields, the summary structure, and how to interpret them. It also covers edge cases like over-long ranges and differences from quote-tool fields. The tool's complexity is fully addressed.

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 only documents the symbol parameter; from_date and to_date appear without descriptions and with defaults. The description compensates by explicitly listing all three parameters with explanations (e.g., 'Start date YYYY-MM-DD (optional)') and clarifying that the range is 'the whole date range you ask for.' It adds meaning beyond the schema, though default behavior when dates are omitted is not stated.

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 provides 'Daily OHLC price history for a cryptocurrency' with a specific resource and scope. It differentiates itself from get_crypto_quote by noting it returns historical data, not just the current level, and also distinguishes from other historical tools by specifying crypto-specific behavior.

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 instructs when to use this tool versus alternatives: 'For the current level alone, call get_crypto_quote.' It also provides guidance on when to request a narrower date range to get daily rows instead of aggregated bars, and clarifies how to use summary for claims like 'starting price' or 'a year ago.' This is exemplary 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds behavioral context beyond annotations: order ('ordered newest-first'), scope ('market-wide across all coins'), and returned content ('article headlines, snippets, and source URLs'). It repeats safety traits ('Read-only, no side effects') but adds useful ordering and scope details. 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?

Description is two short paragraphs: the first delivers the core meaning in one sentence, the second gives precise usage guidance with named alternatives. No redundant or filler content.

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

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

For a simple read-only news feed with one optional parameter and no output schema, the description covers scope, ordering, return fields, and use cases. Parameter semantics are fully handled by the schema. No significant gaps.

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

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

The single parameter 'page' is fully described in the schema with '0-indexed page of recent articles (0 = most recent); increase to page further back in time.' Since schema coverage is 100%, the description does not need to restate it; baseline 3 applies.

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

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

Description clearly states 'Latest cryptocurrency news — a market-wide feed across all coins (not filtered to a single asset), ordered newest-first: article headlines, snippets, and source URLs.' It specifies the resource (crypto news), scope (all coins), and output elements, and explicitly distinguishes from sibling tools get_assets_news and get_latest_news.

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 direct usage guidance: 'Use for broad crypto/market headlines. For news about a specific holding use get_assets_news; for the general (non-crypto) editorial feed use get_latest_news.' This names exact alternatives and conditions for use.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by clarifying the real-time nature and listing common symbol mappings, which is 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 concise and front-loaded with the core purpose. The list of symbols is helpful, though the 'Args:' section redundantly restates schema information. No fluff or unnecessary 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?

For a simple one-parameter tool with strong annotations, the description is complete. It covers what the tool does, what inputs are needed, and gives practical examples. No output schema is present, but the description sufficiently conveys the return type.

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 describes the symbol parameter, but the description expands on it with a list of common symbols and their full names, providing additional semantic value 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 it returns the real-time price quote for a specific cryptocurrency, using a specific verb and resource. It distinguishes itself from siblings like get_all_crypto_quotes by emphasizing 'specific'.

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

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

The description implies when to use this tool (need a single, real-time quote) but does not explicitly mention alternatives like get_all_crypto_quotes for multiple quotes or get_crypto_historical for historical data. No exclusions are provided.

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 read-only/idempotent, and the description adds significant behavioral context: output structure, yield percentage format (4.5 = 4.5%), per-payment list capped at 'count', and annual_totals always returned in full. 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 well-organized: purpose first, then output structure, then yield encoding, use cases, and argument details. Every sentence adds value, and the formatting with headings/paragraphs makes it easy to scan.

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

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

Given no output schema, the description thoroughly explains the return shape (snapshot, per-payment list, annual totals) and edge behavior (count cap, yield percentages). It sufficiently covers the tool's functionality for an agent to select and invoke it correctly.

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

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

Schema coverage is 0% with no descriptions for ticker or count. The description compensates by explaining ticker with examples and count with default (16) and max (100), plus the effect on annual_totals. This adds meaningful semantics 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 explicitly states 'Dividend payment history for a ticker' and details the output components (current snapshot, per-payment list, annual totals). This clearly distinguishes it from siblings like get_stock_splits or get_earnings_history.

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 usage examples ('Use for: AAPL dividend history', 'yield trend over 5 years') and describes the nature of the data. However, it does not explicitly mention when not to use this tool or direct users to alternative tools, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, which cover safety. The description adds the date default behavior (today to 14 days) but does not disclose additional traits like rate limits, data freshness, or pagination. With annotations present, this is adequate but not extra-rich.

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 lines plus a concise argument list. The first sentence states the purpose, and the argument list is neatly formatted with defaults and examples. No word wasted.

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

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

Despite no output schema, the description tells the agent what to expect: 'upcoming earnings dates'. For a simple filtered-list read-only tool with good annotations, this is sufficient context. The date defaults and exchange filter are documented, making the tool 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 0%, so the description carries full responsibility. It explains each parameter: fromDate (format YYYY-MM-DD, default today), toDate (format, default 14 days), and exchange (optional, with example 'US'). This fully compensates for the schema gap.

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

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

The description clearly states the tool returns 'upcoming earnings dates across all stocks for a date range', using a specific verb and resource. It distinguishes from sibling tools like get_ticker_earnings (which is likely stock-specific) and get_economic_calendar (which covers macro events), so purpose clarity is high.

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 scope context ('across all stocks', date range) and the optional exchange filter, implying when to use it. However, it does not explicitly name alternative tools or state when not to use it, earning a 4 rather than 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, idempotentHint=true, and destructiveHint=false. The description adds beyond these by noting it's a structured summary (not raw transcript), that only the most recent quarter is stored, and that highlights are 'AI-extracted', implying potential unreliability. This is useful context but doesn't cover failure modes or rate limits.

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

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

The description is front-loaded with the core purpose and each sentence adds value: content, usage guidance, sibling differentiation, and parameter/return details. No filler or tautology; structured with Args and Returns for clarity.

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, the description is complete: it explains input, output format, data scope, and limitations (only most recent quarter). It even provides the return JSON structure, so no separate output schema 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 coverage is 0%, so the description fully compensates. The Args section explains 'ticker' with concrete examples ('AAPL', 'NVDA') and clearly states it's a stock ticker. The return structure is also described, making the parameter's purpose unambiguous.

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 the most recent earnings call summary for a ticker, enumerating specific components (guidance, sentiment, highlights, lowlights). It distinguishes itself from raw transcript and sibling tools like get_earnings_history.

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 use cases are provided (e.g., 'what did management say about X', 'was the call bullish or bearish'). It directly names an alternative (get_earnings_history) for historical EPS series, giving clear when-to-use vs. when-not-to guidance.

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

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

Annotations already mark this as read-only/idempotent; the description adds chart-readiness, oldest-first ordering, field lists, and next_quarter metadata, enriching the behavioral contract with no contradictions. This is a strong addition 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 longer than average but well-organized: overview, data shape, next_quarter, use cases, and args. No fluff; each section adds distinct value, and the structure makes it easy to scan.

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 describes the return rows and ordering, making it self-contained for an agent to predict output. It also covers the optional quarters parameter behavior, leaving little ambiguity.

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 only lists types and a default; the description compensates by documenting both parameters, specifying ticker format and the quarters default (8) and maximum (40), filling the 0% schema coverage gap completely.

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 'Quarterly earnings time series for a ticker,' a specific verb+resource statement, and later lists concrete use cases like 'AAPL earnings history' and 'EPS beat/miss the past 4 quarters,' clearly distinguishing it from sibling earnings tools like get_earnings_calendar.

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 'Use for' section provides explicit query examples that signal when to invoke this tool, but it does not name alternatives or exclusion criteria, so it falls short of the full 'when-not' guidance. The examples are enough to place it in context, but explicit exclusions would push to 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. The description adds valuable behavioral context by explaining why default filters exist and how the raw feed is noisy, helping agents understand the need to adjust filters for broader results. 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?

Well-structured with a one-sentence purpose, a concise rationale, a clean Args list, and a Returns line. Every line is informative and there is no fluff or repetition of schema fields.

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

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

Despite having 7 parameters and no output schema, the description covers all parameters, defaults, filter behavior, and the return shape ({ totalMatched, returned, filters, economicCalendar }). It provides enough information for an agent to call the tool correctly without additional documentation.

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

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

Schema coverage is only 29%, but the description thoroughly documents all 7 parameters, including defaults, valid values, and the alternative relationships between daysBack/fromDate and daysForward/toDate. This fully compensates for the schema gaps and goes beyond basic definitions.

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

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

The description uses a specific verb ('Returns') and resource ('economic events') with concrete examples (Fed meetings, jobs reports, CPI, GDP), clearly distinguishing it from sibling tools like earnings or IPO calendars.

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

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

The description explains default behavior ('Defaults to US events at High/Medium impact only') and the rationale (raw feed includes hundreds of low-impact items), providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or point to alternatives, so it misses the highest bar.

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 idempotentHint true, and destructiveHint false, establishing safety. The description adds meaningful context by explaining that the consensus is computed as a weighted average of holdings' ratings, which is a 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?

The description is concise, with two sentences plus an Args block. It front-loads the core purpose and gives an example without unnecessary detail. 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?

This is a low-complexity tool with one parameter and no output schema. The description covers the purpose, parameter format, and methodology, which is sufficient for basic usage. It does not describe the response format, but that gap is somewhat acceptable given the absence of an 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 schema provides no description for the 'tickers' parameter, so the description compensates by specifying 'comma-separated ETF tickers' with an example (QQQ,SPY,VTI). However, it only mentions the string form and omits the array alternative allowed by the schema, and does not specify any constraints like limits.

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 returns analyst consensus for ETFs based on a weighted average of holdings' ratings, providing a specific verb, resource, and methodology. This distinguishes it from sibling ETF tools like get_etf_holdings or get_etf_exposures.

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

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

The description implies usage for ETF analyst consensus queries but does not explicitly mention alternatives or when not to use this tool. Differentiation from sibling tools is left to the user rather than being explicitly stated.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds behavioral details beyond these: sorting by holding market value (largest first), pagination behavior (page, page_size defaults and max 100), and the exact list of per-ETF fields returned. This enriches the annotation baseline without 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 well-structured with a clear one-sentence purpose, followed by an Args block and a Returns block. Every line adds useful information—parameter defaults, max page_size, and per-ETF fields—with no fluff 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?

The description covers inputs, outputs, sorting, and pagination completely. There is no output schema, so the detailed return fields are essential and provided. Given the tool's moderate complexity and strong annotations, no critical information 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 0%, so the description carries full responsibility. It explains each parameter: ticker with examples, page with default, page_size with default and max. This fully compensates for the lack of schema descriptions and adds practical usage guidance.

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 'Returns the list of ETFs that hold a specific stock, sorted by holding market value (largest first).' This uses a specific verb ('Returns'), identifies the resource (ETFs holding a specific stock), and distinguishes it from sibling tools like get_etf_holdings (which likely lists holdings of a given ETF) and get_etf_top_stocks.

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 a clear use case: finding which ETFs hold a given stock, with sorting and pagination details. However, it does not explicitly state when to use this tool over alternatives such as get_etf_holdings or get_etf_screener, nor does it mention exclusions. The context is clear but not explicitly differentiated.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds the output fields (consensus, price target, upside), which gives some behavioral context beyond the annotations. However, it does not discuss error handling, rate limits, or other behavioral nuances, so it remains at a moderate level.

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 very concise: one sentence stating purpose, followed by a clear Args section. It is front-loaded with the key information and contains no filler. 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 simple one-parameter read-only tool with no output schema, the description adequately covers the main purpose and expected return fields. It does not explicitly mention that only one ETF is processed at a time or define terms like 'upside', but the core information is sufficient for an agent to invoke the tool correctly.

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

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

The input schema only defines 'ticker' as a string with no description. The tool description compensates fully by explaining what ticker means and providing an example ('QQQ'). This is clear and directly aids the agent in selecting and formatting 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 returns the analyst forecast for a specific ETF, listing consensus, price target, and upside. It uses a specific verb ('Returns') and resource ('analyst forecast for a specific ETF'), distinguishing it from sibling tools like get_etf_exposures or get_etf_screener.

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

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

The description implies the tool is for retrieving forecast data for a single ETF, which narrows its scope. However, it does not explicitly mention when to prefer this over related tools like get_etf_analysis or get_etf_holdings, nor does it provide exclusions. Usage context is present but not fully articulated.

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

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

With annotations already marking the tool read-only and idempotent, the description adds significant behavioral detail: the default-vs-top mode switch selected by `limit`/`sort_by`, and the explicit note that a negative or non-numeric `limit` is REJECTED rather than coerced to 0. This gives the agent an actionable model of how the tool behaves.

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

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

The description is front-loaded with the core purpose and then organizes modes into compact labeled paragraphs. Every sentence adds necessary information about selection, output fields, or error handling, 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?

With no output schema, the description compensates by listing the fields returned in each mode and covering the key error behavior. It is slightly incomplete around ambiguous combinations such as setting `sort_by` without a positive `limit`, and the sort_by value discrepancy leaves some residual uncertainty.

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

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

The description compensates for the sparse schema coverage by explaining `ticker`, the allowed `sort_by` values, and the meaning of `limit`, including the max of 50. However, it contradicts the schema's `sort_by` examples ('5d' vs 'prices.5d.gain'), which could confuse an agent about which values to pass.

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 clear verb and resource: 'List the constituents of an ETF,' and then details two modes, so an agent knows what the tool returns. It does not explicitly differentiate this from adjacent ETF tools such as get_etf_top_stocks or get_etf_exposures, leaving the agent to infer boundaries.

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

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

The description gives an explicit use case: 'Use the top-performers mode for questions like "which stocks in XLK rose most this week" without separately calling a screener.' This states when to use the mode, but it does not enumerate alternatives or explain when the base mode should not be chosen.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description goes beyond annotations by adding behavioral details: the default limit of 20 and max of 100, and the semantic quirk that `focus` functions as the sector filter since no dedicated `sector` parameter exists. This is genuinely useful context for correct invocation.

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, front-loaded with the tool's purpose, and organized as a clean Args block. Each parameter line earns its place by adding value beyond the schema, and the sector note is integrated naturally without padding.

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

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

For a simple read-only screening tool with no required parameters, the description covers all parameters, provides valid value hints, and states limits. The only minor gap is that no output schema exists and the description does not describe the return shape, but for a screener the implied result of a filtered ETF list is likely sufficient for an agent to proceed.

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?

Although schema coverage is 100%, the description adds meaning well beyond the schema. It enumerates valid assetClass values, gives representative category examples, and crucially explains how to use `focus` for sector questions, including a concrete example mapping 'tech ETFs' to InformationTechnology. This helps the agent pick correct parameter values where the schema only gives generic 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 opens with a specific verb and resource: 'Filters ETFs by asset class, category, and focus.' This clearly identifies the tool as a screening/filtering operation and distinguishes it from sibling ETF tools like get_etf_analysis, get_etf_holdings, and get_etf_exposures by emphasizing screening dimensions rather than retrieving a specific data slice.

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 usage guidance for one common scenario: 'Use this for a sector question' and maps 'tech ETFs' to InformationTechnology. It also states an important exclusion: 'the screener has no `sector` filter.' It doesn't name alternative sibling tools explicitly, but the when-to-use guidance is clear enough for an agent to select this tool over a generic ETF data 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns top stock holdings and analyst ratings but does not disclose additional behavioral details such as the number of holdings returned, sorting order, or pagination. This adds some value beyond annotations but lacks depth.

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 concise sentence followed by a brief Args line, with no redundant or filler content. Information is front-loaded and 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?

Despite strong annotations and a simple one-parameter schema, the description lacks crucial details about what 'top' means—such as the number of holdings or their ordering. With no output schema, the agent is left without complete information about the return structure, though the tool is inherently simple.

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 Args section in the description explains the single 'ticker' parameter as 'ETF ticker (e.g. 'QQQ')', providing meaning beyond the schema's bare property name. This compensates for the 0% schema description coverage, though it is still minimal and doesn't mention case sensitivity or format constraints.

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 the top stock holdings within an ETF along with their analyst ratings,' using a specific verb and resource. The qualifier 'top' and the addition of 'analyst ratings' distinguish it from sibling tools like get_etf_holdings, 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 implies usage when top holdings with analyst ratings are needed, but it does not explicitly state when to use this tool over alternatives such as get_etf_holdings. No when-to-use or when-not-to-use guidance is provided, so the usage context is only 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 state readOnlyHint=true and idempotentHint=true, but the description adds valuable behavioral conventions beyond that: margins are percentages ('49.27 means 49.27%'), cash outflows are negative numbers ('matching the source convention'), period ranges (~9 years annual, ~37 quarters), and ordering (oldest-first). These details are not in 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 is detailed but every sentence serves a purpose: overview, field enumeration, formatting conventions, use cases, and parameter docs. It is front-loaded with the core purpose, then structured logically. 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?

Without an output schema, the description must explain the return value and does so thoroughly: it lists the ~25 fields, describes the flat structure, explains the computed ratios, and documents all three parameters with defaults and constraints. The tool's complexity is fully addressed.

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

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

Schema description coverage is only 33% (only period has any description). The description compensates fully: explains ticker with examples, period with allowed values and data history lengths, and count with default, max, and ordering semantics. This adds meaning far beyond the raw 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?

Description opens with a specific statement: 'Financial statements time series for a ticker, chart-ready.' It names the resource (financial statements) and the action (get time series), and elaborates with a detailed field breakdown covering income statement, balance sheet, cash flow, and ratios, clearly distinguishing it from sibling quote/price 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?

Provides explicit 'Use for' examples that map to common user intents ('AAPL revenue and FCF over the last 10 years', 'show margins trend', etc.). It does not explicitly name alternatives or state when not to use it, but the specificity of the examples makes the intended scenario obvious.

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 readOnly/destructive annotations, the description discloses aggregation behavior (coarser OHLC bars for long ranges), missing vwap in aggregated bars, summary always covering the full window, and volume being a tick count rather than turnover. 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?

Though longer than typical descriptions, it is well-structured with clear paragraphs: overview, chart-ready, aggregation, summary, volume caveat, and args. Every sentence adds useful context, and it front-loads the primary purpose. No fluff or repetition.

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

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

With no output schema, the description fully explains return fields, aggregation behavior, summary structure, and volume semantics. It also covers edge cases like vwap absence and 52-week vs window high/low. The tool is complex, and the description provides enough context for correct invocation and interpretation.

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

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

Schema coverage is only 33%, so description must compensate. The Args section provides format and optionality for from_date and to_date ('YYYY-MM-DD (optional)') and symbol example ('EURUSD'), adding meaning beyond the sparse schema. However, it doesn't explain default behavior when dates are omitted or validation rules.

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 'Daily OHLC price history for a forex pair, covering the whole date range you ask for,' which clearly states the tool's purpose and scope. It also distinguishes it from siblings by explicitly naming get_forex_quote for current levels, and the sibling context shows historical variants for other asset classes.

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 guidance: 'For the current level alone, call get_forex_quote' and 'Re-request a narrower from_date/to_date for daily rows.' It also advises interpreting summary fields correctly, such as distinguishing windowHigh/windowLow from 52-week figures from quote tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only nature is covered. The description adds the 'real-time' aspect, but does not disclose return format, rate limits, or other behavioral traits. 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 exceedingly concise: a single purpose sentence, a list of common pairs, and the argument specification. Every sentence adds value and 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?

The tool is simple with rich annotations, but there is no output schema and the description does not explain the return value structure. While the purpose and parameter are clear, an agent cannot know what fields the quote contains (e.g., bid, ask, timestamp), leaving the description incomplete for a tool without 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 schema description covers the symbol parameter with detailed format and examples, giving 100% coverage. The description's Args section repeats this information without adding new meaning. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description explicitly states the tool 'Returns the real-time exchange rate quote for a forex pair,' which clearly identifies the verb, resource, and scope. This distinguishes it from sibling tools like get_all_forex_quotes (which returns all pairs) and get_forex_historical (which returns historical data).

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 that the tool is for obtaining a single real-time forex quote, but it does not explicitly state when to use it versus alternatives. No exclusions or alternative tool recommendations are provided, so the usage context is implied rather than clearly guided.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the limit constraint (max 100, default 25) and the return format, but does not disclose additional behavioral traits such as rate limits, pagination, or permission requirements. Since the description carries less burden due to annotations, a score of 3 is appropriate.

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-organized: a concise purpose statement, a useful complement note, an Args section, and a Returns section. It is front-loaded with the core purpose, and every sentence adds value—the detailed return structure is necessary given the absence of an output schema. No redundant text.

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

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

The tool has no output schema, so the description takes on the responsibility of explaining the return shape. It provides a comprehensive breakdown of the JSON response, including the funds array fields (manager, shares_change, direction, holding_value, etc.). Combined with parameter documentation and the relationship to the sibling tool, the description is complete for the tool's 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?

The schema provides only types and a default for limit, while the description's Args section adds significant meaning: ticker is explained as 'Stock ticker (e.g. 'AAPL')' and limit is described as 'Max funds to return (default 25, max 100)', including a range not present in the schema. This fully compensates for the 0% schema description 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 that the tool returns per-fund hedge-fund holdings and recent transactions for a ticker, with a specific list of fields (holding value, % of portfolio, rank/stars). It also distinguishes itself from the sibling tool get_hedge_fund_holdings by noting it complements the aggregate share-count timeseries, making the purpose and scope 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 mentions 'Complements get_hedge_fund_holdings (the aggregate share-count timeseries)', which indicates a usage distinction: this tool provides per-fund detail, while the sibling provides aggregate data. However, it does not explicitly state 'use this when you need X' or 'use that instead of Y', so the guidance is somewhat implicit rather than a full when/when-not directive.

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 and idempotentHint annotations, the description discloses meaningful behavioral details: the return structure ('Each row: {date, shares}' plus a summary block), the limit cap of 60, and the data freshness lag. This gives the agent accurate expectations 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 concise and well-structured: the core purpose is front-loaded in the first sentence, followed by return format, source, and alternative in a compact format. Every sentence contributes value, with no redundancy or filler.

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

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

For a tool without an output schema, the description fully covers the return format, parameter limits, data freshness, and alternative tooling. It provides sufficient context for an agent to select and invoke the tool correctly in any relevant scenario.

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

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

The input schema has no descriptions (0% coverage), but the description compensates fully: ticker is defined as 'Stock ticker (e.g. 'AAPL')' and limit as 'Max snapshots to return (default 60, max 60)'. Both parameters receive meaning beyond the bare 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 returns 'Hedge-fund share-count history for a ticker' with a specific verb ('Returns') and resource. It also distinguishes from sibling tools by explicitly referencing get_assets_data for current sentiment, making its purpose unique 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?

The description provides explicit usage guidance by stating 'For a snapshot of current sentiment without the timeseries, use get_assets_data and read hedgeFundSentimentData.' It also notes the data source (quarterly 13F filings) and 45-day lag, making clear when this tool is appropriate (historical trends) 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?

The description goes far beyond the annotations by detailing aggregation behavior for long ranges, the omission of vwap in aggregated bars, the summary always describing the full requested window, and the distinction between windowHigh/windowLow and 52-week figures. No contradiction with readOnlyHint or idempotentHint.

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 lengthy but well-structured with paragraphs and an Args section. Every sentence provides necessary detail about return behavior and edge cases, though it could be slightly tightened. The core purpose 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 there is no output schema, the description thoroughly explains return fields, aggregation, summary semantics, and caveats like vwap only per session. It anticipates confusion with quote-based 52-week figures and provides complete guidance for agent use.

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 has only 33% description coverage, so the description compensates by explaining all three parameters with examples (symbol '^GSPC'), date format (YYYY-MM-DD), and defaults (to_date defaults to today). It adds meaning beyond the bare schema 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 clearly states it returns daily OHLC price history for a major market index over a requested date range. It distinguishes itself from get_index_quote by explicitly noting that for current level alone, one should call get_index_quote, and it differentiates from other historical tools by focusing on index symbols.

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 usage guidance: when to use this tool vs get_index_quote, when to re-request a narrower range to get daily rows, and how to interpret summary vs quote-based figures. It clearly explains behavior for long ranges and directs the agent on how to handle data presentation.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the real-time nature and the universe of supported symbols, which is useful context beyond the annotations, but it does not disclose any additional behavioral details like rate limits or exact output format.

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

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

The description is well-structured with a one-sentence purpose, a bulleted list of supported symbols, and an Args section. Every sentence earns its place; no filler or redundancy. It is front-loaded with the primary action.

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 low complexity (single parameter) and the presence of helpful annotations, the description is reasonably complete. It covers the tool's scope (real-time index quotes) and acceptable symbols. However, it does not describe the return structure (e.g., fields like price, change, %), which would be useful since no output schema exists.

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 100% of parameters with a clear description, but the tool description goes further by enumerating the valid index symbols (e.g., '^GSPC', '^IXIC'), which is essential for correct invocation. This adds meaningful value beyond the schema's single example.

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 real-time quotes for major market indexes, with a specific verb ('Returns') and resource ('major market index'). It differentiates from siblings like get_index_historical (historical data) and get_stock_quotes (stock quotes) by the explicit focus on indexes and the list of index symbols.

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 (real-time quotes for major indexes) and even lists valid symbols, which indirectly tells the user when this tool is appropriate. However, it does not explicitly state exclusions or name alternative tools for other quote types (e.g., stocks, forex), so it misses the 'when-not-to-use' guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: newest-first ordering, approximate price (value/shares, no exact price from source), SEC filing links, and a detailed row layout. It does not contradict 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 detailed but well-structured: purpose sentence, row-field list, usage guidance, and Args. Every part contributes useful information, though the row enumeration is somewhat lengthy. It is not overly verbose given the lack of an output schema.

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

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

For a read-only list tool with no output schema, the description covers the key aspects: what is returned (all fields), ordering, data source, and an alternative for retail sentiment. Minor gaps like unclear 'insider_stars' semantics and no pagination mention prevent a perfect score.

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?

Although the schema has no per-property descriptions (0% coverage), the description's Args section thoroughly explains both parameters: ticker with an example, and limit with default (30) and maximum (100). This fully compensates for the missing 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 immediately specifies it returns individual corporate-insider (Form 4) transactions for a ticker, newest first. The phrase 'corporate-insider activity (Form 4)' and the comparison to retail sentiment clearly distinguish it from sibling tools like get_hedge_fund_activity and get_assets_data.

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 ('corporate-insider activity') and when to use an alternative: 'For retail/individual investor sentiment, use get_assets_data and read investorActivity.' This is a clear usage directive with a named alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds substantial behavioral context beyond that: it explains the meaning of decimal fields (0.013 = +1.3%), clarifies that ageDistribution refers to account-tenure tiers not biological age, and highlights the divergence between crowd and best-investor sentiment as a headline signal. This exceeds the annotation baseline.

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 well-organized with clear section headers (investorStatsOverview, bestInvestorStatsOverview, ageDistribution, investorsAlsoBought). Given that no output schema is present, the detailed breakdown of return fields is justified and each section earns its place. It is front-loaded with the core purpose and then follows a logical structure.

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 and a complex nested JSON response, the description is remarkably complete. It documents every top-level key, explains field semantics (including percentage decimal interpretation), notes edge cases (empty lists for cohort-specific holdings), and provides interpretation guidance (the divergence signal). This gives an agent everything it needs to understand the tool's output.

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

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

The input schema has only a 'ticker' string with no description. The description compensates by explicitly stating 'ticker: Stock ticker (e.g. NVDA)', providing an example and clarifying the expected format. Since schema coverage is 0%, the description adds critical meaning that would otherwise be missing.

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

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

The description opens with a clear, specific statement: 'Returns crowd / retail investor sentiment for a stock.' It identifies the resource (investor sentiment) and the action (returns), and distinguishes it from sibling sentiment tools like get_blogger_sentiment by focusing on TipRanks crowd/retail positioning.

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

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

The description implies when to use the tool—when you need crowd/retail sentiment for a stock—but does not explicitly compare it to alternatives like get_blogger_sentiment or get_bulls_bears_summary. No exclusion or when-not-to-use guidance is provided, so it earns a middle score.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the default date range (today to 30 days from now) and that it includes both upcoming and recent IPOs, but does not disclose pagination, output format, or any rate limits. This is adequate but not rich.

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 and front-loaded with the primary action. The 'Args:' section neatly lists the parameters with concise explanations, using no unnecessary words. It is both compact and well-structured.

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 no output schema, the description gives a high-level return statement but does not describe the structure of the returned IPO data (e.g., company names, dates, exchange). Annotations and parameter explanations cover most of the needed context, but a bit more detail on return values would make it 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 has no descriptions for parameters, so the description fully compensates by explaining fromDate as 'Start date ISO format' and toDate as 'End date ISO format' with defaults. This adds clear semantic meaning beyond the bare schema fields, turning empty-string defaults into meaningful behavioral specifications.

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 "Returns upcoming and recent IPOs," which specifies the resource and action. This distinguishes it from sibling tools like get_earnings_calendar or get_economic_calendar by the specific domain (IPO vs. other event types).

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

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

Usage is implied by the name and description but not explicitly stated. There is no mention of when to use this tool versus alternatives like get_earnings_calendar or get_economic_calendar, nor any exclusions. The date-range defaults provide some context for typical 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 annotations (readOnly, idempotent, non-destructive), the description reveals important behavioral traits: the newest-first ordering, the presence of excerpts (which get_assets_news lacks), the archive depth ('holds years of stories'), the counterintuitive from_date behavior ('from_date alone returns today's news rather than news from around that date'), and the inclusive to_date. It also states the return format and forwards to get_article for full content. This is rich context not captured by 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 longer than the minimal examples, but every sentence earns its place. It is structured with a purpose statement, usage guidance, an Args list, and return format. It front-loads the core purpose and differentiator, then provides necessary details without repetition or filler. The length is justified by the need to explain 5 parameters and subtle date-window 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 appropriately specifies the returned structure: 'a JSON list of {id, title, excerpt, author, category, date, url, tickers}.' It also covers enough context for the tool's use cases, edge cases (date windows), and relationships to sibling tools (get_assets_news, get_article). Given the moderate complexity (5 optional parameters) and the absence of an output schema, this description is complete and self-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 only 40% (category and to_date have descriptions), but the description compensates with a full Args list explaining each parameter: tickers as comma-separated, category as single optional value, from_date as a 'YYYY-MM-DD' recency floor, limit with default 20, and to_date as an inclusive upper bound. It also clarifies the interaction between from_date and to_date, which the schema does not fully convey. This directly addresses the low schema coverage.

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

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

The description opens with a specific verb+resource statement: 'Latest TipRanks news articles (newest first) from TipRanks's own editorial/wire feed — each with a text excerpt, unlike get_assets_news.' This clearly defines what the tool does and immediately differentiates it from a sibling tool. It also lists concrete use cases: general market news, stock-specific news with summaries, and browsing categories.

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 guidance is provided: 'Use for general market news (no ticker), news on a specific stock... or to browse a news category.' It also states when this tool is uniquely appropriate: 'This is also the tool for news from a specific PAST date range — pass from_date AND to_date together...' and contrasts with get_assets_news's limited recency. This gives clear when-to-use and even notes when not to rely on the alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds substantial context beyond that: it reads a ~4-hour-old cache, does not trigger regeneration, returns a specific 'unavailable' status when no cache exists, and warns that content is AI-generated and not authoritative. These are non-obvious behavioral traits that materially affect how an agent should invoke and present the 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 four sentences, front-loaded with the core purpose. Every sentence serves a distinct role: what it is, what it returns, how/when it's generated, cache-only behavior, error case, and usage caveat. No filler or redundant restatement of the tool's name.

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 zero-parameter, no-output-schema tool, this description is complete. It documents the return structure, the refresh interval, the cache-miss behavior, and the AI-generation caveat. The agent has everything needed to decide invoke, interpret results, and communicate them to end users.

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

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

The tool has zero parameters and the schema properties are empty (coverage is trivially 100%). The description correctly adds no parameter noise. Given the 0-parameter baseline of 4, this score is appropriate; the description instead clarifies the output shape and cache behavior, which is more valuable here.

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 'Cached equities market sentiment snapshot,' a specific verb+resource+qualifier that immediately distinguishes this from siblings like get_market_movers or get_market_performance. It also enumerates the exact return fields (overallSentiment, atmosphere, keyThemes, tailwinds, headwinds), leaving no ambiguity about its 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 clearly establishes the context: this is a cache-only endpoint that never triggers regeneration and may return 'unavailable' if no cache exists. This implies it is suitable for quick, non-authoritative sentiment reads. However, it does not explicitly name alternative tools (e.g., get_investor_sentiment or get_market_performance) for cases where real-time or authoritative data is needed, so it stops short of full exclusion guidance.

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

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

Annotations already indicate readOnlyHint and idempotentHint, and the description adds no contradictory behavioral traits. It includes category meanings, but these are also present in the schema. No extra context like pagination, data freshness, or limitations is provided.

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

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

The purpose sentence is front-loaded and the Args list is compact and readable. However, it duplicates some information already in the schema, making it slightly redundant though still efficient.

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

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

For a read-only tool with three parameters and no output schema, the description covers all parameter meanings and the types of movers returned. It could mention the return format (e.g., a list of tickers) but remains adequate for understanding the tool's capabilities.

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

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

Schema coverage is 67%, and the description largely repeats the same numeric codes for category and country. It adds minimal semantics for 'num' as 'Number of results,' which is somewhat self-evident, so it does not significantly enhance 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 returns today's market movers with specific categories (gainers, losers, most active), using the verb 'Returns' and a specific resource. It is distinguishable from siblings like get_market_performance, though it does not explicitly mention alternatives.

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

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

No guidance on when to use this tool versus similar market data tools, nor any exclusions or alternative tool names. The description only explains what it returns, not when it should be selected.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds context about the output contents (sector breakdown, top/bottom performers) but no additional behavioral traits like data freshness, pagination, or any side effects. It does not contradict 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 sentences, front-loaded with the core purpose and then the parameter. Every word earns its place; no filler or redundant restating of the tool name or annotations.

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 a single optional parameter, rich annotations, and no output schema, the description covers the essential purpose and parameter semantics. However, it omits details like whether data is real-time or historical, and the country list is open-ended ('etc.'), which could leave edge cases unclear. Still, for a read-only simple lookup, it is largely 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 only provides a title 'Country' with a default, and schema description coverage is 0%. The description compensates by explaining the country parameter with explicit examples ('us', 'ca', 'gb', etc.), adding meaningful guidance beyond the raw schema. The 'etc.' leaves some ambiguity, but it is sufficient for the common cases.

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 market-wide performance for a specific country, enumerating the exact data included (average returns, sector breakdown, top/bottom performers). This distinguishes it from sibling tools like get_market_movers or get_sector_analysis by explicitly scoping to country-level market performance.

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

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

The description implies usage when country-level market performance is needed, but it does not explicitly contrast with alternatives such as get_market_movers, get_sector_analysis, or get_market_commentary. It lacks clear when-to-use or when-not-to-use guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description reveals important nuances: every metered call counts even if it fails, refused over-limit calls also count and are not refunded, and `used` can exceed `limit` on OAuth. This is rich behavioral disclosure with no contradiction to 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 adds necessary caveats in a structured, easy-to-follow manner. Every sentence delivers unique value; 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?

The quota semantics are complex, and the description fully addresses edge cases: free calls, handshake calls not metered, failed calls still count, and OAuth-specific overage behavior. It is complete despite lacking an 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?

With zero parameters, the baseline is 4. The description goes further by enumerating the returned fields (used, limit, remaining, tier, reset time), which substitutes for an output schema and fully clarifies the tool's semantics.

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

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

The description precisely states the tool's function: it reports calls used, limit, remaining calls, plan tier, and quota reset time in UTC. This clearly distinguishes it from the many sibling data retrieval 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?

It explicitly advises using this tool before a large batch of calls and clarifies that the call itself is free and never counts against the quota. It also explains metering behavior for failed calls and handshake calls, providing thorough when-to-use 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 mark this as read-only, idempotent, and non-destructive, so the description adds value by disclosing the ~15-minute quote delay, the absence of Greeks/IV in the data source, and the exact list of returned row fields. This is rich behavioral context beyond the structured metadata.

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: a one-line purpose, a compact output field list, a behavior note, and a clear Args block. Every sentence adds necessary information, with no filler or repetition. It is appropriately sized for a six-parameter 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?

With no output schema, the description enumerates all return fields, covering price, volume, OI, and price range. It also provides usage context (expiration discovery), data timing (delayed quotes), and limitation warnings. The combination of annotations and description fully equips an agent to call 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?

Despite schema description coverage of only 33%, the description's Args section fully explains all six parameters with examples ('AAPL'), constraints (strike filters, limit default 50), and the requirement that expiration_date comes from get_options_expirations. It more than compensates for the schema's gaps.

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

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

The first sentence 'Contracts at one expiration, enriched with price + OI + volume' states a specific verb (get) and resource (option chain for one expiration). It clearly distinguishes from get_options_expirations (dates only) and get_options_contract (single contract) by emphasizing a full chain at a single expiration.

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 instructs to use get_options_expirations first to discover valid expiration dates, and warns that Greeks/IV are not available and must not be fabricated. This gives clear when-to-use and what-not-to-use guidance, plus a direct reference to a sibling 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 already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context: 'Quotes are typically delayed ~15 minutes' and 'Greeks and implied volatility are not available from this data source,' which are not in the annotations and help 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 well-organized: a one-sentence summary followed by necessary formatting details and behavioral caveats, then a simple Args line. Every sentence carries meaningful information, with no fluff 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?

For a single-parameter tool with no output schema, the description is complete. It states what data is returned, how to format the parameter, and what limitations exist (delayed quotes, no Greeks/IV). This gives an agent all the context needed 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?

Although the schema already documents the contract_ticker parameter, the description adds deep semantic value by breaking down the OCC symbol format ('O: + underlying + YYMMDD + C/P + strike-in-thousandths-8-digits') and noting that the 'O:' prefix is optional. This goes beyond the schema's simple example and is essential for correctly constructing the ticker.

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 'Snapshot one OCC contract — price, OI, intraday OHLCV, last trade,' which uses a specific verb and resource and lists the returned data fields. This clearly distinguishes it from sibling tools like get_options_chain (which covers a chain) and get_options_expirations (which covers expirations).

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

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

The description implies usage for a single contract snapshot ('Snapshot one OCC contract') but never explicitly contrasts it with alternatives such as get_options_chain or get_options_unusual_trades. There is no when/when-not guidance, making the usage context clear but not explicit.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds the behavioral filter 'Excludes past expirations,' but does not describe return format or ordering, so it stays at the calibration baseline.

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 plus a clear Args section. It front-loads the core action, includes the essential exclusion filter, and gives a workflow hint – 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 simple one-parameter read-only tool with no output schema, the description covers the purpose, the parameter, and its role in an options-chain workflow. There are no side effects, auth requirements, or rate limits to disclose, so nothing important 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 0%, so the description must compensate. The Args section defines ticker as 'Underlying ticker (e.g. 'AAPL')', giving both a definition and an example. This goes beyond the schema's bare type and is sufficient for correct invocation.

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 'List future expiration dates for a ticker's listed options' – a specific verb and resource. It distinguishes from sibling tools like get_options_chain or get_options_contract, which operate on the chain or individual contracts.

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 workflow directive: 'Use the result as input to get_options_chain.' This tells the agent when to use this tool and how it fits into a larger operation. It doesn't explicitly exclude alternatives, but the purpose is distinct enough that a competent agent would not confuse 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 declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by explaining the data returned (side, strike, expiry, size, notional) and the 'flagged trades' nature, while also noting the 'most recent' ordering. It does not contradict 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 and front-loaded: first sentence states the core function, second adds return fields and a use case, and the Args list is clearly formatted. 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?

Given the tool's moderate complexity (2 params, no output schema, direct read operation), the description covers what it returns, the parameters, and the intended use case. It is complete enough for an agent to select and invoke it correctly.

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

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

Schema description coverage is 0%, so the description fully compensates. It explains both parameters: ticker as 'Underlying ticker (e.g. 'AAPL')' and limit as 'Max trades to return (default 25)', adding meaning beyond the bare schema definitions.

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

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

The description clearly states it returns 'recent unusual option trades for an underlying' and specifically mentions 'size/sweep alerts', distinguishing it from sibling tools like get_options_chain or get_options_contract. The verb (get/return) and resource (unusual option trades) are explicit.

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

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

It provides a clear use case ('Useful for spotting large bullish or bearish positioning'), indicating when to use the tool. However, it does not explicitly exclude alternatives or state when not to use it, which keeps it at a 4 rather than 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 provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds that the tool provides 'comparative metrics for side-by-side analysis' and explicitly states 'Read-only, no side effects,' which reinforces but does not significantly expand beyond the annotations. The added context about the output purpose is useful, but there is minor 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 two sentences, front-loaded with the main purpose and followed by usage guidance. It is concise with no filler or wasted words, efficiently conveying the tool's function and boundaries.

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, strong annotations, and no output schema, the description provides adequate context: it explains what the tool returns (comparative metrics), when to use it, and how it differs from alternatives. No critical information is missing for an agent to decide invocation.

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

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

Schema description coverage is 100%, with the ticker parameter described as 'Stock ticker symbol, e.g. 'AAPL'.' The description does not add any further explanation about the parameter beyond 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 states the tool identifies 'peer/competitor companies for a stock, with comparative metrics for side-by-side analysis.' It uses a specific verb (find/compare) and resource (peer companies) and distinguishes from siblings by noting alternatives for own data (get_assets_data) and sector-wide analysis (get_sector_analysis).

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

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

The description explicitly says when to use the tool: 'Use to find and compare a company against similar names (competitors, same-sector peers).' It also provides clear exclusions: 'For that company's own data use get_assets_data; for a sector-wide breakdown use get_sector_analysis.' This names alternatives and 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavioral context by explaining the dependency on get_politicians and the allowed values for 'activity'. This goes beyond the 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 compact and front-loaded: the first sentence states the purpose, the second gives the prerequisite, and the Args list maps clearly to the parameters. 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 simple, read-only tool with full schema coverage and no output schema, the description is sufficiently complete for an agent to select and invoke it correctly. It covers what it returns, how to obtain the required ID, and the two activity options. It could mention return format, but that is not required and not critical for correctness.

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 parameters are fully documented in the schema. The description largely repeats the schema's info (politicianId from get_politicians, activity 'trades' or 'holdings'). The only added value is reiterating the prerequisite, which is already in the schema description, so it adequately meets the 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 states 'Returns a specific politician's stock trades or holdings,' which is a specific verb and resource. It distinguishes from the sibling get_politicians tool by focusing on the activity (trades/holdings) of a single politician rather than listing politicians.

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 explicit prerequisite guidance: 'First call get_politicians to find the politicianId.' This clearly tells the agent the required sequence. It does not explicitly mention alternatives or when-not-to-use, but the context is sufficiently clear for this simple lookup 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 already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering the safety profile. The description adds the return field list and the 'tracked for trading activity' scope, which gives some context but does not disclose additional behavioral traits like pagination or 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 two sentences, front-loaded with the core purpose, and the field list is compact. Every sentence earns its place 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 parameterless list endpoint, the description covers purpose and return fields. Annotations provide safety and idempotency information. Although there is no output schema, the field list partially compensates, and the description is sufficient for the tool's simplicity.

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

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

The tool has zero parameters, so schema coverage is 100% by default. With no parameters to document, the baseline is 4, and the description does not need to add parameter-specific semantics.

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

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

The description clearly states the verb ('Returns') and resource ('the list of politicians tracked for trading activity'), which identifies the tool's purpose precisely. It also distinguishes itself from the sibling tool get_politician_activity by focusing on the politicians list rather than individual activity.

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

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

The description makes the context clear: this tool returns a list of politicians, not their activity. It implicitly differentiates from get_politician_activity, but it does not explicitly state when not to use it or name alternatives, so the agent must infer the appropriate 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, openWorldHint, idempotentHint, and non-destructive, so the safety profile is disclosed. The description adds the behavioral fact that portfolio_id must be obtained from list_my_portfolios, which is useful but not a major new behavioral trait. No contradictions exist.

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 with a comprehensive list of output dimensions in one sentence, followed by an Args block. Every sentence earns its place; 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 read-only analysis tool with one parameter and no output schema, this description is complete. It explains what to expect (allocation/distribution data) and how to satisfy the input (portfolio_id from list_my_portfolios). No major gaps remain.

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 0% for portfolio_id, so the description must compensate. It explicitly connects the parameter to list_my_portfolios, giving the agent a clear way to obtain valid IDs. This is valuable semantic context that the schema alone lacks, though it doesn't cover additional formats or constraints.

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 the specific verb 'Returns' and clearly enumerates the resource: asset allocation by type/country/top stocks and distribution by sector, market cap, dividend yield, beta, and P/E. This distinguishes it from sibling portfolio tools like get_portfolio_holdings or get_portfolio_overview by specifying the exact analytical content.

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 about when to use this tool: when you need allocation and distribution metrics for a portfolio. It also gives a crucial prerequisite—portfolio_id must come from list_my_portfolios. However, it does not explicitly contrast with alternatives or state when not to use it, so it misses the full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by detailing the output structure, including per-holding metrics and portfolio summaries (total value, cash, stock count), which is especially important given the absence of an output schema. It does not mention pagination or potential large response sizes, but for a simple read operation this is sufficient.

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 efficiently organized: a one-line purpose, a field list, and a parameter explanation. Every sentence contributes meaningful information, and the field list is concise yet comprehensive. It is not bloated and earns 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 single-parameter read tool with high annotation coverage, the description is almost complete. It covers the return values thoroughly and the parameter provenance. The only gaps are potential edge cases (e.g., empty portfolio, invalid ID) or response size limits, but these are not critical for a holdings retrieval tool. Thus it scores just above the minimum viable.

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 provides only the type and requirement for portfolio_id with zero coverage. The description compensates fully by explaining that portfolio_id is 'One of the IDs returned by list_my_portfolios,' giving the agent a precise source for the parameter. This transforms an opaque integer into a well-defined reference.

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 all holdings for one of your TipRanks portfolios,' which is a specific verb+resource. It distinguishes itself from sibling tools like get_portfolio_overview and get_portfolio_analysis by focusing on holdings, and it enumerates the exact data fields returned (ticker, shares, price, cost basis, etc.), leaving no ambiguity about its 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 specifies the prerequisite that portfolio_id comes from list_my_portfolios, which guides the user on how to obtain a valid input. It does not explicitly contrast with sibling portfolio tools, but the context is clear enough that this is the go-to for detailed holdings while other tools handle overviews or analysis. A brief note about when not to use it would elevate this score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds meaningful behavioral detail by specifying the exact output fields and noting that the monthly history is chart-ready as a list of {month, return} objects, which goes beyond what annotations provide.

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

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

The description is concise and structured: it first summarizes the returned metrics, then clarifies the shape of the monthly history field, and finally documents the parameter. Every sentence contributes useful information with 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?

For a read-only tool with a single parameter and no output schema, the description covers the main return values and the parameter source. Minor gaps remain, such as units for returns and possible error behavior for invalid IDs, but the overall context is sufficient for an agent 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?

The schema only defines portfolio_id as an integer with no supporting description (0% coverage). The description compensates well by explaining that the ID must be one returned by list_my_portfolios, giving the agent a concrete source for valid values.

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 that the tool returns a portfolio overview with specific metrics (returns for multiple periods, Sharpe ratio, and a monthly-return time series). However, it does not explicitly differentiate itself from the similar sibling tool get_portfolio_performance, so it misses the highest bar for sibling distinction.

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

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

The description gives a useful prerequisite by saying portfolio_id must be one of the IDs returned by list_my_portfolios, but it does not explain when to choose this tool over alternatives like get_portfolio_performance or get_portfolio_analysis. Usage context is implied rather than explicit.

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