TipRanks

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

Annotations already cover safety (readOnly, idempotent, openWorld, non-destructive), yet the description adds substantial behavior: coverage excludes ETFs, uncovered vs covered-but-missing-provider symbols are reported in separate buckets so a missing provider is never misreported as absent analysis, and as_of regeneration semantics (new earnings or significant price move). This goes well beyond the annotation surface.

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?

Long but deliberately structured with 'Use for:' examples, an explicit NOT clause, and per-field notes. Front-loaded with the headline definition. The Returns paragraph is dense but earns its place since no output schema exists; a tight edit could still trim some redundancy around as_of/reports_dated.

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

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

There is no output schema, so the description carries the full return contract and does so: it enumerates the stocks fields, explains ai_score vs consensus, upside_pct, reports_dated conditional presence, and the two error buckets. Nothing an agent needs to invoke or interpret the call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: the interaction rule that detail is ignored on multi-ticker calls, and the rationale for provider selection ('Omit for the headline score that matches the website'). The batching instruction reinforces the max-25 ticker constraint.

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

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

Names a specific resource (TipRanks AI Stock Analysis 0-100 score) and verb (get), and explicitly distinguishes itself from the closest sibling system: 'This is NOT the Smart Score (1-10, eight quantitative factors).' An agent can separate this from get_top_smart_score_stocks or get_technical_analysis without opening a schema.

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

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

Gives concrete trigger phrases ('what's the AI score for NVDA', 'why do the models disagree on Tesla') and an explicit exclusion (not the Smart Score, and the two routinely disagree by design). It also states the batching rule — pass every symbol in one call for watchlist/ranking questions — which is exactly when-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, 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 declare readOnly/idempotent/non-destructive, yet the description adds substantial behavior beyond them: long ranges are aggregated into coarser bars instead of cut short, aggregated bars drop `vwap`, ordering is newest-first, and `summary` always reflects the full requested window with explicit warning against conflating its windowHigh/windowLow with a quote tool's trailing range.

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

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

Core purpose and field list are front-loaded, and each paragraph covers a distinct concern (fields, aggregation, summary semantics, sibling routing). It is on the long side and re-enumerates fields, but nearly every sentence carries non-obvious information.

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

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

With no output schema, the description fully carries the return-value burden: it lists the exact row fields, the ordering, the aggregation variant and its field omissions, and the meaning of `summary`. Nothing an agent needs to interpret or call the tool correctly is missing.

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

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

Schema coverage is only 33% (symbol is the sole documented param), so the description carries the load: it gives the date format (YYYY-MM-DD), explains that from_date/to_date scope the range, and describes how an overly long range is aggregated rather than truncated. It adds real meaning, though it also mentions an `interval` value that is not an actual parameter, which is mildly confusing.

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

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

States a specific verb and resource — daily OHLC price history for a commodity — and immediately scopes it to the requested date range. It is clearly distinguishable from get_commodity_quote and the other *_historical siblings without opening any schema.

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

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

Explicitly routes the agent: 'For the current level alone, call get_commodity_quote,' and tells it to 'Re-request a narrower from_date/to_date for daily rows' when aggregation kicks in. When-to-use, when-to-use-something-else, and the fallback action are all stated.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so safety is covered. The description earns credit for disclosing data semantics beyond the annotations: yearHigh/yearLow are trailing-year (12-13 months) and the quote does not date its extremes. That is genuine behavioral nuance about what the feed returns.

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

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

Purpose is front-loaded in the first sentence, followed by useful symbol references and a caveat about the trailing-year fields. The six-symbol list is slightly long but directly aids invocation, so nothing feels wasteful.

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

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

With no output schema, the description usefully explains the key ambiguous return fields (yearHigh/yearLow semantics) and names the historical alternative. Covered well for a one-parameter quote tool; only the all-commodities alternative is unaddressed.

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

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

Schema description coverage is 100% and the single parameter's meaning is fully documented in the schema. The description repeats a symbol example plus a list of common symbols, which is mildly additive but not required. Baseline 3 for a fully-documented single param.

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

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

States a specific verb and resource ('Returns the real-time price quote for a specific commodity'), and explicitly differentiates itself from the sibling get_commodity_historical. An agent can identify scope and sibling boundary without opening the schema.

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

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

Gives explicit routing guidance: when the user needs YTD, calendar-year change, dated extremes, or an exact 52-week figure, call get_commodity_historical instead. It does not, however, address the sibling get_all_commodities_quotes, so the multi-commodity case is left 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, 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 read-only/idempotent safety, yet the description adds substantial non-obvious behavior: long ranges are aggregated into coarser bars rather than truncated, aggregated bars omit `vwap` because the feed defines it per session, rows are newest-first, and `summary` is computed over the FULL requested window. These are real behavioral traits an agent cannot infer from the schema or annotations.

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

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

Front-loaded with the core purpose, and the long-form paragraphs are all output-semantics detail with no filler. Dense but every sentence maps to how the result should be interpreted; slightly long, with the summary/quote caveats restated more than once.

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

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

There is no output schema, so the description carries the full burden and does so thoroughly: it enumerates the returned fields, explains ordering, bar aggregation, the absent vwap case, and how to interpret summary stats and the yearHigh/yearLow distinction. An agent has everything needed to call and interpret it.

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

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

Schema coverage is only 33% (symbol documented only), so the description must compensate: it specifies YYYY-MM-DD format, optionality, and start/end semantics for from_date/to_date, plus how the range drives daily-vs-aggregated output. It does not state what happens when dates are omitted (default range), leaving one gap.

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

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

States a specific verb and resource ('Daily OHLC price history for a cryptocurrency') with explicit scope ('covering the whole date range you ask for'). It also distinguishes itself from get_crypto_quote by reserving that sibling for 'the current level alone', so an agent can choose correctly without opening schemas.

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

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

Gives a clear routing rule to an alternative ('For the current level alone, call get_crypto_quote') and tells the agent to 'Re-request a narrower from_date/to_date for daily rows' when aggregation occurs. It does not address when-not to use this tool versus other historical siblings (commodity/forex/index), so it stops short of full when/when-not coverage.

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

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

Annotations already 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 declare readOnly, idempotent, open-world and non-destructive behavior, so safety is covered. The description adds genuinely useful context the annotations cannot: that yearHigh/yearLow are a trailing 12-13 month feed range and that the quote does not date its extremes, which prevents a common misinterpretation.

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

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

Purpose is front-loaded, followed by supported symbols and the trailing-year caveat, all earning their place. The trailing 'Args: symbol' block mildly duplicates the schema description, a small redundancy.

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

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

With no output schema, the description usefully explains the trickiest returned fields (yearHigh/yearLow) and their caveats. It stops short of enumerating other expected quote fields such as price or change, leaving a modest gap for a data-returning tool.

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

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

Schema coverage is 100% and the schema already documents the symbol parameter with examples, so the baseline is 3. The description's symbol list and example complement but do not extend the schema's 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?

States a specific verb (returns) and resource (real-time price quote) scoped to a single cryptocurrency symbol, and names the concrete unit of exchange (BTCUSD, ETHUSD, etc.). An agent can distinguish it from get_all_crypto_quotes (all symbols) and get_crypto_historical without opening either schema.

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

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

Explicitly routes to get_crypto_historical for year-to-date, calendar-year, dated-extreme or exact 52-week needs, which is a real alternative-selection rule. It does not address when to prefer this over get_all_crypto_quotes, but the single-symbol scope makes that inference trivial.

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 establish the safe read-only, idempotent profile. The description adds meaningful behavioral detail beyond that: the hard 15-day truncation, that the served window is reported back in fromDate/toDate, and the continuation pattern for longer ranges.

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

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

Front-loads the tool's purpose, then the range constraint and pagination rule, then the argument reference. The Args section slightly repeats the 14-day maximum already stated in the prose, a minor 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 three optional parameters, no output schema, and 0% schema description coverage, the description covers the essential inputs, the truncation behavior, and the response window metadata. It could say more about the returned earnings fields, but the core calling information is present.

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 the full burden and does so well. It documents all three parameters with formats, defaults, the 14-day maximum, and an exchange-filter example, adding substantial 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?

States a specific verb and resource: returns upcoming earnings dates across all stocks for a date range. The phrases 'upcoming' and 'across all stocks' implicitly distinguish it from past-earnings and single-ticker siblings, but no sibling is named explicitly.

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

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

Gives clear operational context: at most 15 days per call, and how to continue with multiple calls for longer periods. It does not name an alternative tool or state when another earnings-calendar sibling would be preferable, so it stops short of full when-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 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?

Beyond the annotations (readOnly/idempotent/openWorld), it discloses the noisy-ness of the raw feed and why defaults filter, the truncation behavior when limit is large ('cut to the events nearest now... the result says how many were left out'), and the exact composition of the vsEstimate delta field including that the label is direction-only. These are non-obvious behaviors an agent needs.

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

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

Front-loaded purpose sentence followed by a rationale, a special-case instruction, and an organized Args block; the Returns line prevents the reader from guessing. It is somewhat long and the countries/impact text partially duplicates the schema descriptions, which is minor waste but not filler.

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

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

With no output schema and 7 undocumented-in-schema parameters, the description still supplies both the parameters and the return shape ({ totalMatched, returned, filters, economicCalendar }) plus the nested vsEstimate semantics. Nothing needed to call or interpret the tool is missing.

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

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

Schema description coverage is only 29%, so the description carries the burden and does so fully: it documents all seven parameters with defaults, the fromDate/toDate-vs-daysBack/daysForward alternatives, valid enum-ish values for impact ('High','Medium','Low'), common country values, and the empty-string convention for disabling filters.

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

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

States a specific verb and resource ('Returns upcoming and recent economic events') and grounds it with concrete examples (Fed meetings, jobs reports, CPI, GDP). This clearly separates it from company-specific siblings like get_earnings_calendar and get_ipo_calendar, though it never names those siblings explicitly.

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

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

Gives real when-to-use guidance: the default filtering exists 'because the raw feed includes hundreds of low-impact items from every country,' and it explains setting daysBack to 35 to retrieve released actuals. It also explains how to opt out of each default filter. It lacks any explicit when-not-to-use or alternative-tool routing.

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

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

Annotations 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?

Annotations already establish the safe read-only profile, and the description adds genuine extra context: the returned field sets per mode ({ticker, name, weight_pct} vs weight_pct, current_price, return_pct, analyst_consensus) and the limit validation rule that negative/non-numeric values are rejected rather than coerced. Missing pieces like rate limits are minor for an idempotent read.

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

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

Front-loads the mode distinction before the Args block, and each sentence carries information. The rationale paragraph justifying the negative-limit rejection is unusually verbose for an edge case, but it is the kind of detail that prevents a silent mis-call.

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

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

For a 3-parameter read tool with no output schema, the description supplies the mode semantics, the per-mode return fields, and the boundary behavior of the only tricky parameter. Nothing an agent needs in order to invoke it correctly is left unstated.

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 schema description coverage at only 33% and no enums declared in the schema, the description carries the load and does so thoroughly: it enumerates sort_by's valid values ('5d', 'month', 'ytd', 'year'), defines limit's 0-vs-positive semantics with a max of 50, and explains why negative limits are rejected. This is meaning well beyond what the schema provides.

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

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

States a concrete verb+resource ("List the constituents of an ETF") and spells out the two operating modes and their exact return shapes, so an agent knows precisely what it gets. It partially differentiates from siblings by noting it replaces a separate screener call, but never distinguishes itself from get_etf_top_stocks, which appears to overlap with the top-performers mode.

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

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

Gives explicit mode-selection rules: default for the full holding list, and `sort_by` plus `limit`>0 for top-N by period, with a concrete motivating question ("which stocks in XLK rose most this week"). It even steers the agent away from a redundant screener call. It stops short of naming when to prefer the sibling get_etf_top_stocks or get_etf_exposures instead.

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/openWorld, so the safety profile is covered; the description adds the meaningful extras — the absence of a sector filter, the empty-result failure mode for mismatched filter values, and the limit default/max. It stops short of describing pagination or ordering behavior, so it is strong rather than exhaustive.

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

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

Front-loaded single-sentence purpose followed by cleanly separated Args and Returns blocks. Some of the Args text restates the schema's assetClass enumeration in condensed form, which is mild redundancy, but the Returns field list earns its space because no output schema exists.

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

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

With no output schema, the description carries the full return contract — `count` plus the exact row fields including conditional flags like isLeveraged/isActivelyManaged 'when true'. Combined with defaults, limits, and the fallback path for uncovered factors/regions, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% and the assetClass field description is already extremely detailed, so much of the Args section duplicates structured data. It still adds interpretive value by recasting `focus` as the de-facto sector filter and giving worked examples ('tech ETFs' -> InformationTechnology) that clarify intent rather than just enumerating 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?

States a specific verb and resource ('Filters ETFs') and enumerates the three facets it screens on, which distinguishes it from the single-ticker siblings like get_etf_analysis and get_etf_holdings. It also explicitly routes factor/region queries away to get_assets_data, so an agent can pick the right tool without opening a schema.

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

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

Gives explicit when-to-use ('tech ETFs' -> focus=InformationTechnology), an explicit when-not (the screener has no `sector` filter), and a named alternative with concrete ticker examples ('momentum -> MTUM/SPMO via get_assets_data'). The assetClass section further warns that values taken from the wrong class match no ETF, which prevents a costly misuse.

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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: automatic aggregation into coarser bars for long ranges, that aggregated bars drop `vwap`, that rows are newest-first, and that `volume` is a per-venue tick count rather than market turnover. It also clarifies the semantics of summary.windowHigh/windowLow versus a quote tool's trailing-year figure.

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

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

Front-loads the core purpose and is organized into digestible paragraphs, most of which (volume caveat, summary semantics, aggregation behavior) earn their place. It is somewhat verbose for a 3-parameter tool, and references to the non-existent `interval` arg add noise.

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

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

With no output schema, the description carries the full burden of describing returns, and it does so thoroughly: enumerates the row fields, explains the summary block, describes aggregated-bar fields, and gives plotting intent. An agent has everything needed to call and interpret it.

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

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

Schema coverage is only 33% (only `symbol` is described in the schema), so the description must compensate, and it partially does by giving the date format (YYYY-MM-DD) and marking from/to as optional. However it never explains the empty-string default or what omitting a date returns, and it confusingly discusses an `interval` field that is not an input 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?

Opens with a specific verb+resource+scope: 'Daily OHLC price history for a forex pair, covering the whole date range you ask for.' It explicitly separates itself from the sibling get_forex_quote ('For the current level alone, call get_forex_quote'), so an agent can route without opening a schema.

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

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

Gives explicit when-to-use guidance (historical range vs 'current level alone') and names the alternative tool get_forex_quote. It also tells the agent what to do when a range is too long ('Re-request a narrower from_date/to_date for daily rows') and which source to base derived claims on.

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/openWorld, so this is safely a read. The description goes well beyond them: it discloses that yearHigh/yearLow are feed trailing-year (~12-13 month) figures rather than calendar values, that spot FX is closed Friday 17:00 to Sunday 17:00 NY time, and that a quote in that window shows the last close rather than a same-day move. These are real behavioral caveats an agent could not infer from annotations.

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

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

Front-loads the one-line purpose, then groups the interpretation, trailing-year, and market-hours gotchas, each earning its place with no redundant restatement. Long but dense; every sentence addresses a distinct pitfall.

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

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

With no output schema, the description carries return-value burden and does so: it defines yearHigh/yearLow, changePercentage's previousClose basis, and the meaning of priceAvg50/priceAvg200 relationships. Nothing material for correct invocation or interpretation appears missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine semantic value by explaining the base/quote convention ('USDHUF 320 means 1 USD = 320 HUF') and how a rising rate relates to the averages, which the schema's terse 'uppercase with no slash' note does not. It stops short of adding format/syntax beyond the schema, so a 4 rather than 5.

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

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

States a specific verb and resource ('Returns the real-time exchange rate quote for a forex pair') and immediately names the sibling to use instead for historical figures (get_forex_historical) and the broader list variant is implied by common pairs. An agent can distinguish it from get_all_forex_quotes and get_forex_historical without opening any schema.

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

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

Explicitly routes the agent: 'For a year-to-date or calendar-year change, a dated extreme or an exact 52-week figure use get_forex_historical.' It also explains the market-hours caveat that determines whether a quote is actionable. Clear when-to-use and when-to-look-elsewhere 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, 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?

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), but the description adds substantial behavior beyond them: long ranges are aggregated into coarser bars rather than truncated, aggregated bars omit vwap, rows come newest-first, and summary always spans the full requested window. These are non-obvious response-shaping behaviors that materially affect interpretation.

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

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

Front-loaded with purpose and organized into purposeful paragraphs, with the routing hint placed at the end. It is on the long side and repeats the symbol-mapping point already implied, but virtually every sentence carries operational information rather than filler.

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

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

With no output schema, the description fully carries the return-shape burden: field list, ordering, aggregation fallback, which fields survive aggregation, and summary semantics. An agent has everything needed to call it and correctly 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 only 33% (from_date and to_date have no schema descriptions), so the description must compensate — and it does, supplying YYYY-MM-DD formats, the 'to_date defaults to today' default, and concrete symbol examples (^GSPC, ^NDX, ^GDAXI). It does not clarify the boundary inclusivity of the range or the interval control it references.

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

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

Opens with a specific verb+resource+scope: 'Daily OHLC price history for a major market index, covering the whole date range you ask for.' It also explicitly names the sibling it is not (get_index_quote) for the current-level case, so an agent can distinguish it without opening either schema.

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

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

Gives explicit routing: 'For the current level alone, call get_index_quote', and states the remedy for oversized ranges ('Re-request a narrower from_date/to_date for daily rows'). It also tells the agent which construct to base claims on (summary or a present bar) versus the trailing-year figures a quote tool returns.

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

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

Annotations already establish read-only, idempotent, open-world behavior, so the safety profile is covered. The description adds real behavioral context no structured field carries: yearHigh/yearLow are a trailing ~12-13 month feed range with undated extremes, which changes how the agent should present the data. It stops short of describing the full return shape or freshness/latency of 'real-time'.

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?

Long, but the bulk is content-bearing symbol mapping rather than filler, and the core statement plus the historical-tool handoff are front-loaded. The alias list is dense and could be trimmed of redundancy, but nothing reads as padding.

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

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

With no output schema, the description correctly compensates by explaining the semantics of the returned range fields and directing ambiguous-name cases. Together with the annotation coverage, an agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100% and there is only one parameter, so the baseline would be 3. However the description goes well beyond the schema's 'e.g. ^GSPC' stub by supplying a broker/CFD alias map ('US Tech 100'/'NAS100' -> ^NDX, etc.) that lets the agent resolve natural-language index names, plus a warning about near-name collisions.

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

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

Opens with a specific verb+resource: 'Returns the real-time quote for a major market index.' The scope is unambiguous and an agent can separate it from get_index_historical, get_market_performance, and other quote tools from the first sentence alone.

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

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

Explicitly routes the agent away from this tool when the need is YTD/calendar-year changes, dated extremes, or exact 52-week figures ('use get_index_historical'). It also gives concrete disambiguation rules for ambiguous inputs (bare 'Nasdaq', 'S&P 100') and the policy of quoting the index the user named.

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

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

Annotations already declare readOnlyHint=true, 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?

Annotations already cover readOnly/idempotent/openWorld/destructive, so the safety profile is free. The description adds genuinely useful behavior beyond that: newest-first ordering, an archive holding years of stories, the excerpt field, and the handoff to get_article. It does not mention pagination limits, rate limits, or what happens when tickers/category are combined, which keeps it short of a 5.

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

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

Front-loaded with the core purpose and the sibling contrast in the first sentence, then structured Args and a Returns line. Slightly verbose — the same-point repetition about from_date/to_date appears in both the prose and Args — but every section earns its place for a 5-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 present, the description carries the return contract itself ({id, title, excerpt, author, category, date, url, tickers}) and the follow-up path via get_article. Combined with full parameter semantics and annotation-covered safety, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is only 40%, and the description fully compensates with an Args block covering all five parameters, including the non-obvious semantics that from_date is a recency floor and that from_date alone returns today's news rather than stories from around that date. This is meaning the schema alone does not supply.

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

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

States a specific verb+resource and scope: 'Latest TipRanks news articles (newest first) from TipRanks's own editorial/wire feed'. It explicitly distinguishes itself from get_assets_news (text excerpt, archive depth) and routes to get_article for full reads, so an agent can tell it apart from siblings without opening any schema.

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

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

Explicitly enumerates the use cases — general market news with no ticker, ticker-filtered news with summaries, category browsing, and past date-range retrieval — and names the alternative (get_assets_news) plus the condition that selects this tool over it ('get_assets_news only reaches recent articles').

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, destructiveHint=false and openWorldHint, so safety is covered. With no output schema present, the description steps in and specifies what the response contains (average returns, sector breakdown, top/bottom performers), which is real added value beyond the structured fields; it still omits the time window and any response-sizing caveats.

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

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

One front-loaded sentence naming the resource and its return contents, followed by a compact Args block for the single parameter. No filler, though the Args block is slightly redundant with the parameter name already exposed in the schema.

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

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

For a single-parameter, no-output-schema read tool this covers the essentials: what is returned and what values the parameter accepts. The notable gap is the performance horizon (daily, YTD, trailing?) – critical for interpreting 'average returns' – plus no positioning against get_market_movers/get_sector_analysis.

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% – the property is just a bare string with default 'us' – so the description has to carry the load, and it does by enumerating valid market codes ('us', 'ca', 'uk', 'de', 'il', 'au', 'hk', 'sg', etc.). The open-ended 'etc.' and lack of a canonical full list keep it short of a 5.

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

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

States a specific verb and resource ('Returns market-wide performance for a specific country') and enumerates the payload ('average returns, sector breakdown, top/bottom performers'). It does not explicitly distinguish itself from near-neighbours like get_market_movers, get_sector_analysis, or get_market_commentary, so the agent must infer the boundary.

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

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

Usage is only implied by the phrase 'market-wide' and 'for a specific country' – the agent can guess this is the country-level aggregate rather than a single-ticker or sector call. There is no explicit when-to-use, when-not-to-use, or named alternative among the many market/sector 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, the description discloses that this call is free and never counts against the quota, that all other metered calls count even on failure, that handshake/discovery calls are unmetered, and that refused calls are refunded. It also explains the edge case where `used` can exceed `limit` when the cap falls mid-month.

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 summary and then organized into clear, purposeful paragraphs. It is longer than strictly necessary, but each paragraph adds meaningful behavioral detail that helps an agent avoid misinterpreting quota edge cases.

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

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

With no output schema, the description covers the returned fields: calls used, limit, remaining calls, plan tier, and reset time. It also covers free-call status, metering rules, and edge-case behavior, making it fully self-sufficient 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?

The tool has zero parameters and the schema coverage is trivially 100%, so the description does not need to explain parameters. It still adds relevant context by clarifying that invoking this tool has no metering side effects.

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

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

The description states the tool's specific function: reporting the current TipRanks MCP usage against the monthly tool-call quota. It clearly distinguishes itself from the many data-retrieval siblings by focusing on quota state rather than market 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 recommends checking usage before running a large batch of calls, giving clear contextual guidance. It does not name alternatives or exclusion cases, but none are needed since no sibling tool serves this purpose.

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

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

Annotations already declare read-only, idempotent, non-destructive and open-world, so the safety profile is covered; the description adds genuinely new behavior: ~15-minute quote delay, the exact fields returned per row, and the deliberate absence of greeks/IV with an instruction not to estimate them. That is well beyond what the structured fields 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 Args block is tight and front-loaded, and the return-field list is useful. The GREEKS AND IV paragraph is somewhat repetitive, restating the unavailability of greeks/IV across several sentences ('state plainly that greeks and IV are unavailable' vs 'leave delta and IV unestimated, including rules of thumb'), which costs a little economy.

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

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

With no output schema, the description carries the return shape and does so explicitly by enumerating row fields; it also covers latency, the missing-greeks caveat, and every argument. Nothing an agent needs to call this correctly is absent.

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% (just contract_type and expiration_date), so the description must compensate, and it does: it documents ticker as the underlying, the YYYY-MM-DD expiration, ''/'call'/'put' semantics, strike_gte/strike_lte as inclusive strike filters, and limit's default of 50. All six parameters gain 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 opening line states the resource and its scope precisely: option contracts at a single expiration, enriched with price, open interest and volume. That cleanly separates it from get_options_expirations (which enumerates dates) and get_options_contract (single contract), so an agent can route without opening the schema.

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

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

It names the prerequisite tool explicitly ('One of the dates from get_options_expirations') and spells out the full call sequence for a common query pattern (greeks/IV -> get_options_expirations then this tool). It also states what this tool is NOT for, which is exactly the when-not guidance an agent needs.

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

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

Goes well past the annotations (which only declare readOnly/idempotent) by disclosing ~15-minute quote delay and an exact field-coverage boundary — no greeks, no IV, no bid/ask. It further instructs the agent to leave those values unestimated, which is real behavioral guidance that prevents hallucination.

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

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

Front-loaded with the purpose and the key field, then format, then caveats. The greeks paragraph is long but earns its place by heading off a common failure mode; structure is 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 takes on the burden of describing the return surface and does so concretely (price, OI, OI change, volume, day OHLC, last_trade_date). Combined with the delay and field-absence notes, an agent has everything needed to call and report correctly.

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

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

Schema coverage is 100% and the schema already gives the example plus the optional 'O:' prefix. The description adds value by decomposing the OCC format (YYMMDD, C/P, strike-in-thousandths-8-digits), giving the agent a way to validate or construct tickers beyond a single sample.

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

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

States a specific verb and resource ('Snapshot one OCC contract') and enumerates exactly what is returned (price, OI, intraday OHLCV, last trade). The word 'one' implicitly scopes it against the sibling get_options_chain, which returns many 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?

Gives an explicit conditional directive: when a user asks for greeks/IV, call this tool, present what it returns, and state the fields are unavailable. It lacks explicit routing versus get_options_chain or get_options_expirations, but the usage context is clear.

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

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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful filtering context ('Excludes past expirations') and clarifies its role as a prerequisite for chain data, which goes beyond the structured annotations.

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

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

Front-loads the core purpose, then provides usage guidance and a brief args block. The wording is slightly roundabout in the greeks/IV sentence, but overall it is efficient 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, single-parameter read tool with full safety annotations, the description covers purpose, usage, and parameter meaning. Missing details like date format or sorting order are minor and not critical for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the full burden. It identifies the parameter as 'Underlying ticker' and provides an example ('AAPL'), which is sufficient for a single, straightforward ticker 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?

States a specific verb and resource: 'List future expiration dates for a ticker's listed options.' This clearly distinguishes it from get_options_chain and other option-related siblings by focusing on expirations rather than the chain itself.

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

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

Explicitly routes the agent: 'Use the result as input to get_options_chain' and 'Use it FIRST when the user asks for greeks, IV or delta.' The condition for use and the downstream relationship are both stated, leaving little inference needed.

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.