OptionsBell Options Flow

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

With no annotations provided, the description carries the burden of disclosing behavioral traits. It implies a read-only, metadata-oriented operation through 'Discover what data is available' and 'Call this first,' which strongly suggests a non-destructive query. It also explains what information is returned, adding behavioral context beyond the bare tool name. It does not explicitly state 'no side effects,' but for a stats/discovery tool this is reasonably transparent.

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: the first front-loads the core purpose and output types, the second gives usage guidance. Every word contributes, with no redundancy or filler. It is concise yet 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?

Given the tool has no parameters, no annotations, and no output schema, the description does well to specify both the output content (date ranges, contract counts, symbol counts, sector coverage) and the dataset scope ('unusual-activity dataset and its daily aggregates'). It also provides usage context. It is slightly incomplete in not specifying whether the stats are global or per-symbol/time-window, but for a discovery tool this is adequate.

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

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

The tool has zero parameters, and the rubric gives a baseline of 4 for 0 params. The description adds no parameter-specific semantics, but none are needed. It does mention the content of the returned data, which is not about parameters. The baseline 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's purpose: 'Discover what data is available before querying' and enumerates specific outputs (date ranges, contract counts, symbol counts, sector coverage). It distinguishes itself from the sibling data-query tools like get_unusual_activity by focusing on dataset metadata rather than actual activity rows.

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

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

The description explicitly instructs 'Call this first when unsure about available history,' which gives a clear when-to-use. It also implies using it before other querying tools ('before querying'). However, it does not explicitly mention alternative tools or give when-not-to-use conditions, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains the output structure (DTE buckets with splits) and adds interpretive value (event vs. positioning), which goes beyond a simple restatement. It does not mention limitations or edge cases, but the core behavior is well conveyed.

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

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

The description is two sentences, front-loaded with the main purpose and followed by a concise interpretive heuristic. 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 specialized analytics tool with no output schema, the description conveys the core concept, bucket definitions, and suggests how to interpret results. It is sufficient for an expert user, though it leaves some ambiguity about the exact output format (e.g., percentage vs. count).

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 (date and symbols) are already documented. The description adds context about the tool's analytical focus but does not provide additional parameter-level meaning beyond what the schema offers. 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's purpose: showing where the day's unusual premium sits along the expiry axis in DTE buckets with call/put splits. It uses a specific verb ("sits") and distinguishes it from sibling tools by focusing on expiry concentration rather than broader flow or IV metrics.

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 interpretative guidance for when to use this tool: heavy short-dated premium reads as event bets, heavy long-dated as positioning. This gives clear context on how to apply the output, though it does not explicitly name alternatives or state when not to use it.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It explains what the series contains, how the data is aggregated, the approximate length (~75 trading days), and the included metrics such as call/put volume, premium, C/P ratio, IV, net delta, and streak. It does not cover output structure or error/edge-case behavior, but it provides substantial behavioral context beyond the title.

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 with a high information-to-word ratio. It front-loads the core purpose, then details the metrics and typical length, and ends with a concrete use example. Every phrase earns its place; the parenthetical about the unusual filter is particularly valuable for disambiguation.

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

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

Given there is no output schema, the description does a good job telling the agent what to expect: a daily series with specific fields and approximate duration. The schema handles parameter constraints. A full 5 would require a bit more clarity on the exact response shape or behavior when date_from/date_to vs the default ~75 trading days interact, but the current definition is sufficient for correct selection and 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 baseline is 3. The description does not add parameter-level meaning beyond the schema, but it reinforces that the data is per-symbol and time-series based, which aligns with the symbol, date_from, date_to, and limit parameters. No parameter details are missing enough to require extra compensation.

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 resource ('one symbol's UNUSUAL options flow') and a precise operation ('End-of-day series'), and clearly distinguishes itself by noting it is aggregated from contracts that passed the unusual filter, not the full tape. This makes it easy to tell apart from siblings like get_symbol_flow and get_unusual_activity.

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

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

The description gives clear use context: it powers back-tests and questions like 'how has unusual flow on NVDA developed?'. It also implies a boundary by saying it is 'not the full tape', which steers an agent away from using it when raw/full tape data is requested. It does not explicitly name alternative tools, so it misses the top-level exclusion guidance.

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

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

With no annotations provided, the description carries the disclosure burden. It explains the scoring basis (call/put volumes, premium, net delta), the strength scale, and the two distinct response modes. It does not discuss pagination or edge cases, but those details are partially covered by schema parameter descriptions and there is no contradiction.

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

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

The description is two dense sentences with no filler. It front-loads the core classification semantics, then explains the mode switch and filters in the second sentence. Every phrase 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 12-parameter tool with high schema coverage and no output schema, the description conveys the essential purpose and the central mode-selection logic that would be hardest to infer. It omits the symbols and signal_only parameters, but the schema descriptions cover those, and the overall calling pattern is clear.

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 high, so the description's main job is to add selection semantics. It adds the crucial conditional: presence or absence of the symbol parameter switches between time-series and snapshot mode, and it groups the filter parameters cohesively. It does not enumerate every parameter, but the schema already documents those.

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 the resource ('unusual flow') and the core output: a bullish/bearish classification with a 0-9 strength score, based on call/put volumes, premium, and net delta. It clearly explains the two modes, single-symbol time series vs cross-market snapshot. However, it does not explicitly contrast itself with sibling tools such as get_symbol_flow or get_sector_flow.

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

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

The description gives explicit conditional instructions: pass a symbol for the ticker's sentiment series, omit it for the snapshot, and filter the snapshot by sector, side, minimum strength, or premium. This is clear usage context, though it does not state when to prefer this tool over nearby siblings like get_symbol_flow or get_sector_flow.

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 provided, the description carries the behavioral disclosure burden. It explains the core output concept and the signal interpretation, but it does not disclose response shape, pagination behavior, or any limitations beyond what the schema states.

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 compact sentences: the first front-loads the core concept and output, the second adds actionable context without fluff. Every clause earns its place.

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

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

With no output schema, no annotations, and 7 parameters, the description leaves important gaps: no return-field details, no mention of defaults, and no explicit sibling differentiation. It covers the concept and use case but is not complete enough for fully autonomous 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 71%, leaving limit and min_volume without descriptions. The description adds no parameter-level meaning beyond mentioning the dominant side, which is already in the schema, so it fails to compensate for the undocumented 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?

The description states a specific resource (symbols with unusual options activity) and a clear differentiator: N+ consecutive trading days with a dominant call/put side. It does not name sibling tools, but the 'single print' contrast helps separate it from single-event flow tools.

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

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

The phrase 'Persistent unusual flow is a stronger signal than a single print' and the use case 'where does money keep showing up?' give clear contextual guidance. However, it does not explicitly name alternative tools or state when not to use this tool.

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

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

With no annotations, the description carries the full disclosure burden. It explains the 20+ day history requirement, the two output modes, and the specific side=both behavior. It does not describe the response shape or behavior for insufficient history, but the core behavioral traits are well disclosed.

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 dense sentences, front-loaded with purpose, then organized by mode with a concrete example. Every clause earns its place; there is no filler or repetition of schema content.

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

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

For a dual-mode tool with no output schema and no annotations, the description provides enough to select the right mode and parameters, and it surfaces the rolling-history prerequisite. Minor gaps remain, such as behavior when symbol is combined with snapshot-only parameters and what the returned records contain, but these do not block correct tool selection.

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

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

Schema coverage is 67%, and the description adds meaningful parameter logic beyond the schema: lookback_days and limit apply to the series mode, while side, min_rank, and max_rank apply to the snapshot. It also clarifies that side=both ranks by the higher of call/put IV rank, which the schema does not convey.

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 precise computation ('IV rank and IV percentile per symbol against its rolling history') and immediately separates the two modes: per-symbol time series versus ranked snapshot. This clearly distinguishes the tool from the sibling flow/OI tools and leaves no doubt about what it does.

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 an explicit mode-selection rule: pass a symbol for a time series, omit it for a ranked snapshot. The example 'side=put&min_rank=0.8 finds elevated put IV' provides concrete usage context. It does not name alternatives or state when not to use the tool, but no sibling tool overlaps with IV rank, so the guidance 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. It does disclose the main behavior: aggregating market-wide unusual flow and returning a breadth score, ratio, regime label, and signal counts. However, it omits response shape, date-range handling, and any edge-case behavior, making the transparency only partial.

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, compact sentence that front-loads the output summary and ends with a practical use-case. It contains no filler, though the enumeration of fields is slightly dense.

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

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

Without an output schema, the description should clarify the return structure, but it only lists content fields without stating whether the result is a single object or an array of daily rows. The core use case is well covered, but an agent still lacks exact response shape and field-name expectations.

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 each parameter clearly documented and validated (date, limit, date_from, date_to). The description adds no parameter-specific detail, but the schema fully covers meaning, defaults, and constraints, 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?

The description clearly identifies a specific computation (market-wide breadth of unusual flow per trading day) and lists concrete return fields (score, call/put ratio, regime label, signal counts). It implies differentiation from per-symbol/sector siblings via 'market-wide' and 'overall tone', but does not explicitly name an alternative.

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

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

The description gives a direct usage context: answering 'what's the overall tone of the unusual-flow tape?'. This tells an agent when to select this tool, but it does not state when not to use it or mention alternative tools by name.

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 behavioral disclosure burden. It does convey the day-over-day computation, per-symbol vs market-wide behavior, and the interpretive meaning of 'fresh positioning being built or unwound.' However, it does not describe return shape, sorting semantics, or pagination beyond what the schema mentions, so some behavioral context is left implicit.

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 compact sentences with no filler. The core concept is front-loaded, and the mode-switching instruction is placed immediately afterward, making it quick to parse.

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

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

For a 10-parameter tool with no annotations and no output schema, the description plus rich schema coverage is largely sufficient. It explains the two main usage modes and the supported fields, while the schema fills in defaults, bounds, and market-wide-only constraints. A return-format hint would improve completeness slightly, but the current combination is adequate.

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 90%, so the schema already documents nearly all parameters. The description adds useful framing about which parameters apply in which mode ('date_from, date_to, limit apply' for symbol mode; omit symbol for market-wide), but it does not add substantial semantics beyond the schema for most 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?

The description names a specific resource ('Day-over-day open-interest change per symbol') with explicit components (total, calls, puts) and a clear verb. It also distinguishes the two operating modes by symbol vs market-wide, making it easy to tell apart from sibling flow and IV tools.

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

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

The description gives direct invocation guidance: pass a symbol for an OI-change series, omit it for market-wide gainers/losers. It does not explicitly name alternative sibling tools or state when not to use this tool, but the mode-based usage is clear enough for an agent to choose correctly.

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 behavioral disclosure burden and does so reasonably: it specifies the metrics returned, the sector-label universe (11 GICS sectors plus Diversified, Unknown, and Unclassified), and the 'only labels with activity, at most 14 rows' constraint. It does not mention ordering, response container format, or units, but these are secondary for a read-only rollup.

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 front-loaded sentence that leads with the core question and packs necessary details into a parenthetical without filler. It repeats nothing from the schema and every phrase adds useful 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?

Given no output schema and no annotations, the description compensates well by listing the returned metrics and row-count constraints, while the schema covers the two optional parameters. It stops short of specifying the exact response object shape and sort order, but an agent can invoke the tool correctly from this definition.

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 parameters (date and limit) documented including defaults and bounds. The tool description adds no parameter-level meaning beyond what the schema already provides, 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 clearly identifies the tool as a sector-level rollup of the day's unusual options premium and enumerates the returned metrics: total premium, volume, average net delta, and bullish/bearish counts. The sector-label scope distinguishes it from siblings like get_symbol_flow, though it lacks an explicit verb such as 'returns' or 'lists'.

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 conveys the usage context—sector concentration of daily unusual options premium—but does not explicitly say when to choose this tool over get_symbol_flow, get_expiry_concentration, or other siblings. No alternatives or exclusions are mentioned, so guidance is only implied by the sector-grouping language.

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 behavioral disclosure burden. It does disclose ranking behavior and the score basis ('Vol/OI weighted by premium'), but it does not mention defaults, response shape, or side-effect-related details. It is honest 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?

Two sentences with no filler. The core output and ranking behavior are front-loaded, and the usage context is stated immediately after. Every sentence earns its place.

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

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

This is an 8-parameter tool with no output schema and no annotations, yet the description only addresses scope and ranking. It omits guidance about optional filters, date range behavior, limit semantics, and how it relates to siblings like get_unusual_activity or get_top_prints, leaving the agent under-equipped 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 only 50%, and four parameters (type, limit, min_voloi, min_premium) have no schema descriptions. The tool description adds only a vague tie-in to 'premium' and does not explain these optional filters, ranges, or limits, so it does not compensate for the coverage gap.

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

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

The description clearly states what the tool returns: 'Every unusual contract on a single ticker, ranked by score.' It also indicates the scope with 'one specific stock,' which separates it from broader siblings like get_unusual_activity, but it does not explicitly name or contrast any sibling tool.

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

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

It gives explicit context: 'Use when the question is about one specific stock's unusual options flow.' This is clear and actionable, but it lacks explicit when-not-to-use guidance or named alternatives, so it falls short of a 5.

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

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

With no annotations, the description carries the behavioral burden. It does disclose that results are ranked by estimated premium and that this matches the view used in alert emails. However, it does not state read-only behavior, data freshness, or whether results are sorted descending, leaving some behavioral details to inference.

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: the first defines what the tool returns and how it ranks, the second gives a representative user question. No filler or repetition, and the core scoping 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?

The combination of a focused description and a well-described schema is mostly sufficient for a read-only listing tool. The main gaps are the lack of explicit descending-sort confirmation and an output schema or return-structure note, but these are minor for this tool type.

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

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

Schema description coverage is 83%, so the baseline is 3. The description adds no parameter-specific meaning beyond the general 'estimated premium' ranking concept; it does not clarify the undocumented 'type' parameter or enrich any of the schema-described 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?

The description clearly identifies the tool as returning the day's biggest options bets ranked by estimated premium, with an explicit user query example. It is specific about the resource and ranking metric, and the phrase 'largest options trades today' distinguishes it from flow-history or sentiment siblings, though it does not name a sibling 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?

It provides a concrete use case: 'Perfect for what were the largest options trades today?' This tells the agent the intended query context. It does not mention alternatives, exclusions, or when not to use this tool, but the context is clear enough for selection among siblings.

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

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

With no annotations provided, the description carries the full burden. It discloses several behaviors: the always-on base floor (Vol/OI>=1.5, OI>=100, premium>=$25k), the 'raw' parameter to skip it, the response fields (including filtered_total and has_more for paging), and the meaning of 'since' for intraday polling. This goes beyond a generic read tool, though it does not mention error handling or side effects (unlikely for a scan).

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

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

The description is well-structured and front-loaded with purpose, then filters, output fields, and an example. It is slightly long but every sentence provides value; no filler or redundancy. It could be tightened but is appropriately detailed for a tool with 15 parameters.

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

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

Given the lack of an output schema, the description compensates by listing output row fields and pagination details (offset, has_more). It covers defaults (date, type, limit) and the base-floor behavior. It does not explicitly mention edge cases like no results or symbol requirements, but it is sufficiently complete for an agent to use the tool correctly in most scenarios.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema by grouping filters (Vol/OI, premium, IV, DTE, volume, OI) and explaining the output rows (strike, expiry, IV, delta, sector, premium). It also clarifies the 'raw' parameter's role, which is not obvious from the schema alone.

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 is a contract-level unusual options activity scan across 7,000+ US stocks, listing specific filters and output fields. It also provides an example question ('what unusual put buying hit TSLA today?'), making its purpose unmistakable and distinguishing it from sibling tools like get_flow_history or get_top_prints by its focus on unusual activity thresholds.

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

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

The description gives a clear usage context with an example question and explains the available filters, implying when to use it. However, it does not explicitly mention when not to use it or name alternative sibling tools, so it falls short of full routing 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?

With no annotations provided, the description carries the burden of disclosing behavioral traits. It adds the key detail that no API key is required, which is a behavioral trait. It does not describe the return value or error behavior, but for a simple liveness check, this is sufficient for an agent to understand what to expect.

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, front-loaded sentence: 'Liveness check for the OptionsBell MCP server. No API key required.' Every word earns its place, with no redundancy or filler. It is appropriately brief for a tool of this simplicity.

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 health-check tool with no parameters, no output schema, and no annotations, the description is fully complete. It states the purpose and the absence of authentication requirements, which is all the context an agent needs to select and invoke this tool correctly.

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

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

The input schema has zero parameters (empty properties object), and the description adds no parameter information. Per rubric, a zero-parameter tool receives a baseline of 4, and the description need not compensate since there are no parameters to explain.

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 'Liveness check for the OptionsBell MCP server', specifying both the verb (check) and the resource (server). This distinctly sets it apart from the sibling tools, which are all data retrieval operations (e.g., get_flow_history, get_iv_rank), making the tool's 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 phrase 'No API key required' provides useful context for when to use the tool, implying it can be called without authentication setup. However, it does not explicitly mention when to use it versus alternatives or provide exclusions, though the liveness-check nature clearly suggests using it for connectivity verification before data calls.

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