finnhub

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

The annotation readOnlyHint=true already signals a safe read operation, so the description does not need to repeat that. It adds useful context via the REST endpoint and the note that 'all' returns every metric, but does not disclose additional behaviors like rate limits or authentication needs. This is adequate for a simple GET.

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 one concise sentence followed by the REST endpoint. It is front-loaded with the core purpose and has zero filler. Every word earns its place.

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

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

For a two-parameter read-only tool with no output schema, the description provides a sufficient overview of what data is returned (valuation, margins, growth, etc.). It could mention return format, but the REST endpoint and metric categories give enough context for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%: both parameters (symbol and metric) are documented, including the default value for metric. The description mentions metric categories but does not go beyond schema details. Baseline 3 is appropriate since the schema carries the semantic weight.

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

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

The description clearly states the tool provides 'key financial metrics for a company' and enumerates categories like 'valuation, margins, growth, per-share and 52-week ratios.' This is a specific verb-resource pairing that distinctly separates it from sibling tools like finnhub_quote (current price) or finnhub_company_profile (company details).

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

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

The description gives clear context for when to use the tool by listing the types of financial metrics it returns. It does not explicitly name alternatives or exclude other tools, but an agent can infer this is the go-to for fundamental financial ratios. The REST path adds further clarity.

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

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

The annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the 1-year lookback limit and REST endpoint, but does not disclose return format, pagination, or other behavioral details. This modest addition beyond annotations warrants a 3.

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

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

The description is a single, well-structured sentence that front-loads the main function and key constraint. Every word earns its place, with no redundancy or vague language.

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

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

This is a simple read-only news lookup with three required parameters and clear annotations. The description covers the essential purpose and date-range limit, which is sufficient for selection. Without an output schema, it could say more about the return structure, but 'news' reasonably implies a list of articles, so a 4 is appropriate.

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

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

The input schema already provides full descriptions for all three parameters (symbol, from, to) with 100% coverage. The description's reference to 'date range' aligns with the schema but adds no new semantic information, so the baseline score of 3 applies.

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

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

The description clearly states it retrieves 'Latest company news for a symbol over a date range', naming the specific resource and operation. It also cites the REST endpoint, and 'for a symbol' distinguishes it from sibling finnhub_market_news which covers market-wide 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?

The description provides useful context (per-symbol, date range, up to 1 year back) but does not explicitly mention when to use this tool versus alternatives like finnhub_market_news. Usage is implied rather than clearly stated, so it meets the 'implied usage' 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?

The readOnlyHint annotation already establishes the safe, read-only nature. The description adds the REST endpoint, but does not mention rate limits, authentication, or response structure. The phrase 'and more' is vague, providing limited added transparency 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 two sentences, front-loads the purpose, lists key fields, and states the input rule and endpoint. There is no filler or redundant information, making it highly 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?

The tool is simple with three identifier parameters and no output schema. The description covers the main output fields and the input requirement, but does not specify the exact return shape (e.g., single object vs. null). This is adequate but leaves a small gap.

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

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

The schema already documents each parameter and indicates they are alternatives. The description adds the crucial constraint that at least one identifier is required, which is not expressed in the schema's optional fields. This goes beyond the structured data.

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 a 'General company profile' and enumerates specific data fields (name, country, currency, exchange, industry, market cap, etc.), distinguishing it from siblings like finnhub_quote or finnhub_basic_financials. The REST endpoint reference further clarifies the operation.

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 input requirement ('Provide at least one of symbol, isin or cusip') and the field list implies it is for static company data. However, it does not explicitly compare against alternatives, so it misses the 'when-not-to-use' guidance.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context: it covers both upcoming and historical data and supports filtering. The mention of the Finnhub REST endpoint also provides a transparency signal about the underlying API. However, it does not disclose edge cases like default date ranges or response shape, but given the read-only annotation, this is acceptable.

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 includes the REST endpoint as a useful reference. No unnecessary words or fluff.

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

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

For a simple read-only calendar tool with all parameters documented and no output schema, the description is sufficiently complete. It states the resource type, time range coverage, and filter options. It could be more detailed about return values, but the absence of an output schema and the tool's simplicity make this acceptable.

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

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

All three parameters (to, from, symbol) have descriptions in the schema, covering 100% of parameters. The description's mention of 'date range and/or symbol' simply summarizes the schema without adding additional meaning. Since schema coverage is high, a baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a calendar of upcoming and historical earnings releases, with optional filtering by date range and/or symbol. This distinguishes it from sibling tools like finnhub_earnings_surprises and finnhub_ipo_calendar, making the purpose unmistakable.

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

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

The description implies when to use this tool: when you need earnings release dates, optionally filtered by date range or symbol. It provides context but does not explicitly name alternatives or exclusions. The context is clear enough for an agent to select this over peers.

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, so the safe-read nature is covered. The description adds useful detail about the data (actual vs. estimated EPS) but does not disclose additional behavioral traits like response format, pagination, or any limitations. It does not contradict 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 a single concise sentence that front-loads the core purpose and includes the REST endpoint for reference. Every word earns its place 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 only two parameters and full schema coverage, the description provides sufficient context: it names the data type, the comparison, and the period granularity. It does not describe the return structure, but given the low complexity and no output schema, this is a minor gap.

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

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

Schema description coverage is 100%, so the parameters symbol and limit are already well-documented in the schema. The description adds no additional parameter semantics beyond what the schema provides, which matches the baseline for 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 identifies the tool as providing historical quarterly EPS surprises, specifically actual vs. estimated EPS by period. It names the underlying Finnhub REST endpoint, and the 'historical' qualifier distinguishes it from sibling tools like finnhub_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?

Usage context is implied by 'Historical quarterly' and 'by period', suggesting it is for past earnings surprise data rather than future earnings dates. However, there is no explicit guidance on when to prefer this tool over alternatives such as finnhub_earnings_calendar or finnhub_basic_financials.

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 the description adds the REST GET method and the Form 3/4/5 filing types, which provide useful context. However, it does not go beyond that to describe output format, pagination, or any limitations, so it meets the baseline but lacks rich behavioral detail.

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 key purpose and followed by the API endpoint. No filler or redundant information, achieving high clarity in minimal space.

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 three parameters and no output schema, the description gives enough context: the data type (insider transactions), the filing category (Form 3/4/5), and the optional date range. It doesn't describe the return fields but the purpose is clear within the Finnhub family context.

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

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

All three parameters have full schema descriptions covering symbol, from, and to with formats and optionality. The description's mention of 'optionally within a date range' aligns with the schema but adds no extra meaning, so the schema carries the burden.

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

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

The description clearly identifies the resource as insider transactions (Form 3/4/5 filings) for a company with an optional date range, which distinguishes it from sibling tools like market news or financials. The REST endpoint GET /stock/insider-transactions reinforces the intended action, even though no explicit verb like 'retrieve' is used.

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 obtaining insider transaction filings for a company, optionally filtered by date, but it does not explicitly state when to choose this tool over siblings or mention exclusions. No direct alternatives are named, though the sibling list shows distinct financial data endpoints.

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, so safety is covered. The description adds behavioral context that the calendar includes both upcoming and recent IPOs for the given date range, but does not describe return format, pagination, or other potential behaviors. This meets the baseline for a read-only tool with annotation coverage, with modest additional value.

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 includes only relevant information (the REST endpoint). There is no fluff or redundancy, and every word earns its place.

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

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

For a simple read-only tool with two required parameters, well-defined schema, and read-only annotation, the description is mostly complete. However, since there is no output schema, a brief note about the response shape (e.g., array of IPO events) would enhance completeness. The lack of such detail is a minor gap.

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

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

Schema description coverage is 100%, with both 'from' and 'to' clearly documented as required start and end dates with a format pattern. The description merely says 'date range' without adding any semantic detail beyond what the schema already provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states it provides an IPO calendar for a date range, including upcoming and recent initial public offerings. It specifies the resource (IPO calendar) and scope, and is distinct from sibling tools like earnings calendar or market news. The inclusion of the Finnhub REST endpoint further clarifies the exact functionality.

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

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

The description implies when to use this tool: whenever IPO data for a specific date range is needed. It gives clear context about what the tool covers (upcoming and recent IPOs) but does not explicitly mention alternatives or when not to use it. This qualifies as 'clear context, no exclusions'.

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

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

Annotations include readOnlyHint=true, so the safety profile is already disclosed. The description adds minimal behavioral insight beyond that, such as 'latest' implying recency, but does not discuss pagination behavior, return format, or rate limits. It neither contradicts annotations nor enriches them significantly.

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 includes the REST endpoint for reference. Every word earns its place 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 simple news-listing tool with no output schema, the description is adequate but sparse. It covers the main action and category filtering, yet omits any detail about response contents or pagination usage beyond the schema. Given the tool's simplicity and schema coverage, a 3 is reasonable, but it could be more complete with usage oriented guidance.

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 both minId and category having clear descriptions. The description's mention of 'by category' is already captured in the schema, so it adds no new meaning. Baseline 3 is appropriate.

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

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

The description states 'General latest market news by category,' which clearly identifies the resource (market news) and the scope (general, by category). It distinguishes from sibling finnhub_company_news by focusing on market-wide news rather than company-specific news, though it lacks an explicit verb like 'Get' or 'List.'

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 is provided on when to use this tool versus alternatives such as finnhub_company_news. The description does not mention when to prefer this over other news tools or any exclusions, leaving the agent to infer usage from the category parameter.

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, so the read-only nature is covered. The description adds the REST endpoint and mentions 'session' but does not disclose response structure, rate limits, or other behavioral details. 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 single, well-structured sentence that front-loads the core purpose. The REST endpoint is a useful addition and every word earns its place.

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

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

For a simple single-parameter read-only tool with no output schema, the description covers the essential function. However, it could be more complete by specifying expected response fields (e.g., isOpen, session) since there is no output schema to fill that gap.

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

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

The schema fully describes the 'exchange' parameter with a required flag, type, and example. The description's phrase 'for an exchange' adds no new semantic value beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description clearly states the tool provides current market open/closed status and session for an exchange, which is distinct from sibling tools like finnhub_market_news or finnhub_quote. It also includes the specific REST endpoint, making the purpose unambiguous.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. It neither mentions specific use cases nor excludes other tools, so the agent must infer usage from the purpose 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, and the description adds the grouping criteria and REST endpoint. However, it does not disclose return format, pagination, or other behavioral traits beyond what the annotations suggest. This is acceptable 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 only two sentences, front-loaded with the core purpose. The REST endpoint reference is useful and every word serves a purpose with no redundancy or filler.

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

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

For a simple read tool with full parameter schema and a safety annotation, the description conveys the core idea. However, with no output schema, it would benefit from explicitly stating the return format (e.g., a list of ticker symbols), which is currently only implied by 'Peer companies'.

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 both symbol and grouping parameters fully described. The tool description adds no new parameter semantics beyond the schema, so it relies on the schema, which is adequate.

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 peer companies for a symbol, specifying the criteria (same country and GICS sub-industry). The REST endpoint reference adds precision and distinguishes this from sibling tools that fetch other data 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?

The description implies usage when peer companies are needed, which is clear from the resource name and behavior. However, it does not explicitly mention alternatives or when-not-to-use scenarios, though sibling tools are sufficiently differentiated by their own descriptions.

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

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

The annotation readOnlyHint already indicates a read operation, and the description adds valuable behavioral context: the premium-tier limitation (may return 403) and the REST endpoint. It also discloses the output structure (high/low/median/mean), exceeding what annotations alone 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 two sentences, front-loaded with the core purpose, and succinctly adds the premium note and REST endpoint. Every sentence contributes meaningful information with no waste.

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

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

For a tool with a single parameter and no output schema, the description provides a complete picture: what it does, what data it returns (high/low/median/mean), and a key caveat (403 on free plan). No significant 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 100% and the description does not add extra semantic meaning beyond the schema's symbol description. The baseline of 3 is appropriate since the schema already documents the only parameter adequately.

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

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

The description clearly states the tool provides 'Analyst price targets for a symbol' and specifies the output categories (high/low/median/mean), distinguishing it from sibling tools like quote or recommendation_trends. The inclusion of the REST endpoint further reinforces the specific 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?

The description gives clear context for when to use the tool (when needing analyst price targets for a symbol) and includes a caveat about premium-tier access potentially causing 403 errors. However, it does not explicitly mention alternatives or exclusions, so it stops short of a 5.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description adds value by listing the exact response fields and the REST endpoint. It discloses the output structure (c, d, dp, h, l, o, pc, t), which is useful behavioral context beyond the annotation.

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, front-loaded with the core purpose, and contains no filler. It lists output fields in a compact format and includes the endpoint reference, making every sentence informative.

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

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

For a simple quote tool with one parameter and read-only annotations, the description is complete. It explains the return fields, which is especially important since there is no output schema, and provides the REST endpoint for further reference.

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

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

The schema fully documents the single parameter 'symbol' with a clear description and example, so the schema carries the semantic weight. The tool description adds no additional parameter-level information, but it doesn't need to given 100% 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 provides a real-time quote for a stock and enumerates the returned fields (current price, change, percent change, etc.), making its purpose specific and unambiguous. This distinguishes it from sibling tools like company_news or market_status, which address different Finnhub endpoints.

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 offers clear context by indicating this is for real-time stock quotes, which implies the right use case. However, it does not explicitly mention when not to use it or point to alternative tools for related but distinct data needs, such as historical data or detailed financials.

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

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

The annotations declare readOnlyHint=true, and the description adds that the tool returns counts of analyst ratings over time, which is consistent with a read-only operation. It does not contradict annotations, but it also does not disclose more detailed behavioral aspects such as response format, time periods covered, or any limitations. The REST endpoint hint provides some contextual value.

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, focused sentence that conveys the core function (analyst recommendation trends with counts by period) and includes the REST endpoint. It is front-loaded with the most important information and contains no unnecessary words, making it highly concise 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?

The tool has a single parameter and no output schema, and the description provides a high-level overview of the returned data (counts of recommendations by period). However, it does not specify the exact response structure, the granularity of periods (e.g., monthly, quarterly), or any edge cases. Since no output schema is present, the description should carry more weight to fully prepare the agent.

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

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

The schema already documents the single symbol parameter with a clear description ('Stock ticker symbol, e.g. 'AAPL' (required).'), and schema coverage is 100%. The tool description adds no additional meaning about the parameter, so it does not improve upon the schema. Baseline 3 applies.

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

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

The description clearly states the tool's function: providing analyst recommendation trends over time, specifically counts of strong buy/buy/hold/sell/strong sell by period. This specific verb+resource structure distinguishes it from sibling tools like finnhub_price_target, which focuses on price targets. The inclusion of the Finnhub REST endpoint further clarifies the exact data source.

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 does not provide any guidance on when to use this tool versus alternatives. There is no mention of scenarios, prerequisites, or exclusions. The agent must rely solely on the tool name and description to infer its applicability, which is insufficient for proper alternative selection.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds the REST endpoint and scope ('all symbols'), which is useful but not rich. It does not disclose pagination behavior, output format, or rate limits, so transparency is adequate but limited.

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, front-loaded with the core purpose, and includes the REST endpoint as a secondary detail. Both sentences contribute value 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 list tool with detailed schema and readOnlyHint, the description is minimally sufficient but omits return format and pagination considerations. Given no output schema, a bit more detail on what the tool returns would improve completeness.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already provides; it merely reinforces the exchange scope.

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 'List all symbols supported on an exchange', specifying the verb (list), resource (symbols), and scope (exchange). It distinguishes from sibling tools like finnhub_symbol_search by implying a comprehensive list rather than a search, but lacks explicit differentiation.

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 is provided on when to use this tool instead of alternatives. The description only states what the tool does and the REST endpoint, without any context about use cases, prerequisites, or competing tools.

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

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

The annotation readOnlyHint=true is consistent with the description, which also mentions the GET /search endpoint. The description adds that results include best-matching symbols with descriptions and types, but it does not disclose pagination, rate limits, or error behavior. It provides some extra context beyond annotations, but not a substantial amount.

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

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

The description is two concise sentences. The first states the core purpose and output, and the second provides the REST endpoint. Every word earns its place, 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 simple two-parameter read-only search tool, the description is sufficiently complete. It states the query semantics and the nature of the return value ('best-matching symbols with descriptions and types'), compensating for the lack of an output schema. It does not address the sibling finnhub_stock_symbols tool, which would make it more complete, but the tool itself is adequately contextualized.

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

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

The input schema has 100% coverage with descriptions for both parameters (q and exchange). The description's 'by name or ticker' merely reiterates the existing q description, adding no new semantic information. With high schema coverage, the baseline of 3 applies.

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

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

The description clearly states the tool searches for stock symbols by name or ticker and returns best-matching results. It names the resource and the action, but does not explicitly distinguish itself from the sibling finnhub_stock_symbols tool, so it falls short of a 5.

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

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

The usage is implied: use this when you need to look up stock symbols by name or ticker. However, there is no explicit guidance on when not to use it, nor any mention of alternatives like finnhub_stock_symbols, leaving the agent to infer the choice.

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