OptionWhales

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, and the description clears it by disclosing tiered access behavior: 3 trades without an account, 5 with a free key, full feed for Pro, plus the fields each tier returns. It does not cover rate limits or refresh cadence, but the tier disclosure is genuinely useful context beyond the annotations.

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

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

Two dense sentences: the first defines the signal and payload, the second gives example queries and tier limits. Every clause earns its place and the access tiers are grouped compactly at the end.

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

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

For a single-optional-parameter, no-output-schema tool, the description supplies the qualifier definition, example intents, returned fields, and tier-dependent result sizes, which is nearly everything an agent needs. It stops short of describing response shape or sort order, which matters given there is no output schema.

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

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

Schema coverage is 100% for the single 'limit' parameter, so the schema already documents default and bounds. The description never references limit directly, but the tier caps (3/5/full) and the field list tacitly frame what comes back; this adds contextual value without adding parameter-level syntax, so baseline 3 is right.

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 resource (unusual options activity this session) and defines the qualifying signal precisely: large, sweep-like, or volume-versus-open-interest outlier orders. The subject matter is clearly distinct from siblings like darkpool_ranking or insider_trades, though no sibling is named explicitly, which keeps it just 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 concrete example phrasings ('any unusual options activity in NVDA?', 'biggest options trades today') that map a user intent directly onto this tool. No explicit when-not-to-use guidance or named alternatives, so it stops at clear context rather than full routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description still adds two things beyond them: the output is grouped by expiry, and access is gated ('Pro'). The band semantics (fraction of spot) are also surfaced, though return payload details and rate limits remain unstated.

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, zero filler, with the scope constraint front-loaded ahead of the usage sentence. 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, the description should ideally say more about the return shape; it gives the 'grouped by expiry' hint but not the fields. However, annotations fully carry the safety profile and the schema fully documents inputs, so the definition is adequate 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 all three parameters are already documented, including the default width of 0.05 and the date format. The description only restates the default band as 'plus or minus 5%', adding a little interpretive value but nothing the schema lacks. 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+resource: returns near-the-money option strikes grouped by expiry, scoped to a band around spot. It distinguishes itself from a general chain by the ATM/band framing, but never names the closely related siblings contract_chain or contract_historic, so an agent must infer the boundary.

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

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

'Use to find the liquid at-the-money contracts for a ticker' gives usage context, but there is no explicit when-to-use-vs-alternative guidance despite contract_chain and contract_historic sitting right beside it. The reader can infer the niche but gets no routing rule.

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

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

Annotations already cover the read-only, idempotent, non-destructive profile, so the bar is lower. The description still adds real context: it is a latest-snapshot view (not a time series, unlike contract_historic), rows are constrained to OI > 0, and the 'Pro' marker signals a subscription/tier requirement.

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 what the tool returns, the second lists filters. Dense and efficient, though the field enumeration is slightly list-heavy.

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

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

For a read-only listing tool with no output schema, the description covers the returned fields, the snapshot semantics and the available filters. Remaining gaps (default limit, 'Pro' meaning, response shape) are minor but not fully closed.

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 schema itself documents ticker, date and limit formats. The description names the filterable fields (expiry, call/put, min OI) and confirms the OI>0 constraint, adding marginal value but no format or syntax detail 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 (option chain for a ticker) plus the exact returned fields, which lets an agent distinguish it from contract_atm and contract_historic. It does not explicitly name or contrast those siblings, 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?

The description says what can be filtered (expiry, call/put, minimum OI) but gives no when-to-use guidance or comparison to alternatives such as contract_atm or contract_historic. Usage is implied by the filters 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is known. The description adds the look-back limit ('about a year') which is useful behavioral context, but does not disclose rate limits, authentication requirements beyond 'Pro', or return format specifics.

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?

Single sentence, front-loaded with the core purpose, no waste. The trailing 'Pro' is terse but possibly unclear whether it's a tagline or a requirement.

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 explain the return format (e.g., array of OHLC bars with date keys). It doesn't. However, annotations cover safety and the look-back limit is given. For a read-only data retrieval tool, it's minimally adequate but leaves return shape 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?

Schema coverage is 100%, with each parameter documented (occ example, from/to format). The description adds only minimal context: 'one option contract' and 'between two dates'. Baseline 3 is appropriate when schema is complete.

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: 'Daily OHLC price bars for one option contract by OCC symbol'. Clearly distinguishable from siblings like stock_candles (single stock) and contract_chain (list of contracts).

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

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

Implies usage context ('one option contract', OCC symbol required) but provides no explicit when-to-use vs alternatives, no mention of prerequisites like a Pro subscription requirement beyond the word 'Pro'. No exclusions stated.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotent, openWorld). The description adds the default-latest behavior, which is useful, but says nothing about return shape, pagination, or what 'Pro.' entails. With annotations carrying the burden, a 3 is appropriate.

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

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

Front-loads the resource and scope well, but the malformed fragment 'Pro.' at the end is unclear and wastes a closing beat. Otherwise efficient, though the example query adds little.

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

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

For a single-parameter, annotation-covered read tool this is close to adequate, but the undefined 'Pro.' token and absence of any note on the two output sections leave small gaps. Enough to call correctly, not rich.

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 date parameter is fully documented with format and default. The description repeats the default-latest behavior but adds no syntax or edge-case detail beyond the schema, so baseline 3 is correct.

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: off-exchange (dark pool) activity with two distinct outputs — a market-wide share and a per-ticker notional ranking. An agent can distinguish it from siblings like market_tide or abnormal_trades_current 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?

Provides an explicit usage quote ('where is dark pool activity concentrated?'), which gives clear context for when to reach for this tool. It does not name an alternative or state exclusions, so it falls short of a 5.

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

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

Annotations already declare it read-only, idempotent, non-destructive and open-world, so the safety profile is covered. The description confirms the score's composition and range, which is useful context, but says nothing about data freshness, result ordering, or what the score means at its extremes.

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 that front-load the tool's purpose and range, then the use case. The dangling 'Pro.' is the only wasted token.

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

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

For a single-optional-param read tool with no output schema, most of what an agent needs is present, but absence of return-shape detail and the opaque 'Pro.' qualifier (a gating requirement?) leaves a small gap.

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

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

Schema coverage is 100%, and the single max_display param is fully documented in the schema. The description adds no extra parameter guidance, 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?

Clear verb+resource: a per-ticker directional score for the current session, with an explicit -1 to +1 scale and the inputs it combines. It's distinguishable from siblings like market_tide or sector_tide, though the terse 'Pro.' tag adds no clarity.

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

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

Explicitly states when to use it ('rank names by bullish or bearish options positioning'), giving a concrete use case. It doesn't name a competing alternative (e.g. intent_flow_current or abnormal_trades_current), so it stops 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?

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior. The description adds only that results cover amount, frequency, and ex/pay dates, plus a cryptic 'Pro.' tier flag; it says nothing about pagination, latency, or data currency beyond the annotations.

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

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

Two short, front-loaded sentences with no filler; the resource and payload contents come first. The dangling 'Pro.' fragment is slightly opaque but does not bloat the definition.

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

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

With no output schema, the description carries the burden of explaining returns, and it names the fields but not their formats (date format, per-share amounts, adjusted vs unadjusted, frequency values). Adequate but leaves real gaps for an agent interpreting results.

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 (ticker, limit) are fully documented in the schema, so the baseline is 3. The description's field list describes return content, not parameter semantics, and adds nothing about ticker format or limit behavior.

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 ('Cash dividend history for a stock') and enumerates the returned fields, so the agent knows this is a historical dividend data lookup. It does not name or distinguish itself from any sibling, though none of the listed siblings clearly duplicates it.

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?

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives. The trailing 'Pro.' is the only contextual hint, implying an entitlement requirement rather than usage direction, and it is not explained.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false. The description adds genuinely new behavioral context beyond those: the account-tier gating (no account = date/time for one ticker or next 3 reporters; free = up to 10 with estimates; Pro = full calendar plus options-flow intent label).

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

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

Three dense sentences, front-loaded with the resource and returned fields, then usage, then tier limits. No filler, though the tier sentence is packed tightly and could be slightly clearer.

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

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

For a read-only calendar tool with no output schema, the description covers returned fields, usage variants, window/default semantics, and access-tier limits. It leaves only the earnings_current-vs-earnings_calendar distinction and return format specifics 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%, so all three parameters (days, limit, ticker) are already documented in the schema. The description restates the days window and default (7) and the ticker-as-optional idea, adding only marginal meaning 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?

States a specific verb+resource: 'Upcoming earnings reports' with the returned fields (date, before/after market, EPS and revenue estimates). The word 'Upcoming' implies a time direction, but the description never explicitly distinguishes it from the sibling earnings_current (likely historical), 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?

Gives concrete when-to-use guidance via two example intents: 'Pass a ticker for when does NVDA report?' vs 'omit it for who reports this week?', and notes that days sets the window. It stops short of naming an alternative sibling tool or when-not-to-use conditions, so it 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds that data is scoped to 'companies reporting this session,' useful for understanding freshness. But it doesn't explain coverage gaps (only companies on today's earnings calendar?) or latency/refresh characteristics for a live-flow 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?

Front-loaded with the topic, but the trailing 'Pro.' is unnecessary and the sentence packs several concepts (pre-earnings flow, Greeks, intent signals) without subordinating them. Slightly loose for a zero-parameter tool.

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

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

For a zero-param tool with full annotation coverage and no output schema, the description covers what it does but omits how the output is structured or scoped (all reporting companies? how filtered?). No mention of sibling distinctions, which matters given many nearby options-flow tools.

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?

No parameters, so baseline is 4. The description does not need to document params since there are none, but it also doesn't tell the agent how tickers/companies are selected (no input means output must be global or auto-scoped to session), which is a subtle semantic gap.

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

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

States a specific verb scope (options positioning around earnings) and resources (order flow, Greeks, intent signals). It partially differentiates from siblings like greek_exposure or intent_flow_current by tying to earnings, but doesn't explicitly name alternatives. The trailing 'Pro.' is marketing noise that doesn't add clarity.

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

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

Gives a concrete user example ('how are traders positioned into NVDA earnings?') that anchors the use case, and states 'companies reporting this session,' which implies recency constraints. However, it never compares to sibling tools like greek_exposure or intent_flow_current that overlap in scope, so an agent can't easily route.

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

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

Annotations already establish read-only, idempotent, non-destructive, open-world behavior. The description adds genuinely new behavioral context: the paid-tier gating (unauthenticated users see only the next 3 high-impact events, free/Pro see the full calendar), which an agent needs to interpret truncated results correctly.

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: capability, usage trigger, access-tier constraint. Front-loaded with what matters most and no filler or restated title.

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 one-optional-param read tool with no output schema, the description covers content returned, trigger conditions, and access limits. It does not say whether the calendar includes past/upcoming windowing or result size beyond the tier cap, which is a minor but real gap.

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

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

Schema description coverage is 100% and the single optional 'impact' filter is fully documented there, so the baseline is 3. The description echoes 'impact level' and mentions 'high-impact,' but adds no format or semantics beyond the schema's high/medium/low enumeration.

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 resource (US macro events: CPI, FOMC, jobs, GDP) plus what each entry carries (impact level, historically reacting ETFs). That is clearly distinguishable from siblings like earnings_calendar, dividends, or stock_news without opening a schema.

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

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

Gives an explicit invocation trigger ('what macro events are coming up?'), which is exactly the routing cue an agent needs. It does not name alternatives (e.g., earnings_calendar for company-specific events) or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds 'latest first' ordering and the 'Pro' access note, but says nothing about rate limits, auth requirements, or how many periods are returned by default.

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?

A single well-formed sentence that front-loads the resource and its content types before the modifiers. The trailing 'Pro.' is a slightly cryptic fragment, but overall there is little 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?

With no output schema and only 67% schema coverage, the description should carry more weight. It covers what the tool returns and the ordering, but omits defaults (4 periods), the max limit of 40, and any pagination or tier details.

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%: ticker and limit are documented in the schema, but timeframe has no description. The description partly compensates by spelling out 'trailing-twelve-month, quarterly or annual', which maps to the enum values, though it does not document the default period count or the limit cap.

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 resource (company financial statements) and enumerates the three statement types, plus the period granularity and ordering. It is clear what the tool returns, but it never contrasts itself with siblings like earnings_current or dividends, so it earns a 4 rather than 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?

There is no explicit when-to-use or when-not guidance and no named alternative. The trailing 'Pro.' hints at a subscription prerequisite but leaves the agent to infer access conditions and whether another sibling is more appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds real behavioral value: the session default and the tier/entitlement gate (free: SPY/QQQ; Pro: any ticker), which is not in annotations or schema. It does not describe pagination or refresh cadence, so a solid 3.

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

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

Four compact sentences, front-loaded with what the tool returns, then when to use it, then defaults and access tiers. Every sentence earns its place with no filler.

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

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

For a read-only, three-parameter tool with no output schema, the description covers purpose, triggering contexts, session default and entitlement limits. The main gap is that it doesn't explain how the returned level values should be interpreted or their format, though annotations already relieve the safety burden.

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 parameters are documented by the schema itself. The description restates the session default but adds no syntax or meaning for dte_filter beyond what the schema provides, which is the correct baseline 3.

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 resource (dealer gamma-exposure key levels) and enumerates the outputs: gamma flip, max pain, call wall, put wall, spot. No sibling covers GEX levels, and the agent can tell exactly what comes back.

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 triggering contexts ('where price may pin, bounce, stall or accelerate') with a concrete example query. It lacks explicit when-not-to-use guidance (e.g., intraday vs. post-close, or how it differs from greek_exposure/volatility_term_structure), so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low. The description adds real value beyond them: the 'Pro' tag signals an access/subscription prerequisite, and it clarifies that session defaults to the latest trading day.

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-load the resource and granularity, followed by a short usage cue and default/access notes. Every sentence earns its place with no filler.

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

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

With no output schema, the description helpfully previews the return shape (by strike/expiry, calls/puts/net) and covers the session default. It falls short only on dte_filter, whose filtering behavior is left unexplained.

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%: ticker and session are documented, but dte_filter carries only an enum with no prose. The description restates the session default but never explains dte_filter's semantics, so it does little to compensate for the gap. 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 resource (dealer gamma, charm, vanna exposure) with explicit breakdowns by strike, expiry, and calls/puts/net. It explicitly distinguishes itself from the sibling gex_levels by positioning as the more detailed 'beyond the key GEX levels' view.

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: 'Use for detailed hedging-flow analysis beyond the key GEX levels,' which implicitly routes the agent away from gex_levels for high-granularity needs. It lacks an explicit when-not rule (e.g. prefer gex_levels for headline levels), so it stops short of 5.

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

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

Annotations already declare readOnly, idempotent, open-world, and non-destructive, so the safety profile is covered. The description adds real context beyond that: 'latest first' ordering, the specific fields returned, the SEC Form 4 source, and the 'Pro.' tier indicator implying an entitlement requirement.

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

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

Front-loaded with the core subject and field list, then the usage example, all in two efficient sentences with no filler. The trailing 'Pro.' is terse and slightly cryptic but conveys tier info cheaply.

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

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

With no output schema, the description carries the burden of explaining returns and does so by listing the fields and ordering ('latest first'). Combined with a fully documented input schema, an agent has almost everything needed, though pagination behavior for the limit is not addressed.

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

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

Schema coverage is 100% and both parameters (ticker, limit with default 25) are documented in the schema. The description adds no syntax or format detail beyond 'for a stock,' so the baseline of 3 is appropriate.

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

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

States a specific verb+resource: 'SEC Form 4 insider transactions for a stock,' and enumerates the returned fields (insider, transaction code, shares, price, value, filing link). This clearly separates it from siblings like abnormal_trades_current or darkpool_ranking without opening any schema.

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

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

Provides an explicit use-case example ('are insiders buying AAPL?') that maps an intent to this tool. It gives clear context but names no alternatives or when-not-to-use conditions, and 'Pro.' is left unexplained as a constraint.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior. The description adds valuable tier-based access limits: unauthenticated returns top 3 tickers with minimal fields, free returns top 3 with core fields, Pro returns every tracked ticker with all fields. It doesn't mention rate limits or data freshness beyond 'Today's', so a 4 is appropriate.

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

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

Three sentences, front-loaded with the core definition, then use cases, then tier limits. Every clause adds information with no redundant phrasing.

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

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

For a zero-parameter, no-output-schema tool whose annotations cover safety, the description covers purpose, usage, and access tiers. It partially describes return fields but leaves 'core fields' and 'all fields' vague, a minor gap that keeps 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?

The tool has zero parameters, so the schema has no properties to document; the rule sets a baseline of 4 for this case. The description adds no parameter information because there are none 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?

States a specific verb (rankings of options-flow intent) and resource (tickers showing bullish vs bearish institutional positioning). Expands beyond the title by naming accumulation, distribution, hedging, direction bias, and strength. Does not explicitly distinguish itself from siblings like darkpool_ranking or directional_current, so not 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?

Provides clear example queries ('what are big options traders doing today?', 'where is smart money flowing?') that signal intended use. No when-not-to-use guidance or named alternatives, so not a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely useful non-annotation context: the shape of the returned data and the 'Pro' tier hint. It stops short of stating auth/key requirements or session-boundary caveats, which keeps it below a 5.

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

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

Three tight sentences: payload definition first, then the use-case question, then the tier flag. Every clause earns its place and nothing is repeated from the schema.

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

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

With no output schema, the description correctly names the three returned components, and the annotations cover safety. It is complete enough to call correctly, though it omits the Pro/auth prerequisite detail and any note on what 'latest' resolves to.

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% with both parameters fully described (top_n default 25, session date or 'latest'). The description only loosely ties to these via 'top net-premium tickers' and 'for a session', adding no format or constraint detail 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 subject and payload: signed large-order net-premium into calls vs puts, the intraday cumulative curve, and top tickers per session. The 'market-wide' scope cleanly distinguishes it from the sector-level sibling sector_tide, so an agent can route 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 trigger question ('is options flow bullish or bearish overall today?') and flags 'Pro', implying tier gating. It stops short of naming the alternative (sector_tide) for narrowing to a sector or an exclusion case, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable tier-gating behavior: free accounts get top 3, Pro gets up to 200 with all fields. This tells the agent the effective ceiling varies by account, which annotations do not convey.

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

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

Three compact sentences, front-loaded with the ranking definition, then the use case, then the tier constraint. Every sentence adds distinct information with no 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 one-parameter, read-only ranking tool with annotations covering safety, this is nearly complete. The description could state the default output count (50) or whether results are limited in fields for free accounts, but the essential behavioral facts (ordering, use case, tier limits) are present.

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

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

Schema description coverage is 100%, and the sole parameter (top) is fully documented in the schema with its default of 50 and max of 200. The description's mention of 'top 3' free vs 'up to 200' Pro adds account-tier context but is not per-parameter semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific ranking output ('Tickers ranked by options-flow momentum') and adds the defining dimension ('fastest-changing positioning this session'), which distinguishes it from siblings like directional_current or gex_levels. An agent can identify the resource and its ordering criterion immediately.

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 explicit example query ('which stocks have the strongest options momentum right now?') that maps natural-language intent to this tool. No exclusions or sibling alternatives are named, but the usage context is clear enough to route correctly among similar flow tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description's one genuinely additive behavioral signal is 'Pro.', which hints at a subscription/tier gate, but it does not state what gets returned or any limits beyond the schema's max.

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, ranking concept front-loaded, no filler. The dangling 'Pro.' fragment is slightly abrupt but costs almost nothing in length.

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

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

For a read-only ranking tool with no output schema and complete annotations, the description covers purpose and a use case, but leaves the dte semantics and expected return shape unexplained, so it is only minimally 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 coverage is only 50%, and the uncovered parameter is the dte enum ('all', 'lt8', 'gte8') whose meaning is opaque. The description does not compensate by explaining what these buckets mean or how dte and limit interact with the ranking.

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: tickers ranked by day-over-day change in total options open interest, with sub-modes (gainers, losers, most active). This distinguishes it from oi_timeseries (a time series) well enough, though it never names the 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?

The description gives a use case ('where is new options positioning building?'), which implies when to reach for this tool, but offers no when-not guidance and names no alternative among the many sibling ranking tools (e.g., volatility_movers).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds real context beyond them: it is snapshot-based rather than live, and the trailing "Pro" signals a paid entitlement requirement. Neither points appear in the structured annotations.

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

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

Three short sentences, front-loaded with the resource and scope, with the analytical purpose second. No filler, though the terse "Pro." fragment is a little clipped relative to the rest.

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 explaining the entitlement model, the description should be doing more: it leaves the dte and slot parameters unexplained and doesn't describe the snapshot cadence or return shape. It is adequate for a basic read tool but has clear gaps around the two enum parameters.

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

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

Schema coverage is only 33% (just the ticker description). The dte enum (all/lt8/gte8) and slot enum (AM/PM) have no descriptions, and their meanings are far from self-evident; the description says nothing about either. The "calls, puts, total" phrasing describes output dimensions, not any parameter, so it does not compensate.

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: open interest and volume history for one ticker, with the broken-out dimensions (calls, puts, total). Clear on its own, but it never differentiates from the sibling oi_movers, which also concerns open interest, so an agent must guess which one fits.

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 see whether options positioning is building or unwinding" gives an implied analytical use case, but there is no explicit when-not guidance and no alternative sibling (e.g. oi_movers) named. The agent can infer intent but must decide on its own when this tool is the right one.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and side-effect profile is covered. The description adds signal scope and filtering behavior but says nothing about output shape, pagination, or result caps beyond the limit param. The trailing 'Pro.' hints at a subscription/auth tier but is too cryptic to count as disclosure, so a 3 is appropriate against the 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 sentences, front-loaded with the capability and then the filter set and an example. The dangling 'Pro.' is cryptic and slightly muddies the close, but overall the structure is tight with little waste.

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

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

For an 11-parameter tool with no output schema, the description covers the screening dimensions and a representative query well. It omits any description of what a returned row contains, how sessions/signals interact, or pagination behavior, leaving real gaps given the absence of an output schema.

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

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

Schema coverage is 64% with 11 params, so the schema does much of the work. The description touches most filter dimensions (direction, premium, OI change, catalyst window, phase, congress, sort, limit) but adds no syntax, units, or format detail beyond the schema, and leaves session, signals and order unaddressed. Baseline 3 fits.

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 ('Screen the market') and enumerates the four signal families (options-flow net premium, OI change, FDA catalysts, congressional trading), which meaningfully distinguishes it from single-signal siblings like oi_movers or intent_flow_current. It stops short of explicitly contrasting itself with those siblings, 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?

It supplies a concrete usage scenario ('find bullish options-flow names with an FDA catalyst in the next 30 days') that tells the agent the kind of multi-signal query this tool is built for. There is no explicit when-not guidance or named alternative, so it lands at clear-context-without-exclusions.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The only behavioral disclosure is the look-back constraint. The unexplained 'Pro' marker and no note on data source, latency, or entitlement limits fall short of adding real context beyond the annotations.

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

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

One dense sentence front-loads the resource but compresses five outputs plus a range into a single clause, and the trailing 'Pro' is an unearned token that adds no 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 read-only analytics tool with no output schema, the description should at least hint at return structure or data granularity; it instead leaves 'Pro' undefined and omits any output-shape guidance, leaving the agent to guess what the payload looks like.

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% with clear descriptions for both parameters, so the schema carries the burden; the description only restates the years range and adds no format or default nuance beyond it. 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+resource: monthly seasonality for a stock, enumerating the exact outputs (average/median return, hit rate, best/worst years). Sibling tools cover different data domains, so no explicit differentiation is needed, but the 'Pro' suffix is unexplained.

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 look-back range (1-25 years) is stated, implicitly signaling long-horizon analysis, but there is no when-to-use guidance, no mention of alternatives to prefer for intraday or non-calendar patterns, and no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds the 'Pro' access requirement and clarifies the aggregation metric (net premium), but says nothing about return format or limits. Adequate against the lower bar set by annotations.

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

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

Two short sentences with the core definition front-loaded and no padding. The dangling 'Pro.' is terse but conveys the access tier, so it 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 single-parameter, read-only, open-world tool whose annotations already cover the safety profile, the description conveys what the tool returns (sector-level net premium) and when to reach for it. No output schema exists, but the return concept is stated, leaving only minor detail gaps.

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

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

Schema description coverage is 100% for the single 'session' parameter (YYYY-MM-DD or 'latest'), so the schema already carries full parameter meaning. The description adds no format or default detail beyond it, making the baseline 3 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: options net premium aggregated by sector for a session. The 'Pro' tag signals access tier. It does not, however, distinguish itself from the near-identical sibling market_tide, which is the main clarity gap.

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 "Use for 'which sectors are seeing bullish options flow?'" gives an implied usage context, but it merely restates the purpose as a question. No when-not guidance and no named alternative (e.g., market_tide) are provided, so routing is left to 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds real context: the data source (FINRA), the bi-weekly settlement cadence, the days-to-cover field, and the "Pro" tier requirement, which signals an access/plan prerequisite not encoded anywhere else.

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 with no waste, front-loading the data source and scope before the example use case. 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?

With no output schema, the description does well by naming the returned content (short interest history plus days to cover). It stops short of describing the return shape or pagination for the limit parameter, but for a two-parameter read-only tool with full annotation coverage it is largely 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%, so ticker and limit are fully documented in the schema, giving a baseline of 3. The description adds nothing about parameter format or defaults beyond what the schema already provides.

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

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

States a specific resource (FINRA short interest history) with a clear cadence (bi-weekly settlements) and a distinguishing metric (days to cover). It is distinguishable from the sibling short_volume, but it never names or contrasts that sibling explicitly, so it stops short of full differentiation.

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

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

The example query "how heavily shorted is GME?" implies the use case, which is genuinely helpful for routing. However there is no when-not-to-use guidance and no explicit reference to alternatives like short_volume, so usage is only implied 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the FINRA data source, the per-venue split, and the 'Pro.' tier signal (a subscription requirement not captured by annotations), but it discloses nothing about return shape or the lookback of the default window beyond the schema.

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

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

A single sentence, front-loaded with the resource and data source, with no wasted words. The trailing 'Pro.' is terse but functionally flags a tier gate rather than padding.

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

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

For a two-parameter read tool whose annotations cover safety and whose schema is fully documented, this is close to sufficient; the returned metrics are at least hinted at. It falls short on sibling differentiation from short_interest and on any statement of what the response contains, given no output schema exists.

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 ticker and limit thoroughly documented in the schema, so the baseline is 3. The description adds no parameter-level meaning beyond what the schema already provides.

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

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

States a specific resource (daily FINRA short-sale volume and short-volume ratio) plus the per-venue split and a stock scope, which is concrete and agent-actionable. However, it never distinguishes itself from the sibling short_interest, which an agent could easily confuse with this 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as short_interest. The agent must infer usage entirely from the name and description.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: real-time bars for watchlisted symbols versus 15-minute delay otherwise, plus a 'Pro' tier gate. No rate-limit or error behavior is 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?

A single dense sentence front-loads the resource and scope, then adds latency and tier caveats. Every clause carries information; nothing is padding.

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

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

With no output schema, the description still conveys the return shape ('OHLCV bars', 'most recent limit bars') and the delay behavior. It stops short of explaining the response envelope (e.g. timestamps, ordering, pagination beyond limit), which is the only remaining gap for a 4-param 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% and every parameter's purpose, range, and default is documented in the schema. The description largely restates those facts ('1 to 60 minute bars', 'default today', 'most recent limit bars') rather than adding syntax or format 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 and resource: 'Intraday OHLCV bars for a stock on a session'. An agent immediately understands this returns candle data, not quotes or indicators. It does not explicitly contrast with close siblings like stock_quote or technical_indicator, 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?

Usage is only implied by the description's scope ('intraday', '1 to 60 minute bars', 'Pro' tier). There is no explicit when-to-use, no when-not, and no named alternative, but the intraday framing does help an agent place it relative to quote/indicator tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and freshness profile is covered structurally. The description adds the useful behavioral fact that sentiment labels are pre-computed and include reasoning, but says nothing about recency window, pagination beyond the limit, or result ordering.

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 core sentence is well front-loaded, but the trailing token 'Pro.' is a dangling fragment that carries no actionable meaning and reads like a stray marketing label. Two of the three sentences earn their place; the third does not.

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

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

For a two-parameter read tool with no output schema, the description does convey the return shape (articles each with a sentiment and its reasoning), which is the most important missing piece otherwise. It remains vague on the recency window implied by 'Recent' and on ordering, leaving a gap an agent would care about.

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% (ticker example formats and the limit default/range are both documented in-schema), so the baseline is 3. The description's phrase 'for a ticker' merely echoes the ticker parameter and adds no format or behavior detail 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+resource ('Recent news for a ticker') and adds the distinguishing output trait (per-article sentiment with reasoning). No sibling tool returns news, so an agent can immediately tell this is the only news-retrieval tool in the set.

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

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

Gives a concrete triggering scenario, "Use for 'why is TSLA moving?'", which tells the agent the intended question type. It does not state exclusions or name alternative tools for adjacent needs (e.g., quote/candles for price questions), so it falls short of a full when/when-not rule set.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds the genuinely non-obvious behavioral rule: real-time only for symbols on the key's real-time watchlist, otherwise a price at least 15 minutes old. That data-freshness caveat is exactly the kind of context annotations cannot express. The trailing 'Pro.' fragment hints at a subscription-tier gate but is too terse to be actionable.

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

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

Front-loaded with the resource and its freshness semantics, then the example query, in three short sentences. The dangling 'Pro.' is a wasted fragment that a reader cannot reliably interpret.

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 is the only place an agent could learn what the call returns, and it says only 'latest price' — no indication of fields, error behavior for unknown tickers, or whether the delayed/real-time distinction affects output shape. Adequate to call correctly, but thin for a tool with no output contract.

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% for the single ticker parameter, so the schema already carries the format guidance (NVDA, SPY, BRK.B). The description adds no syntax or edge-case detail beyond it, making the baseline 3 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+resource ('Latest price for a stock or ETF') and the scope is narrow enough to separate it from stock_candles, stock_news, and technical_indicator without opening a schema. It does not explicitly name a sibling tool, 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?

Provides a concrete invocation scenario ('Use for "what is NVDA trading at?"'), which makes the intended use unambiguous. It gives no when-not guidance and does not route to alternatives such as stock_candles for historical data.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorldHint, so the safety profile is covered. The description adds the returned content and a terse 'Pro.' tier signal, but says nothing about pagination behavior or how the limit interacts with the default of 20.

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

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

One tight sentence, front-loaded with the resource and scope. The trailing 'Pro.' is an unexplained fragment that costs some clarity but doesn't bloat the 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?

With no output schema, the description usefully enumerates the return fields (execution date and split ratio), and annotations carry the safety profile. A simple two-parameter read tool needs little more; only the ambiguous 'Pro.' and absent usage routing hold it back.

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%, with both ticker and limit fully documented including the default of 20 and the 1-500 range. The description adds nothing beyond naming 'ticker', 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 resource (stock split history) scoped to a ticker, and even names the returned fields (execution date, split ratio). It's clear enough to distinguish from siblings like dividends or financials, though it never explicitly contrasts with them.

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

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

No indication of when to use this versus related siblings (e.g., dividends, stock_candles) or of any prerequisites. The only hint is the cryptic trailing 'Pro.', which implies a tier requirement but is not explained.

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

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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false). The description adds genuinely useful behavior beyond that: adjusted closes (splits/dividends handled), daily-by-default timespan, and latest-first ordering. Return format/pagination isn't described, but that gap is minor given the 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?

Front-loaded with the core resource and indicator list, then a compact usage sentence. Efficient with no filler, though the trailing 'Pro' tag is marginal.

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 8 parameters, low schema coverage (38%), and no output schema, the description leaves several parameters and the return shape underspecified. Adequate for routing but not complete for confident invocation of the MACD variants.

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

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

Schema coverage is only 38%, so the description should compensate. It does explain the indicator choice and the daily default, but leaves the MACD-specific windows (long_window, short_window, signal_window) and limit/window semantics entirely to the schema. Partial compensation keeps this at 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?

States a specific verb+resource ('technical indicator series for a stock') and enumerates the supported indicators (SMA, EMA, RSI, MACD). This clearly distinguishes it from siblings like stock_candles, momentum_rankings, and volatility_movers.

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 concrete usage contexts ('is AAPL overbought?' via RSI, or trend questions), which tells the agent when to reach for it. It stops short of naming an alternative sibling to prefer instead, so no explicit exclusions are given.

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

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

Annotations already cover read-only, idempotent, open-world, non-destructive behavior. The description adds non-obvious context the annotations don't: tier-gated result counts (free top 3, Pro up to 50) and that results span both expansions and compressions.

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, metric definition front-loaded, with the usage cue and tier limits appended. No filler, though the tier sentence could be seen as secondary detail rather than essential.

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?

Low-complexity, zero-required-parameter list tool with no output schema and annotations covering the safety profile. The description supplies metric scope and tier limits; only richer direction semantics and return ordering are unstated.

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

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

Schema coverage is 50%; 'limit' is fully documented with default and bounds. The description's 'expansions and/or compressions' and 'up to 50' loosely map to the direction enum and limit ceiling but add little beyond the schema's own enum values.

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

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

States a specific metric and comparison basis: 30-day at-the-money implied volatility moved most versus prior close. An agent can distinguish it from oi_movers and volatility_term_structure by the IV-move focus, though no sibling is named explicitly.

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

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

Gives a concrete usage trigger ('which stocks saw the biggest IV spikes today?') and states tier-based result caps. It lacks explicit when-not-to-use or named alternatives (e.g., oi_movers for open-interest movers), leaving some routing to 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely new behavioral context beyond them: the exact return payload (series by expiration, spot, overall ATM IV) and the free/pro ticker access restriction, which is a hard constraint an agent needs when selecting the 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?

Front-loaded with what the tool returns, then use cases, then access tiers; each sentence carries information. The ticker enumeration is long but functionally necessary for the access constraint, so it stays efficient rather than padding.

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

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

With no output schema, the description compensates by naming the returned components (IV by expiration, spot, overall ATM IV), and annotations carry the safety profile. The only gap is that it does not distinguish itself from the contract-level vol siblings, so it is complete but not maximally informative.

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% for the single ticker parameter, so the schema already documents the argument fully. The description adds no syntax or format detail beyond it (the examples are just illustrative tickers), 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 names a specific resource and its scope: ATM implied volatility by expiration (the IV term structure), plus spot and the overall ATM IV for a ticker. An agent can tell this is a vol-curve tool rather than a chain or single-contract tool. It stops short of explicitly contrasting with the nearest sibling (contract_atm), which keeps it at 4 rather than 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 gives concrete when-to-use signals via example questions ('is NVDA implied volatility elevated?', 'is the vol curve inverted before earnings?'), which is clear context. It does not name a when-not condition or point to alternative tools, so it is clear-but-incomplete rather than fully routing.

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