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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context beyond that: 'Always returns the top N by market cap starting at rank 1; there is no paging or filtering, so a coin outside the top limit will not appear no matter how it performed.' This clarifies the limitation and confirms the openWorldHint annotation. It also mentions the data source. Minor gap: it doesn't specify the exact return structure, but annotations cover safety.

Agents need to know what a tool does to the 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, tightly packed with purpose, usage, alternative, and limitation. There is zero fluff; every sentence adds value. It is front-loaded with the core purpose before diving into guidance.

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

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

Given the tool's low complexity, no output schema, and good annotations, the description covers the essential contextual aspects: what it returns (ranked table with performance), when to use it, and its limitations (no paging/filtering). It lacks an explicit statement that the output is a JSON array, but that is easily inferred from 'ranked table'. Overall it provides sufficient context for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra param semantics: it references `limit` in the limitation sentence and repeats that vs_currency does not filter coins. Since the schema already fully describes both parameters, the description adds no significant new meaning. It does reinforce the behavior but doesn't go beyond what the schema provides.

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

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

The description clearly states the tool lists the largest cryptocurrencies by market cap with 24h and 7d performance, sourced from CoinGecko. It explicitly distinguishes itself from the sibling tool get_crypto_price, saying to use that when specific coins are known. The verb 'ranked table' and resource 'largest cryptocurrencies by market cap' clearly define the tool's purpose.

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

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

The description provides explicit when-to-use guidance: 'Use this to survey or discover the market — what are the biggest coins, what moved this week.' It also gives a clear alternative: 'When you already know which coins you care about, use get_crypto_price instead.' This explicitly covers usage and alternatives.

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

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

Annotations only say readOnlyHint, openWorldHint, destructiveHint. The description adds critical behavioral context beyond these: it accepts both tickers and ids, reports unknown names back rather than failing the whole call, and clarifies prices are 'near-real-time but not exchange-official.' It also names the data source (CoinGecko), giving the user a full picture of behavior and limitations.

Agents need to know what a tool does to the 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 long, front-loaded with the primary purpose, and every sentence earns its place: purpose, usage alternative, input format/behavior, and boundary/alternatives. There is no fluff or redundancy. It is dense with useful information while remaining readable.

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

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

Even though there is no output schema, the description lists the return fields (spot price, 24h change, market cap, 24h volume), covers input formats, error behavior, data source and freshness, and defines boundaries with alternative tools. It fully equips the agent to select and invoke the tool correctly, making the lack of an output schema non-problematic.

Complex tools with many parameters or behaviors need more documentation. 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%, but the description still adds significant meaning beyond the schema. It explains the `coins` parameter accepts common tickers or CoinGecko ids, and clarifies how unknown names are handled ('unknown names are reported back rather than failing the whole call'). This goes beyond the schema's `e.g. ["btc", "eth", "solana"]` example, providing real-world usage 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 opens with a specific verb and resource: 'Spot price, 24h change, market cap, and 24h volume for specific cryptocurrencies you name, from CoinGecko.' This clearly states what the tool does and distinguishes it from get_crypto_market, naming the sibling tool and the difference in use case. The purpose is unmistakable.

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

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

Usage guidance is explicit: 'Use this when you know which coins you want; use get_crypto_market instead to rank the market or discover the largest coins.' It also states exclusions: 'Stocks and FX are not available here — use get_stock_quote and get_fx_rate.' This gives clear when-to-use and when-not-to-use guidance with named 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, openWorldHint), the description adds valuable behavioral details: annual frequency, reporting lags causing omitted years rather than zeros, coverage variation by country/indicator, and the possibility of empty results for valid pairings. This provides a comprehensive behavioral model.

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

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

Three dense, purposeful sentences: the first delivers the what, the second provides usage boundaries, and the third covers important caveats. No filler or redundant phrasing; every clause earns its place.

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

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

Given the absence of an output schema, the description covers output ordering, change calculation, temporal limitations, and empty-result behavior. It is sufficiently complete for an agent to select and invoke the tool correctly without further assumptions.

Complex tools with many parameters or behaviors need more documentation. 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 documents all three parameters with descriptions (100% coverage). The description reinforces and extends this by explaining how 'limit' behaves (newest year first, annual), how 'country' and 'indicator' interact (coverage varies, valid pairing can be empty), and the meaning of annual-only data. It adds contextual semantics without needing to re-list each indicator.

Input schemas describe structure but not intent. Descriptions should explain 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 retrieves macroeconomic time series by country from the World Bank, listing available indicators and output ordering (newest year first with year-over-year change). It explicitly contrasts with company/security data covered by market-data and SEC tools, distinguishing this tool 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?

It explicitly says 'Use this for country-level economics' and notes it cannot answer questions about this month or this quarter because data is annual only. It also identifies that individual company/security questions belong to market-data and SEC tools, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint and destructiveHint, but the description adds valuable behavioral context: the ECB publishes once per business day (daily fix), non-ECB pairs fall back to Yahoo, and rates are indicative mid-market not dealable quotes. This goes beyond the annotations to explain data freshness and reliability.

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

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

The description is a single dense paragraph but every sentence earns its place. The core function is front-loaded in the first sentence, followed by data-source caveats, a crypto exclusion, and a realistic usage warning. There is no fluff or repetition of schema data.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 explains the key return values: the rate, change since prior session, and converted total when amount is given. It also covers data provenance, fallback behavior, and the indicative-vs-dealable caveat, making it comprehensive for an FX converter.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that 'amount' is 'Amount of the base currency' and that when given, the converted total is returned. It reinforces the schema's parameter descriptions and clarifies the conversion direction.

Input schemas describe structure but not intent. Descriptions should explain 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 'Convert between two currencies at the latest published reference rate', which is a specific verb and resource. It clearly distinguishes itself from siblings by stating 'Use get_crypto_price for crypto — BTC and ETH are not currencies here', and clarifies the scope to fiat/ECB/Yahoo currencies.

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

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

The description gives explicit when-not guidance: 'Use get_crypto_price for crypto' and excludes BTC/ETH. It also sets expectations about the rate being a daily fix rather than a live tick, helping the agent decide if real-time data is needed. This is more than just a list of alternatives—it provides contextual exclusions.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds valuable behavioral context: it separates open-market trades from mechanical activity, warns that most reported insider selling is mechanical, states the tool is US-only, and clarifies that it does not interpret or predict share prices. This aligns with annotations and provides deeper insight into the tool's output semantics.

Agents need to know what a tool does to the 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 multi-sentence but each sentence serves a purpose: stating the function, highlighting freshness, explaining the open-market vs. mechanical distinction, and adding scope and interpretation caveats. It is slightly verbose but well-structured and front-loaded with the core purpose, making it easy for an agent to quickly understand the tool's value.

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

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

With no output schema, the description adequately conveys what the tool returns (insider buying/selling activity from Form 4) and the key interpretive distinction between open-market and mechanical trades. It does not enumerate exact return fields, but given the tool's moderate complexity and clear parameter schema, the description provides sufficient context for correct usage.

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

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

The input schema provides comprehensive descriptions for all three parameters (company, limit, since), including guidance on the limit parameter's cost implications. The description itself adds no additional parameter-specific details beyond what the schema already covers, so the baseline score of 3 applies due to high schema coverage.

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

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

The description clearly states the tool retrieves insider trading activity from SEC Form 4 filings, specifying the subjects (officers, directors, 10% owners) and the nature of the data (buying/selling). This distinguishes it from sibling tools like get_stock_quote or get_price_history, which focus on market prices rather than insider transactions.

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

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

The description provides strong contextual guidance: it notes the freshness (2 business day reporting requirement), the crucial distinction between open-market and mechanical trades, and the US-only scope. It implicitly tells the agent when to use this tool (for insider trading signals) and cautions against misinterpreting mechanical activity, but it does not explicitly name alternative tools for other data types.

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

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

Annotations only indicate read-only and non-destructive. The description adds substantial behavioral context: data source (Yahoo Finance), return value composition (OHLCV + summary), intraday data retention limitations, and expected gaps in the series due to omitted candles. This goes well beyond annotation 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 dense but every sentence contributes: primary output, usage examples, sibling differentiation, exclusions, constraint caveat, and gap explanation. No fluff, well-front-loaded.

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

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

Despite no output schema, the description explains the return structure (OHLCV, period return, summary), constraints, exclusions, and expected anomalies. With 4 parameters and rich sibling context, this is complete for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, providing baseline of 3. The description enriches this with concrete interval/range rules (e.g., 'pair 1m–1h with 1d/5d/1mo', 'use 1d or coarser for 1y and beyond') and explains max_rows downsampling behavior. It adds meaningful operational 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 historical OHLCV candles plus a period return and summary for stocks, ETFs, indices, and FX pairs. It explicitly differentiates from get_stock_quote for current price needs, giving a specific verb and resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 examples ('how has NVDA done this year?'), when-not-to-use (current price → get_stock_quote), exclusions (cryptocurrencies), and practical guidance on interval/range pairing to avoid empty responses. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavior: chronological ordering (newest first), inclusion of amended forms when requesting base forms, form type semantics (10-K annual, 8-K event, etc.), and direct document URLs. This enriches the safety profile with functional details.

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

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

The description is longer than a single sentence but every clause earns its place: it covers purpose, output, form types, alternatives, and limitations without redundancy. The opening sentence front-loads the core function. Slightly dense but well-structured, earning 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?

For a tool with moderate complexity (3 params, no output schema), the description provides sufficient context: what it produces, how to filter, when to use it versus alternatives, and geographic scope. Since no output schema exists, the mention of 'direct document URLs' gives a clear expectation of the return value. The tool is well-covered.

Complex tools with many parameters or behaviors need more documentation. 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% (all three parameters have descriptions), so the baseline is 3. The description adds semantic value by explaining form type filters (e.g., '10-K annual report') and the amended-forms rule ('10-K/A is returned when you ask for its base form'), which are not fully captured in the schema parameter descriptions. This extra context justifies a score above baseline.

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

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

The description clearly states the tool's function: 'Recent SEC EDGAR filings for one US-listed company, newest first, with direct document URLs you can cite or fetch.' It specifies the output (filings), ordering, and purpose (locate documents), and distinguishes it from siblings by mentioning search_sec_filings and get_sec_financials as alternatives for different needs.

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

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

The description gives explicit when-to-use guidance: 'Use this to find documents for a company you can already name.' It also names alternatives and their purposes—'Use search_sec_filings instead to search filing text across all companies, and get_sec_financials to read reported numbers rather than locate documents'—plus a clear scope limitation ('US SEC registrants only').

Agents often have multiple tools that could apply. Explicit usage 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 readOnly and non-destructive. The description adds valuable context: use of as-filed audited figures rather than estimates, handling of restatements (most recently filed value returned), tag differences between filers, and US-only scope. 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 multi-sentence but each sentence earns its place—purpose, use guidance, restatement behavior, tag nuances, and scope. It's well-structured and front-loaded, with no redundant wording.

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

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

With no output schema, the description supplies necessary return-value context: rows labelled by period, most-recent value on restatements, and tag naming. It covers key limitations (US registrants only) and data provenance. Sufficient for an agent to invoke correctly.

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

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

Schema covers all 4 parameters at 100%, so baseline is 3. The description further explains concept aliases (tried against several us-gaap tags) and the meaning of period/limit in context. It doesn't fully describe every param but adds meaningful context beyond the schema.

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

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

The description clearly states the tool reports financial line items from SEC XBRL filings as time series, with specific examples (revenue, net income, EPS, etc.). It distinguishes itself from siblings like get_sec_filings ('want the documents rather than the numbers') and market-data 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?

Explicit guidance is given: 'prefer this over any market-data tool for fundamentals' and 'Use get_sec_filings instead when you want the documents rather than the numbers.' This provides clear when-to-use and when-not-to-use instructions.

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

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

The description adds meaningful behavioral context beyond the annotations: price delay up to ~15 minutes, non-official prices, and independent symbol lookup behavior. These details help the agent understand reliability and failure modes, which annotations do not convey.

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

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

Every sentence serves a distinct purpose: core function, symbol format, usage alternatives, and limitations. The description is front-loaded with the primary purpose and is appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description completely covers what the tool returns, how to format inputs, how to use alternatives, and important caveats. It also handles multi-symbol behavior, making it self-sufficient for correct invocation.

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

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

Schema coverage is 100% and the parameter description includes basic examples. The tool description enriches this with Yahoo-style symbol formats (e.g., international suffixes like RELIANCE.NS, 7203.T) and edge-case behavior (one bad symbol does not fail the rest), adding value beyond the schema.

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

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

The description clearly states the tool returns 'Latest price and daily change for one or more stocks, ETFs, or indices, from Yahoo Finance.' This is a specific verb+resource+scope definition and distinguishes from siblings by explicitly referencing get_price_history and get_crypto_price for other use cases.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: 'Call search_symbols first if you only have a company name' and 'use get_price_history for a series or a period return, and get_crypto_price for cryptocurrencies.' This is clear and actionable.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that filings before 2001 are not indexed, results are ranked by EDGAR relevance which can favor company names, totals above 10,000 are approximate, and quote matching behavior. This fully surfaces non-obvious behavioral traits.

Agents need to know what a tool does to the 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 in the first sentence, then packs each additional sentence with specific, non-redundant guidance (quote behavior, sibling distinction, ranking caveat, count approximation, coverage limit). Every sentence adds value without unnecessary padding.

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

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

For a search tool with no output schema, the description covers scope, time coverage, ranking oddity, exact-match behavior, count precision, and when to choose an alternative. This is comprehensive enough for an agent to make informed invocation decisions, including caveats that are not derivable from schema or annotations.

Complex tools with many parameters or behaviors need more documentation. 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 a baseline of 3 applies. The description adds meaningful semantics for the query parameter by explaining that unquoted terms match loosely and produce noise, while quoted phrases yield exact matches. It does not introduce syntax for other parameters, but the added query guidance justifies a 4.

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

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

The description clearly states the tool searches the full text of all SEC filings since 2001 to find companies discussing a topic, with a concrete example. It also distinguishes itself from the sibling get_sec_filings by positioning this as discovery across companies versus a more direct company-specific lookup.

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

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

Explicit guidance is provided: 'Use this for discovery across companies' and 'When you already know the company, get_sec_filings is more direct.' It also explains the exact-phrase versus unquoted search behavior, telling users when to use quotes and warning about noise.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context beyond annotations: the search covers equities, ETFs, and indices across global exchanges, may return multiple listings for the same company, and advises preferring the listing whose exchange matches the market. This helps the agent interpret results correctly. No contradictions with annotations.

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

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

The description is four sentences, front-loaded with the core purpose, followed by usage guidance, scope/ambiguity handling, and an alternative. Every sentence adds value with no redundancy or filler. It is concise yet comprehensive for a search tool.

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

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

For a search/lookup tool with no output schema, the description covers the workflow (name → symbol → pass to quote/history), scope (global equities/ETFs/indices), ambiguity handling (multiple listings, exchange preference), and an alternative path (SEC filings). It does not detail the return format, but the purpose implies the response includes ticker symbols, and the 'may return several listings' comment hints at array-like output. This is sufficient given the tool's simplicity and the annotations.

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

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

The input schema provides full descriptions for both query and limit, with 100% schema coverage, so the baseline is 3. The description adds an example ('Apple' → AAPL) and mentions that the search covers global exchanges, but these do not significantly enhance parameter understanding beyond the schema. The guidance about preferring exchange matches relates to result interpretation, not parameter syntax.

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

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

The description clearly states the action: 'Resolve a company or fund name to a ticker symbol using Yahoo Finance search.' It specifies the resource (company/fund names), the output (ticker symbol), and the method (Yahoo Finance search). It also differentiates from siblings by instructing to call this first when you have a name rather than a symbol, and by noting that get_sec_filings accepts a name directly without needing this lookup.

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

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

Explicit guidance is provided: 'Call this first whenever you have a name rather than a symbol' and then pass the symbol to get_stock_quote or get_price_history. It also gives an exclusion/alternative: for US companies needing SEC data, get_sec_filings accepts a company name directly. This clearly tells the agent 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.