yfinance-mcp-ts

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

No annotations are supplied, so the description carries the behavioral burden. It discloses the return format (compact table, text by default, json on request), which is useful, but says nothing about rate limits, permissions, pagination, or the semantics of max_results truncation.

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 short sentences, front-loaded with what is returned, then the use case, then the format option. No filler or redundancy; each sentence earns its place.

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

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

For a simple two-parameter read tool with no output schema and no annotations, the description covers purpose, use case, and output format sufficiently to call it correctly. It could say a bit more about how max_results behaves when truncated, but nothing essential is missing.

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

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

Schema description coverage is 100% and both parameters are documented there, including the format enum and its default. The description only restates the default and the json switch, adding no meaning beyond the schema, so 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?

States a specific verb and resource ('Returns available currency pairs') and the output shape ('compact table'), which is enough for an agent to know this is the forex-symbol lookup tool. It doesn't explicitly contrast itself with any sibling, but none of the stock-oriented siblings overlap, so disambiguation is implicit rather than stated.

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?

'Use to find forex pair symbols' gives a clear positive trigger for invoking the tool. There is no statement of when not to use it or which sibling to prefer for related data, but for a single-purpose lookup tool the context is adequate.

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?

No annotations are provided, so the description carries the full burden. It discloses the returned fields and the default output format, but omits behavioral details such as authentication requirements, rate limits, error handling, or symbol validation.

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 short, front-loaded sentences with no redundant or filler content. The return content, usage context, and format control are each addressed directly.

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 tool with full schema coverage and no output schema, the description adequately explains what is returned and how to control the format. It leaves minor gaps around limitations and error behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the format default and mentions structured JSON output, but adds little semantic detail beyond what the schema already documents for the two parameters.

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

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

States a specific verb and resource: returns EPS history with surprise %, next estimate, and revenue trend. It clearly identifies the tool's output, though it does not explicitly distinguish itself from the sibling 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?

Provides a clear usage context: 'Use for earnings analysis and surprise tracking.' It does not specify exclusions or name alternative tools, but the intended use case is explicit.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses output-format behavior (text by default, json for structured data) but says nothing about permissions, rate limits, or how results are ordered/paginated.

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 short sentences, front-loaded with the core behavior and ending with an actionable output-format hint. Minor redundancy with the schema's format default, but no wasted 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?

All four optional parameters are documented and the description states what is returned (earnings announcements with EPS estimates). With no output schema, a brief mention of return shape is present; only edge details like result ordering are missing.

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

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

Schema description coverage is 100%, so every parameter (start, end, format, max_results) is already documented in the schema. The description only restates the format default, adding no syntax or constraint beyond the schema, so 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?

States a specific verb and resource ('Returns upcoming earnings announcements with EPS estimates') and frames it as a calendar/tracking view. It does not, however, distinguish itself from the sibling get_earnings, which returns reported results — that ambiguity is left for the agent to resolve.

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?

'Use for tracking reporting dates across the market' implies a use case but gives no explicit when-not guidance and never names or contrasts with the sibling get_earnings. Usage is inferred rather than 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?

With no annotations at all, the description carries the full behavioral burden. It discloses output modes and defaults (summary vs full, text vs json), which is useful, but says nothing about auth requirements, rate limits, multi-symbol behavior, or how results are returned when multiple symbols are passed.

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 tight sentences, front-loaded with the return value, then defaults. No filler, though it is short enough that it could have afforded one routing sentence to a sibling without bloat.

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?

A five-parameter, no-output-schema tool with no annotations needs decent coverage. The description handles the mode/default decisions well but leaves multi-symbol behavior, data recency, and any auth considerations unaddressed, so it is adequate rather than complete.

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

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

Schema description coverage is 100% with four documented enums, so the schema already explains type, detail, format, and frequency, including their defaults. The description restates the summary/detail and text/json defaults but adds no format syntax or edge-case meaning beyond the schema.

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

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

States a specific verb and resource ('Returns financial statements') plus the added value ('key metrics and YoY% changes'). It is clear what the tool produces, though it never distinguishes itself from nearby siblings like get_key_stats 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 gives mode guidance ('Default: summary mode', 'use detail=full for all', 'set format=json for structured data'), which is really parameter-usage guidance rather than when-to-use-this-vs-an-alternative. No alternative sibling is named or excluded, so 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?

With no annotations, the description carries the full behavioral burden, and it mostly restates output-format mechanics ('Text default; set format=json') that the schema already encodes. It never states that the call is read-only, what the date window defaults to when start/end are omitted, whether listing data is delayed or live, or anything about limits — all material for an unannotated data-retrieval tool.

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 short sentences, front-loaded with what is returned before the usage hint and the format note. Every sentence is on-topic, though the middle sentence is close to filler given how self-evident the IPO domain is.

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

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

No output schema exists, and the description partly compensates by naming the returned content ('pricing and deal details'). For a simple, zero-required-parameter query tool with 100% schema coverage this is close to sufficient, with the main gap being the default date-window behavior.

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 four fully documented, optional parameters, so the schema already does the heavy lifting and a 3 baseline applies. The description adds the format=json excerpt, but that duplicates the enum in the schema and adds nothing about how start/end bound the returned IPO window.

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 and resource ('Returns upcoming and recent IPO listings with pricing and deal details'), which is specific and cannot be confused with any sibling tool, all of which cover stocks, financials, options, screeners, or calendars. It stops short of explicitly contrasting itself with siblings, but no sibling overlaps its domain, so differentiation is inherent.

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?

'Use for tracking new market listings' gives an implied usage context but names no alternatives, no when-not conditions, and no prerequisites. For a domain as distinct as IPOs this is workable, but it is guidance by assertion rather than 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?

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only operation ('Returns') and discloses the default output format and the JSON option, but does not mention permissions, rate limits, error handling, or data freshness.

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

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

Two sentences with zero waste: the first states purpose and scope, the second gives usage guidance and format details. The most important information is front-loaded.

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

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

For a simple two-parameter read tool with no output schema, the description covers purpose, usage, and output format adequately. It could be improved by specifying the exact return structure or error behavior, but it is 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 description coverage is 100%, so the schema already documents both parameters. The description reinforces the format default and JSON option, but adds no syntax or semantic details 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 states a specific verb and resource: 'Returns advanced statistics' with concrete examples (PEG, beta, EV ratios, margins, growth). It also distinguishes the tool from the sibling get_stock_summary by positioning it for 'deep fundamental analysis beyond' that 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?

It gives clear usage context ('Use for deep fundamental analysis') and names an alternative (get_stock_summary), but does not explicitly state when not to use it or list other alternatives like get_financials. This is clear context without full 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?

No annotations are provided, so the description carries the full burden. It does disclose the default output mode ('Text default; set format=json') which is useful behavioral context, but says nothing about read-only nature, rate limits, or data freshness for a live market feed.

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 compact sentences, front-loaded with what is returned before usage and formatting notes. No filler, though the second and third sentences are quite terse.

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 describes the return payload (indices with price, change, percent change) and both output modes. For a two-optional-parameter read tool this is nearly complete; only source/freshness details are missing.

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

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

Schema description coverage is 100%, so both parameters (format, country) are already documented with defaults and enum values. The description only restates the format default and ignores the country parameter, adding no meaning beyond 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?

States a specific verb ('Returns') and resource ('major market indices') plus the returned fields (price, change, percent change), which contrasts with the stock-level siblings like get_stock_price or get_stock_summary. It does not name a sibling explicitly, so it stops 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?

Gives clear usage context: 'Use for broad market overview.' This tells the agent when this tool is the right pick versus per-symbol tools. No explicit exclusions or named alternatives, which keeps it at a 4.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses defaults (nearest 3 expirations, summary detail, text output), but omits error behavior for invalid symbols/expirations, rate limits, and what 'full' detail actually contains.

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 tight sentences, no filler, with the core purpose front-loaded before the default behavior and the format switch. Every clause carries information.

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

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

For a 6-param read tool with no output schema and no annotations, the description covers the essential operating defaults and output-format switch. It leaves some gaps (detail=full semantics, failure modes) but nothing that would cause a miscall.

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

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

Schema description coverage is 100%, so every parameter is already documented with type, enum values, and defaults. The description largely restates those defaults (text format, nearest 3 expirations) rather than adding new semantics, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Returns option chain') plus the scoping behavior ('ATM-anchored strike window'), which clearly distinguishes it from siblings like get_stock_price or get_stock_history. An agent can identify the tool 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 clear context: default returns nearest 3 expirations summary, and the expiration param should be used for a specific chain. It stops short of naming alternatives or when-not-to-use conditions, but the operating context is unambiguous.

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

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

With no annotations, the description carries the full burden. It discloses the returned data (analyst consensus and a 4-month trend) and the output format control (default text, json for structured data). It does not explicitly state read-only safety, rate limits, or data freshness, but for a simple read endpoint this is strong coverage.

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

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

Three short sentences, front-loaded with what the tool returns, followed by usage then format. No filler or repetition. Efficient and 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?

For a simple two-parameter read tool with no output schema and no annotations, the description provides the necessary return content, usage context, and format control. Missing only minor details like data freshness or symbol limits, which are 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 100%, so the schema already documents both parameters and the format enum. The description adds minor value by clarifying that json yields structured data and that text is the default, but this largely restates the schema's default note. 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 names a specific verb ('Returns') and resource ('analyst consensus and 4-month recommendation trend'), and adds a use case ('sentiment analysis'). It does not explicitly differentiate from sibling tools like get_stock_summary or get_key_stats, which could overlap in analyst data, so it stops 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?

It provides an implied usage context ('Use for sentiment analysis on a stock'), but offers no explicit when-to-use criteria, when-not-to-use conditions, or named alternatives among the many sibling tools. This is adequate but incomplete 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?

No annotations, so the description carries the full burden. It discloses the default text format, the JSON alternative, and the default count of 10 indirectly via schema. It doesn't state rate limits, caching, or what happens with an invalid screener name, but for a read-only screener invocation this is adequate if minimal.

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

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

Two tight sentences, front-loaded with the core action, then the dependency and format options. 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?

Given 4 params with full schema descriptions and no output schema, the description covers the key behavioral facts an agent needs: prerequisite call, default format, and JSON option. It could mention what the compact table contains or error behavior, but it's 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%, so the schema already documents count, fields, format, and screener with examples and defaults. The description adds only the format default and the count=10 default, which duplicates schema content. Baseline 3 applies when 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?

States a specific verb (runs/returns) and resource (stock screener) and clarifies the output form (compact table). It doesn't differentiate from siblings like get_trending or list_screeners beyond naming list_screeners as a prerequisite, but the purpose is unambiguous.

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

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

Explicitly directs the agent to call list_screeners first to find screener names and explains the default format versus format=json. Lacks explicit when-not-to-use guidance (e.g., distinguishing from get_screener_info), but the prerequisite 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the return shape broadly ('detailed metadata... including criteria' and 'Returns JSON'), but says nothing about permissions, error behavior when a screener name is invalid, or whether the lookup is read-only. Adequate but thin for an unannotated tool.

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 short sentences with the core purpose front-loaded and no padding. The trailing 'Returns JSON' is low-value since it is the expected default for this API, but it costs almost nothing.

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 tool with no output schema and no annotations, the description covers purpose, intended use, and return content. The remaining gap is routing against the get_screener sibling, which is a minor omission given 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?

Schema coverage is 100% and the single parameter is fully described in the schema ('Screener name to get information about'). The description adds no format, casing, or discovery guidance (e.g., where valid names come from, presumably list_screeners), so it does not exceed the schema 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?

Clear specific verb (returns metadata) and resource (a specific screener), with the added scope of 'including criteria'. It distinguishes itself from list_screeners by being singular and detail-oriented, though it never names the near-identical sibling get_screener, so the differentiation is implied rather than 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?

The sentence 'Use to understand what a screener filters before running it' gives a genuine usage context, which is more than most. However, it offers no exclusions and does not distinguish the tool from the very similar get_screener sibling, so the agent must infer which one to pick.

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?

No annotations are provided, so the description carries the full load. It does disclose the default output format (text) and that results are both 'upcoming and recent', which is useful scope context, but it says nothing about permissions, rate limits, or data freshness/latency. Adequate but thin for a no-annotation tool.

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 short sentences with the core purpose front-loaded and no filler. The final sentence partially duplicates the schema's format default, a minor redundancy that keeps it from 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?

There is no output schema, so the description should sketch the return value; 'splits with ratios' plus the text/json toggle covers the essentials for a simple read tool. Missing only secondary detail such as ordering or pagination of max_results, which keeps it below 5.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the YYYY-MM-DD format and the text default. The description's mention of format=json merely restates the enum, adding no syntax or default semantics beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource (returns stock splits with ratios), which an agent can immediately distinguish from price, profile, or financials siblings. It does not explicitly name a sibling it differs from, but the resource is unambiguous and unique in the toolset, so it falls just short of 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?

'Use for tracking share split events' gives one implied usage context but no when-not conditions and no named alternatives. With 20 sibling tools, an agent gets no routing guidance beyond the obvious topic match, so this is minimum viable.

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

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

With no annotations, the description carries the full behavioral burden. It restates behaviors already in the schema (auto-aggregation, default text format) but does not disclose truncation behavior (max_rows defaults to 52, which materially clips long ranges), multi-symbol return semantics, rate limits, or error handling. Too thin for a 9-parameter data tool with zero annotation coverage.

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

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

Three short sentences with the core capability front-loaded and no padding. The format sentence partially duplicates the schema default, which keeps it from being fully waste-free.

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 9-parameter tool with no output schema and enum-rich inputs, the description covers purpose, primary use case, and output format choice, but leaves out what multi-symbol requests return, how row truncation works, and whether start/end and period interact. Adequate but with real gaps an agent would hit when invoking it.

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

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

Schema description coverage is 100%, so every parameter is already documented, and the description adds no syntax or format detail beyond echoing the default output format. Baseline 3 applies 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 names a specific verb and resource ('Returns historical OHLCV data') and adds scope details (auto-aggregation, stats), which clearly separates it from get_stock_price and get_stock_summary. It stops short of naming or contrasting any sibling explicitly, so it is clear but not fully differentiated.

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?

'Use for price trends and technical analysis' gives an implied usage context, and the format hint steers output selection, but there is no when-not-to-use guidance and no reference to sibling tools like get_stock_price for spot quotes. The agent must infer the boundary itself.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the returned fields and that output defaults to text unless format=json is set, but says nothing about data freshness (realtime vs delayed), auth requirements, or behavior for unknown symbols.

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 short, front-loaded sentences with the return payload first and routing second; no filler. The final sentence largely duplicates what the schema enum already declares, costing it a point.

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 naming the four returned values, and it covers the format choice and the sibling alternative. It stops short of mentioning data latency or failure modes, which would be the remaining gap for a market-data 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 description coverage is 100%, so both parameters are already documented (including 'default: text' on the format enum and the space-separated symbol syntax). The description's 'Text default; set format=json' restates the schema rather than adding new semantics, so 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?

States a specific verb and resource ('Returns current price, change, market cap, and volume') and enumerates the exact data fields returned, so the agent knows the payload shape without a schema. It also explicitly distinguishes itself from get_stock_summary, a sibling it could easily be confused with.

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?

'Use for quick price checks; use get_stock_summary for valuation metrics' gives an explicit when-to-use and a named alternative with the condition that selects it. Only one of the many siblings (profile, history, key stats, etc.) is routed, so the guidance is clear but not exhaustive.

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

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

No annotations exist, so the description carries the full behavioral burden. It discloses output-format switching (text default vs. json) and the optional officers expansion, but says nothing about authentication, rate limits, multi-symbol batching behavior, or error handling on invalid symbols.

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 short sentences, each earning its place: purpose and returned fields first, then usage context, then the two optional-parameter behaviors. 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?

With no annotations and no output schema, the description does cover content fields and both optional parameters, which is enough for an agent to call it correctly. Minor gaps remain around what happens with multiple symbols and error cases, keeping it from a 5.

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

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

Schema description coverage is 100%, so the schema already documents format, symbols, and include_officers including their defaults. The description largely restates that (format=json, include_officers=true, space-separated symbols) rather than adding new semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('Returns company profile') and enumerates the returned fields (sector, industry, summary, governance), which differentiates it from data-oriented siblings like get_financials or get_stock_price. It does not explicitly contrast with the closest sibling, get_stock_summary, 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?

'Use for company overview' gives an implied context for selection, and it flags the include_officers option for a specific need. However, with 19 siblings there is no when-not guidance and no named alternative (e.g., vs. get_stock_summary), so selection still requires inference.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the default output mode (text) and that json is opt-in, but says nothing about multi-symbol batching behavior, error handling for unknown symbols, rate limits, or auth requirements. It is adequate for a simple read tool 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?

Three short sentences, zero filler, and the return contents are front-loaded ahead of routing and format notes. Every sentence carries distinct 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 and no annotations, the description compensates by listing the returned metrics and the format toggle, which is largely sufficient for an agent to call it correctly. Minor gaps remain around multi-symbol output shape and failure behavior.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, and the description's 'Text default; set format=json' only restates what the schema's enum and default already convey. Baseline 3 applies since the description adds no syntax or format detail beyond the structured field.

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 valuation and trading metrics') and enumerates the metric families (P/E, yield, ranges, volume, bid/ask), so an agent knows exactly what it produces. It also explicitly names the sibling it is not (get_key_stats), distinguishing 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 an explicit use case ('fundamental screening') and names the alternative tool with the condition that selects it ('use get_key_stats for advanced ratios'). Routing between the two siblings is unambiguous.

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

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

No annotations are provided, so the description carries the behavioral burden alone. It discloses that the tool is a read-only enumeration returning JSON, but says nothing about whether the country list is static or filtered, caching, or the response shape. For a zero-parameter lookup the risk is low, but the disclosure is thin.

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

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

Two short sentences with zero waste, and the core purpose is front-loaded ahead of the usage hint.

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 no-argument reference tool with no output schema, the description covers what it returns and why an agent would call it. The only minor gap is the exact structure of the returned country list, which 'Returns JSON' leaves unspecified.

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 zero parameters and 100% coverage, so there is nothing for the description to compensate for. Baseline of 4 applies for a parameterless 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?

States a specific verb+resource ('Returns list of supported countries') and scopes it to market data and screeners, which distinguishes it from the stock/financial siblings. It does not name a sibling directly, so it falls short of a 5, but the purpose is unambiguous.

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

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

'Use to find valid country codes for other tools' gives explicit when-to-use guidance and ties it to a downstream workflow. There is no when-not guidance or named alternative, but for a reference lookup tool the trigger condition 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?

No annotations are provided, so the description carries the full burden and falls short. It does not mention that this is a read-only, non-destructive listing, nor does it cover rate limits, auth needs, or how trending is computed/ranked. 'Returns JSON' is a content-free statement rather than a behavioral disclosure.

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

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

Three short sentences, purpose front-loaded, no wasted preamble. The trailing 'Returns JSON' is close to filler given no output schema exists to otherwise explain return values, so it is not a fully earned 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 simple 2-param, zero-required read tool this is nearly adequate, but with no output schema the agent gets no sense of the return shape (array of symbols? objects with rank/volume?) beyond 'JSON'. The country parameter's scope is also unstated — whether it means 'trending within that market' is left implicit.

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

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

Schema description coverage is 100% — both count (default 20) and country (full name or ISO code, default united states) are fully documented in the schema, including the enum set. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Returns currently trending/most watched stock symbols'), which is unambiguous and clearly distinct from price/history/financials siblings. It does not, however, explicitly name a sibling it is not, so differentiation is left to inference.

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?

'Use to find popular stocks before deeper analysis' gives a concrete when-to-use context tied to a workflow, which is more than most siblings offer. It stops short of naming alternatives (e.g. list_screeners, search_stocks) or when-not-to-use conditions.

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?

No annotations are provided, so the description carries the full burden. 'Lists' implies a safe read, and the format default is disclosed, but there is no mention of return volume, pagination, or whether results are static — meaningful gaps for a catalog tool with zero annotation coverage.

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

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

Three tight sentences: what it lists, when to call it, and the format switch. Nothing is wasted and the purpose is front-loaded.

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

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

For a simple two-optional-param listing tool with no output schema, the description gives enough to call it correctly: purpose, sequencing with get_screener, and format behavior. Only pagination/result-size expectations are 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 both parameters carry enum values with their own descriptions, so the schema does the heavy lifting. The description only adds the default-format note ('Text default; set format=json'), which is a marginal restatement of the schema's '(default: text)'.

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 ('Lists available stock screeners') plus a scoping qualifier ('organized by category'). An agent can immediately distinguish this discovery tool from the retrieval sibling get_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?

Explicitly instructs to 'Use to discover screener names before calling get_screener', naming the alternative and the sequencing condition. No when-not guidance is given, but the discovery-vs-fetch distinction is unambiguous.

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

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

No annotations are provided, so the description carries the full disclosure burden. It only says 'Returns JSON,' disclosing neither the result shape, pagination, rate limits, nor behavior when no match is found — near-zero behavioral value for a search operation.

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

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

Three short sentences, purpose and workflow context front-loaded, zero filler or repetition beyond what is needed.

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 annotations and no output schema, the description should explain the return shape and no-match behavior, but only offers 'Returns JSON.' Parameter coverage is fine via the schema, so it is adequate but with a clear gap in return semantics.

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

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

Schema description coverage is 100%, so the schema already documents both 'query' and 'limit' including the default of 10. The description merely restates 'company name or symbol' and adds no syntax or matching-behavior detail, so 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?

States a specific verb (searches) and resource (stocks) plus the search keys (company name or symbol). This implicitly separates it from the get_* ticker-based siblings, though it never names one of them 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 situational context: 'Use to find ticker symbols before calling other tools,' which tells the agent this is a lookup step in a workflow. It offers no exclusions or named alternatives (e.g., list_screeners or get_trending for discovery), 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.