FirmTape - SPX, ES, NQ, RTY gamma levels, 100+ symbols

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false). The description adds real behavioral context beyond them: only public FirmTape documents are reachable, and long pages are truncated with a link to the remainder. It does not mention auth requirements or rate limits, so it falls short of 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?

Front-loaded with the core action, then compactly sequenced as accepted inputs, use-when, not-for, and limits. Every clause carries routing or constraint information; there is 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 single-parameter read tool with no output schema, the description covers the return nature (full text prose), the truncation edge case, the input formats, and the routing decision against siblings. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already names the three accepted id kinds, so baseline is 3. The description goes further by explaining the prefix conventions (`session:YYYY-MM-DD`, `page:/path`) and that a bare date or URL also works, giving the agent format-level meaning the schema does not.

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 ('Retrieve the full text of one FirmTape document') and immediately names the id namespace that identifies the document. It explicitly distinguishes itself from get_session and get_levels, so an agent can route 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 explicit 'Use when' (you hold an id from `search`, or a client that only speaks search/fetch) and 'Not for' clauses naming the alternative tools that return structured numbers instead of prose. Both the selecting condition and the exclusion are 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?

Beyond the readOnly/idempotent annotations, it discloses operationally important behavior: the missing-day computation rule (weekdays minus US market holidays, early closes count), the calendar's 2022-2026 coverage limit, and the guarantee that missing days are reported and never filled. These are substantive traits the annotations cannot 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?

The description is dense but front-loads the resource and return shape before usage and limits. Every clause carries information, though the single packed opening sentence is slightly heavy; structure is good but not maximally scannable.

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?

An output schema exists so return values need no prose, yet the description still frames the exact fields returned and the semantics of 'missing'. Combined with the limits and routing guidance, nothing an agent needs to call this correctly is absent.

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

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

Schema description coverage is 100%; both from/to parameters are documented with format, pattern, examples, and defaults in the schema itself. The description only restates that they form an optional window, adding little beyond the structured fields, so the baseline of 3 applies.

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

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

The description names a specific resource (the SPX archive's coverage) and precisely enumerates what it returns: first/last finished session, session count, and missing NYSE trading days. It clearly distinguishes itself from list_sessions and get_session, so an agent can identify the tool 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?

It gives explicit 'Use when' examples ('is 2024-03-15 in the archive', 'which days are missing') and an explicit 'Not for' clause naming the two sibling alternatives (list_sessions, get_session) with the condition that selects them. This is textbook when/when-not/alternatives 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/openWorld, and the description adds substantive context beyond them: coverage limits (US only, 2019 to about a year ahead, at most 31 days per call) and what each event payload contains (ET minute, source link, measured follow-on behavior, dealer book reaction, forecast/prior/actual). These are real operational constraints an agent cannot derive from 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?

Front-loaded with purpose, then 'Use when', 'Not for', and 'Limits' in a clear progression that is easy to scan. The long enumeration of event types is informative but somewhat list-heavy and could be trimmed without losing routing value.

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

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

An output schema exists, so return-value documentation is not required, and the description still supplies coverage bounds, timezone for the returned minutes, and default behavior context. Combined with full schema coverage and rich annotations, an agent has everything needed to invoke this correctly.

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

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

Schema description coverage is 100%, so defaults, date patterns, the 31-day cap and the impact enum are already fully documented in the schema. The description only echoes the window and limit concepts generically without adding per-parameter meaning, 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 (scheduled US market events over a day window) and enumerates the event classes it returns, so an agent knows exactly what domain this covers. It explicitly contrasts itself with get_session and get_levels, making sibling disambiguation unambiguous.

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

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

Provides literal 'Use when' trigger phrasings ('what is on the calendar this week', 'when is the next FOMC') and an explicit 'Not for' clause routing to get_session and get_levels. Nothing about when to reach for this tool versus alternatives 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), and the description goes well beyond them: finished sessions only, 5-minute frame granularity with snap-back behavior, ±2.5% published window, non-comparability of the three books, and a 'measurements only, no signals' disclaimer.

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 definition, then usage, then limits, and every block carries information. It is dense and relies on stylistic emphasis (capitalized book names, em-dashes) that slightly hurts scanability, but no sentence is pure 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 an output schema present, return values need not be described; the description instead covers the constraints an agent must know (session state, frame granularity, window, symbol basis behavior). Nothing needed to call this 7-parameter tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds interpretive meaning beyond the schema: the three books are 'not comparable in magnitude', the level set belongs to the volume book regardless of which ladder is read, and ES/MES strikes are the SPX ladder shifted by the ES basis at the frame's minute.

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 ('gamma LADDER ... gamma by strike around spot, the level set, and the heaviest strikes') and scopes it to one minute of a finished session. It explicitly distinguishes itself from siblings by naming get_session, get_levels, and get_level_history as the wrong tools for adjacent questions.

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 when' clause (questions about SHAPE or a single intraday moment) and a 'Not for' clause that routes three named alternatives to their own tools. An agent can select between this and the siblings without opening any schema.

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 the description adds real behavioral context beyond them: max 40 sessions per call, finished sessions only, archive gaps surfaced in `missing` and never interpolated, ES/MES basis shifting with sessions lacking a basis dropped into `no_basis`, and an explicit 'measurements only, no signals or forecast' scope limit. These are operational traits an agent cannot derive from 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?

A single dense paragraph, but deliberately structured with 'Use when', 'Not for', symbol note, and 'Limits' segments. It is front-loaded with the core purpose and every clause carries routing or constraint 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 analytic tool with a full output schema and 100% parameter description coverage, the description supplies everything an agent needs that the structured fields do not: window limits, missing-data semantics, symbol/basis behavior, and the explicit absence of signals or forecasts.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter behavior the schema does not state — that `from` overrides `days`, how the ES basis is applied per session, and the fallback when fewer than two sessions have a measured basis. It stops short of detailing the contract roll semantics beyond the default front contract, so it is not a full 5.

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 — how dealer-positioning levels MOVED across sessions — and enumerates the exact artifacts returned (flip, call wall, put wall, per-session deltas, window stats). It explicitly distinguishes itself from get_levels, get_session, and get_gex_profile by name, so an agent can route 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?

Contains explicit 'Use when' (trend/window questions, instead of calling get_levels once per day) and 'Not for' clauses naming the correct alternatives for one day and intraday. Both the positive trigger and the exclusion set are stated, leaving nothing 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 still adds real behavior: finished sessions only, one day per call, no CME data, and the graceful fallback that a day without a measured ES basis returns SPX index levels and says so.

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 payload, then usage, exclusions, symbol routing and limits in a tight labeled sequence with no filler sentences. It is dense with domain jargon and runs long, but each clause carries operative information for tool selection.

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?

Covers purpose, when/when-not, sibling routing, symbol-specific caveats, and the one-day/finished-session limit. An output schema exists, so return-value explanation is unnecessary, and nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents day/symbol/contract patterns and examples. The description adds marginal routing semantics (ES/MES vs SPX, NQ coming from get_symbol_gamma) but no syntax the schema lacks.

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?

Names a precise verb+resource and enumerates the exact payload ('zero-gamma flip, call wall, put wall, plus where the session closed relative to them'). It also positions itself against the sibling it is a subset of ('A strict subset of get_session'), so an agent can distinguish it without opening either schema.

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

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

Explicit 'Use when' condition ('the levels are the whole question and the rest of the session would be noise') plus a 'Not for' list that routes each excluded need to a named sibling: OHLC/flip crossings/net-gamma percentile/ATM IV to get_session, multi-day to get_level_history, per-strike gamma to get_gex_profile.

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 the safety profile is covered. The description adds genuinely non-obvious constraints beyond that: finished sessions only, the live day belonging to the paid live stream, coverage starting 2022-04, and an ET clock. It does not discuss result size or rate limits, but the freshness/entitlement limits are the material ones and they are stated.

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 'Use when / Not for / Limits' scaffolding is well organized and front-loads the essentials, but the opening sentence is a sprawling, heavily clause-laden construction whose decorative phrasing ('what stood beside each', 'the honest reading that no headline existed') costs more than it returns.

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 an output schema handling return values, a 100%-covered input schema, idempotent/readOnly annotations, and a description that covers scope, use cases, exclusions, coverage start date, and entitlements, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, with both 'day' (format, default) and 'tape_only' (default true, what false adds) fully documented in the schema. The description reinforces the tape-vs-headline distinction prose-wise but adds no new parameter syntax or semantics. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description names a concrete resource and scope: the market-moving minutes of one finished SPX session, plus the three kinds of annotations each minute carries (scheduled event, news-desk item, or no headline at all). It also distinguishes itself from siblings by name in the 'Not for' clause. The ornate phrasing ('what stood beside each', 'the honest reading') slightly obscures an otherwise precise statement of purpose.

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

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

Explicit when-to-use examples are given ('what moved SPX at 14:25 on 2026-09-10', 'were there news-driven minutes yesterday', 'which afternoon moves had no headline'), and alternatives are named with the condition that routes away from this tool: the scheduled calendar (get_events) and the day's levels (get_levels). Nothing 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 declare readOnly/idempotent/non-destructive, and the description goes further with real constraints: finished sessions only, one day per call, SPX book re-expressed through the day's ES basis, and the deliberate absence of buy/sell signals. These are behavioral facts an agent cannot derive from structured fields.

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 payload contents, then organized into Use when / Not for / ES / Limits blocks. Dense but every sentence carries routing or constraint information; 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?

An output schema exists, so return-format detail is unnecessary, and the description supplies everything else an agent needs: scope, exclusion of siblings, session/one-day limits, and the ES basis caveat.

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 schema already explains day validation, the SPX/ES/MES basis transformation, and default/front-contract roll behavior. The description's ES note largely restates the schema, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Everything FirmTape measured for ONE finished SPX session') and enumerates exactly what is returned: OHLC/VWAP, zero-gamma flip and cross count, call/put walls, net-gamma percentile, ATM IV at the open. It explicitly carves itself apart from get_levels, get_level_history, and get_gex_profile, so an agent can route 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?

Contains explicit 'Use when' (a whole day in one call) and 'Not for' clauses naming three siblings with the condition that selects each (narrower level set, cross-day level movement, per-strike gamma). Nothing about tool selection 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?

Goes well beyond the readOnly/openWorld/idempotent annotations by disclosing freshness ('latest snapshot only, rebuilt every few minutes in session hours'), the dealer-long/dealer-short convention and its approximation on single stocks, the trust-grade meaning, and the units (USD dealer delta per 1% move). These are exactly the behavioral caveats an agent needs and none are in the structured fields.

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 purpose and the critical 'OTHER than SPX' constraint, and every clause carries real information. However it is a dense single block that mixes purpose, symbol lists, basis methodology, return fields, usage, and units, making it heavier than it needs to be for quick scanning.

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 fully compensates by enumerating returned fields (spot, zero-gamma flip, call/put walls, net gamma for VOLUME and OPEN_INTEREST books, heaviest strikes, per-expiry table, trust grade). Combined with symbol scope, freshness, and caveats, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the symbol pattern, examples, and contract semantics are already fully documented in the schema. The description adds futures-context (ES/NQ/RTY, MES/MNQ/M2K) but no syntax or format detail beyond what the schema carries, 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 ('latest dealer gamma picture') and immediately scopes it as 'for a symbol OTHER than the SPX archive', explicitly distinguishing it from the SPX tool the agent might otherwise assume. It enumerates the supported symbol classes (index/ETF/stock chains, E-mini futures) so the agent knows exactly what universe it covers.

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 when' clause (ticker gamma, flip, walls now or at last close, including ES/NQ/RTY) and a 'Not for' clause naming the exact alternatives (get_session, get_levels, get_gex_profile) and the condition (past date/history) that selects them. This is textbook 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, but the description adds substantial behavioral nuance beyond them: the meaning of a thermal anomaly (flaring, upset or fire read alike), that fires between passes are missed, that silence is never proof of nothing, and the curated ~110-site scope with FIRMS starting from each site's watch-begin date.

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?

Well organized with clear 'Use when:' and 'Not for:' segments and a compact 'Limits:' coda, front-loading what the tool covers. The opening sentence is dense to the point of being a run-on, which slightly hurts scannability, but nearly every clause carries needed domain meaning.

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 an output schema present, return formatting needn't be explained, and the description covers scope, caveats, interpretation limits and coverage boundaries. Nothing an agent needs to call or correctly interpret results is missing.

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

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

Schema description coverage is 100%, so the schema already documents q, id, kind and country with examples and patterns. The description adds domain framing (site's own normal, trailing 8-week median) but no parameter syntax or interaction detail beyond what the schema carries; 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 (sites watched by satellite) and enumerates exactly what is covered: refineries, terminals, LNG plants, depots and oil ports, with named geographies. The satellite data streams (FIRMS thermal anomalies, Sentinel-2 imagery, Sentinel-1 vessel counts) make it instantly distinguishable from the market/finance siblings.

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

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

Provides explicit 'Use when:' example queries and an explicit 'Not for: strike confirmation' exclusion. It even names the domain-specific alternatives the agent should reason about (thermal anomaly vs fire, images as context not damage evidence), leaving little 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 declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered. The description goes further by disclosing that only finished sessions appear (today's shows after the close) and that each call is capped at 50 days — real behavioral constraints an agent would otherwise have to discover by failing.

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 what the tool returns, then the when/not-for routing, then the limits. Every clause carries distinct information — scope, ordering, routing, freshness, cap — with no filler or repetition.

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

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

An output schema exists, so return-value detail is not required, yet the description still summarizes the key payload (total count, coverage span). Combined with the freshness and cap caveats, an agent has everything needed to call this correctly and interpret the result.

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?

Only one optional parameter and schema description coverage is 100%, so the schema already documents limit, its default of 10 and its max of 50. The description restates the max-50 cap but adds no format or semantics beyond the schema; the baseline of 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (list) and resource (finished SPX trading sessions in the FirmTape archive), plus ordering (newest first) and what comes back (total count, coverage span). This cleanly separates it from get_session and get_levels, which fetch a single day's data.

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

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

Explicit 'Use when' (discovering which days exist, or the archive size/span, before querying a day) and an explicit 'Not for' that routes measurement questions to get_session with a date. The alternative tool is named and the selecting condition is stated, leaving nothing 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 declare readOnly, idempotent, openWorld, and non-destructive behavior, so the safety profile is covered. The description adds crucial context beyond annotations: it returns counts plus two shares compared against archive-wide shares, lists at most 50 matched sessions, and warns that a matched share close to the archive's share is a base rate rather than a pattern. It also restricts counting to finished sessions' closing measurements with no per-strike data.

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

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

The description is dense but front-loads the core purpose before moving into returns, usage, exclusions, and limits. The labeled 'Use when', 'Not for', and 'Limits' sections make it easy to scan. It is slightly long and the initial filter enumeration partly repeats the schema, but every section serves a distinct purpose.

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

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

Given a 12-parameter filtering tool with an output schema, the description supplies what an agent needs: counts and shares semantics, a 50-session listing cap, the fact that counts cover all matches, and clear routing to sibling tools. Output schema existence means return format details are not required, and the description still adds useful output context.

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

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

Schema description coverage is 100%, so each of the 12 parameters already has a clear enum or format description. The description enumerates the filters in prose but adds no syntax, default, or interpretation detail beyond what the schema already provides. The baseline score of 3 is appropriate when the schema carries the parameter semantics.

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

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

States a specific verb and resource: filter finished SPX sessions in the FirmTape archive by closing measurements and count them. It distinguishes itself from siblings by naming get_session, get_gex_profile, and the Lab as alternatives for other tasks. An agent can tell exactly what this tool does and does not do 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 explicit 'Use when' examples ('how often did FOMC days close in negative gamma', 'the days that closed below the flip with the percentile under 20') and an explicit 'Not for' section routing to get_session, get_gex_profile, and the Lab. This is textbook when/when-not/alternatives 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, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond them: it returns ids intended for `fetch`, it only searches FirmTape's own public pages and finished sessions, and results are keyword-ranked rather than exhaustive. It stops short of describing result volume or pagination.

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 critical scoping and routing information is front-loaded, and the sentence about preferring structured sibling tools is the highest-value line. It runs long at five sentences with some overlap between the "prefer the specific tools" and "Not for" clauses, so it is slightly denser than necessary.

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 explains the return contract (ids to pass to `fetch`) and the corpus limits, ranking method, and date handling. The remaining gap is operational detail such as result counts or pagination, which an agent might want for a ranked keyword search.

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

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

Schema coverage is 100% but the schema's own parameter note is thin ("A topic, a question, or a trading date"). The description compensates by giving concrete accepted date forms ("2026-08-24", "August 24 2026", "August 2026") and explaining that a date resolves to that session or sessions, which the schema alone does not convey.

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

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

The description opens with a specific verb+resource ("Search FirmTape") and narrows the corpus to documents about SPX dealer positioning: explainer pages, dated research measurements, and finished session archives. It distinguishes itself from the sibling tools by naming them and stating what they return instead (structured numbers vs. documents).

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

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

It gives explicit routing guidance: clients able to call specific tools should prefer list_sessions / get_session / get_levels / get_level_history / screen_sessions, and it adds a dedicated "Not for" clause covering fetch and nameable-date measurements. Both when-to-use and when-not-to-use are stated with the alternative named.

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 declare readOnly/idempotent/non-destructive, and the description adds substantive context beyond them: what is being matched (eight named measurements), the base-rate caveat about the archive comparison, that similarity is on these eight numbers only, and the history-not-forecast disclaimer. No contradiction with annotations.

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

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

Front-loads purpose, then use/not-for, then limits and disclaimers — a sensible order. The enumeration of eight measurements is dense but justifies itself for matching semantics; a few clauses (advice disclaimer, replay link) could be trimmed.

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 annotations and an output schema already covering safety and return shape, the description still delivers purpose, sibling routing, hard limits, the base-rate interpretation caveat, and the similarity basis. Nothing an agent needs to call it correctly appears missing.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: it names the eight state measurements that the unlabeled lanes arrays (flip, vwap, gpct, etc.) encode, and clarifies the moment-of-day matching semantics behind day/minute.

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: find finished SPX sessions whose eight-measurement state at the same time of day was nearest a given moment, plus what those days did afterwards. It enumerates the state vector and distinguishes itself from screen_sessions and the Lab by name.

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

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

Explicit 'Use when' examples ('what happened on days like this', 'days that looked like 2026-10-14 at 11:00') and explicit 'Not for' routing to screen_sessions (named conditions) and the Lab (out-of-sample testing). Limits (finished sessions 09:45–15:30 ET, SPX only) further bound usage.

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