FirmTape - SPX dealer positioning

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

Annotations already signal read-only, idempotent, open-world, non-destructive behavior. The description adds meaningful behavioral context beyond those: public documents only, and long pages are truncated with a link to the rest. This fully discloses the key operational caveats.

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 well-structured: it front-loads what the tool does, then covers id formats, usage context, exclusions, and limits in a compact set of sentences. No filler or restatement of the 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 single-parameter read tool with strong annotations and no output schema, the description covers what an agent needs: id formats, when to use it, when not to use it, alternatives, access limits, and truncation behavior. Nothing essential is missing.

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

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

The schema covers the id parameter at 100%, but the description goes further by specifying the exact accepted forms: `session:YYYY-MM-DD`, `page:/path`, a FirmTape URL, or a bare YYYY-MM-DD trading day. This gives the agent enough detail to construct a valid id.

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

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

The description states a specific verb and resource: retrieve the full text of one FirmTape document by id. It enumerates accepted id formats and explicitly contrasts the tool with get_session and get_levels, so an agent can distinguish it from siblings without inspecting schemas.

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 when-to-use conditions ('you hold an id from search, or a client that only speaks search/fetch') and explicit when-not-to-use conditions ('Not for: structured numbers — get_session and get_levels answer the same day with fields instead of prose'). This is model 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 establish read-only, idempotent, non-destructive behavior, so the bar is lower, but the description still adds substantial context: finished sessions only, 5-minute frame snapping, ±2.5% published window, non-comparable book magnitudes, and no buy/sell signals. This tells the agent what to expect beyond what annotations 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 long but tightly organized: definition, conventions, use-when, not-for, limits, and a final qualifier. Every sentence carries operational or routing information, and the core purpose is front-loaded.

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

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

For a tool with a rich output schema and full parameter documentation, the description supplies all the missing operational context: conventions, minute snapping, session restrictions, window limits, and exclusions. An agent has enough to select the tool, choose parameters, and interpret the result 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 baseline is 3, but the description enriches parameter meaning by explaining that the three book conventions offer three lenses on the same minute, that books are not comparable in magnitude, and that the published window constrains strikes_around_spot. This goes beyond ordinary schema documentation.

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: it returns the SPX dealer gamma ladder for a single minute of a finished session, including gamma by strike, the level set, and heaviest strikes. It also distinguishes itself from siblings by naming what it is not for, so an agent can recognize it as the minute-level shape 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?

Explicitly says 'Use when' the question is about gamma shape or a single moment in a session, and 'Not for' day headline numbers, level set alone, or cross-day movement, naming get_session, get_levels, and get_level_history as alternatives. This gives the agent precise 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 cover the safety profile (read-only, idempotent, non-destructive), and the description adds genuinely useful behavioral context beyond them: finished-sessions-only scope, hard 40-call limit, missing archive days reported in `missing` rather than interpolated, and the explicit boundary that it provides measurements only — no signals or forecasts. 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?

Dense but well-organized: the core function is front-loaded, followed by labeled sections ('Use when', 'Not for', 'Limits') that make the routing logic scannable for an agent. Every sentence earns its place, including the summary-statistics inventory and the 'no forecast' disclaimer.

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?

Complete for a read-only windowed-historical tool. The output schema covers return values; the description summarizes what the output contains (flip range, net drift, mean daily movement, close-above-flip frequency) and names the `missing` field. Nothing an agent needs to decide or invoke 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%, so the baseline is 3 — each parameter already has defaults, constraints, examples, and precedence semantics ('from overrides days'). The description adds only marginal context (finished-sessions scope reinforced, max 40 restated) but does not materially compensate beyond what the schema already documents.

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

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

The description states a specific verb+resource+scope: how SPX dealer-positioning levels (zero-gamma flip, call resistance, put support) MOVED across finished sessions, including per-session deltas and window summary statistics. It explicitly names the siblings it is not (get_levels, get_session, get_gex_profile), so an agent can distinguish it from alternatives without inspecting their schemas.

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' conditions (trend/window questions like 'has the flip been climbing') and explicit 'Not for' exclusions (single day → get_levels/get_session; intra-session → get_gex_profile). This gives the agent a complete routing decision tree for when this tool beats calling get_levels repeatedly.

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, and non-destructive behavior. The description adds meaningful context beyond annotations: the tool only serves finished sessions, one day per call, and returns a strict subset of get_session. This clarifies data scope and constraints without contradicting annotations.

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

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

The description opens with the core definition, then gives crisp usage guidance and exclusions, and ends with limits. Every sentence earns its place, and the structure front-loads the most decision-relevant information.

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

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

With an output schema present, return-value explanation is unnecessary. The description covers what the tool returns, how it relates to siblings, when to use it, when not to, and its hard limits. Nothing an agent needs to select and invoke this 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%; the schema already fully documents the 'day' parameter with pattern, examples, and error conditions. The description re-emphasizes 'one day per call' and 'finished sessions only' but adds no new semantic information 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 resource ('dealer-positioning level set for one finished SPX session'), enumerates the exact contents, and explicitly calls itself 'A strict subset of get_session,' distinguishing it from siblings. An agent can immediately tell what this tool returns and how it differs from related tools.

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

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

Provides explicit 'Use when' and 'Not for' conditions, naming the exact sibling tools for each excluded case (get_session, get_level_history, get_gex_profile). No ambiguity remains about when to select this tool over alternatives.

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 behavior, and the description adds meaningful constraints: finished sessions only, one day per call, and the deliberate absence of buy/sell signals. It also clarifies the tool returns a holistic measurement bundle rather than a signal or opinion. This exceeds what annotations alone would tell the agent.

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 front-loaded with a dense but readable list of contents, then structured into 'Use when', 'Not for', and 'Limits' sections, each sentence serving a distinct purpose. There is slight redundancy between 'ONE finished SPX session' and 'finished sessions only, one day per call', but it is used to reinforce a key constraint. No filler or irrelevant detail.

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 and full parameter schema coverage, the description covers the essential invocation context: what is included, when to choose it, which alternatives to use, and the tool's explicit non-signal stance. It also points the agent to the required input domain (finished trading days). Nothing an agent needs to correctly select and call this tool 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?

The schema already fully documents the single required `day` parameter with pattern, example, and error behavior for invalid days (100% coverage), so the description doesn't need to add much. The description's 'finished sessions only, one day per call' reinforces the parameter's semantics but does not add new syntax or formatting detail. Baseline 3 is appropriate because the schema carries the load.

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 ('Everything FirmTape measured for ONE finished SPX session') and enumerates the included data (OHLC, VWAP, gamma flip, walls, hold band, net-gamma percentile, ATM IV). It explicitly differentiates from siblings by naming get_levels, get_level_history, and get_gex_profile as different scopes. This leaves no ambiguity about what this tool returns.

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

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

It gives an explicit 'Use when: you want a whole day in a single call' and a 'Not for' list naming the exact alternative tools for each different need. It also states limits (finished sessions only, one day per call) so an agent can decide when to invoke it. No relevant usage condition 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 establish readOnly/openWorld/idempotent/non-destructive safety, and the description adds meaningful behavioral context beyond them: only finished sessions are listed, today's session appears only after the close, the call returns total count and coverage span, and there is a max of 50 days per call. No contradiction with annotations.

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

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

The description is compact and front-loaded: the first sentence states the core purpose and result, followed by relationship to siblings, usage guidance, exclusions, and limits. Every sentence earns its place with no repetition or filler.

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

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

For a simple listing tool with one optional parameter, rich annotations, and an output schema, the description covers purpose, usage boundaries, alternatives, data freshness, archive span, and call limits. Nothing needed to decide when and how to invoke it 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?

The schema already documents the single optional 'limit' parameter with default and maximum, and schema coverage is 100%. The description reinforces the max 50 days per call but does not add semantic meaning beyond what the schema provides, 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 states a specific verb ('List'), a specific resource ('finished SPX trading sessions'), and ordering ('newest first'), plus what the result includes (total count, coverage span). It also distinguishes itself from siblings by naming get_session / get_levels as the tools for fetching individual days.

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' and 'Not for' guidance is provided: use it to know which days exist or the archive size/span, not for any measurement about a day, in which case get_session is the named alternative. This fully routes an agent to the correct tool.

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

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

Discloses material behavior beyond annotations: it costs 10 credits, refunds on failure, requires a Lab token, uses median bid/ask fills at $1.25 per leg, reports a recommended direction only under strict conditions, never names a best cell, and may auto-expand to 154 configurations. No contradiction with the annotations; readOnlyHint=false is consistent with a credit-spending test operation.

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

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

The purpose is front-loaded and the detail is mostly earned given the tool's complexity, covering output shape, fill assumptions, costs, and failure behavior. Some phrasing is verbose and slightly winding, but no critical information is buried.

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 properly enumerates returned items: marginal by width and entry, a conditional recommended direction, the day-clustered mean and error, prob_loss_20, and the 63 marked cells. It also covers pricing, cost, refunds, authentication, and the expanded grid behavior, making it thorough enough to invoke correctly.

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

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

The input schema already provides 100% descriptive coverage for legs, qty, dist, right, and entry, including clear examples. The description adds context about the 63-way grid and that entry only marks which cell is yours, but it does not substantially expand parameter-level meaning beyond what the schema already gives.

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: 'Test an SPX 0DTE options strategy' against the FirmTape archive on real quotes and real settlement. This clearly differentiates it from the sibling data-retrieval tools like get_gex_profile, get_levels, and get_session, which do not backtest strategies.

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 makes it clear this is for testing options strategies against archived real-market data and describes the kind of answer it produces, so an agent can infer when to choose it over the alternatives. However, it does not explicitly name sibling tools or state when not to use it.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses meaningful behavioral traits: it 'returns ids to pass to fetch,' supports three date formats for locating sessions, is limited to FirmTape's own public pages and finished sessions, and ranks results by keyword. It also clarifies it searches no other site, which adds concrete scope beyond the raw openWorldHint.

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 compact yet dense; every sentence earns its place. It front-loads the core purpose, then covers return behavior, date handling, preferred alternatives, explicit exclusions, and scope limitations in a clear sequence. The non-goal and limits sections are terse but comprehensive, 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 present, the description compensates by stating that results are ids to pass to fetch. It covers all relevant context for a single-parameter search tool: what content is searched, what a query can be, how dates are handled, when not to use it, and the boundaries of the search space. An agent has enough information to call this tool correctly and route the output to the right next step.

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

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

The schema already describes the single parameter ('A topic, a question, or a trading date'), so the baseline is 3. The description adds real value by giving specific date format examples ('2026-08-24', 'August 24 2026', 'August 2026') and explaining that a date resolves to the corresponding session or sessions. This goes beyond the schema shorthand without being exhaustive.

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 and resource: 'Search FirmTape for documents about SPX dealer positioning,' and enumerates exactly what kinds of documents are searched (explainer pages, dated research measurements, finished session archive). It also distinguishes itself from structured-data siblings by noting it returns document ids, making its purpose unambiguous.

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

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

Usage guidance is explicit and actionable: it names the preferred alternatives (list_sessions / get_session / get_levels / get_level_history) and the reason (structured numbers vs documents). It also gives clear negative cases: not for documents you already have the id for, and not for any measurement you can name a date for. This leaves no doubt about when to select this tool.

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