FirmTape - SPX dealer positioning, 100+ symbols

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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds extra behavioral context: US-only, date range 2019 to ~a year ahead, max 31 days per call, and each event's metadata. It does not contradict annotations, and the added limits are valuable.

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 well-organized: purpose, event list, usage examples, exclusions, limits. Each section earns its place, though some redundancy with the schema (e.g., 31-day limit) could be trimmed. Front-loading the core purpose is effective.

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 (has_output_schema=true), the description need not detail return values. It covers what the tool does, when to use it, what data is included, and its constraints. Nothing an agent needs to decide whether to call 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?

Schema description coverage is 100%, so all three parameters are already documented. The description repeats the 31-day limit (also in the 'to' parameter description) and adds no new parameter-level meaning. Baseline of 3 is appropriate when the schema handles parameter 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?

The description states a specific verb (get/list) and resource (US market events from the FirmTape calendar), enumerates the event types, and explicitly distinguishes itself from get_session and get_levels. An agent can immediately tell what it does and what it is not.

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 explicit 'Use when' examples ('what is on the calendar this week', 'when is the next FOMC') and 'Not for' exclusions naming two sibling tools. This is clear guidance for when to choose 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, 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 declare the safe read-only/idempotent profile, so the description correctly focuses on non-obvious traits: the live day is excluded (it sits behind the paid live stream), coverage starts 2022-04, and timestamps are ET. It also discloses what a null headline means rather than leaving it ambiguous. No rate-limit or pagination behavior is mentioned, keeping it 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-loads the payload, then usage, then limits in a clear order. Some phrasing is expository rather than functional ('the honest reading that no headline existed and the dealer book moved on its own'), which costs a little density but does explain an ambiguous output case.

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 description is not required, yet the description still summarizes the per-minute fields. Combined with the explicit data-availability window, clock, and default session, 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%, so the default baseline applies. The description reinforces the meaning of the tape filter (minutes 'the tape itself marked as market-moving' vs. headline-less moves), which loosely illuminates tape_only, but adds no syntax or format 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 resource — the minutes of one finished SPX session that the tape flagged as market-moving — along with the payload each minute carries (scheduled event, news-desk cluster timing, index move over 5/15 min, flip and walls). It explicitly distinguishes itself from get_events and get_levels by name, 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?

Gives concrete 'Use when' exemplars ('what moved SPX at 14:25 on 2026-09-10', 'were there news-driven minutes yesterday') plus a 'Not for' clause naming the two alternatives (get_events, get_levels). Hard constraints (finished sessions only, data from 2022-04, ET clock) are stated outright.

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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds value beyond annotations by disclosing that only finished sessions are available, that each call returns one day, and that FirmTape publishes measurements rather than buy/sell signals. 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 front-loaded with the most important information, followed by clear 'Use when' and 'Not for' sections and a final limitation note. Every sentence earns its place, and the structure makes it easy for an agent to parse quickly.

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 tool with an output schema, the description is fully complete: it explains what is returned, when to use it, when not to use it, and its limits. The output schema covers return structure, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents the day parameter thoroughly with pattern, examples, and error conditions. The description adds context about the 'finished sessions only' limitation and one-day-per-call behavior, but it does not need to repeat parameter details. Baseline 3 is appropriate.

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

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

The first sentence states a specific resource ('ONE finished SPX session') and enumerates exactly what is returned: OHLC, VWAP, zero-gamma flip, walls, hold band, net-gamma percentile, ATM IV. The 'Not for' section names siblings, so an agent can distinguish this from get_levels, get_level_history, and get_gex_profile without opening 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?

Explicitly says 'Use when: you want a whole day in a single call' and gives concrete exclusion cases with sibling names: level set alone, multi-day level movement, and gamma by strike. It also states hard limits: finished sessions only and one day per call. This leaves no ambiguity 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.

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

Beyond the annotations (read-only, idempotent), the description discloses important behavioral traits: it is a 'latest snapshot only' rebuilt every few minutes, calls/puts are counted by convention rather than direct measurement, single-stock results are approximations, and units are 'US dollars of dealer delta per 1% move.' These details meaningfully inform invocation and interpretation.

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?

Although longer than average, every sentence carries distinct information: scope, return contents, use cases, exclusions, limits, conventions, and units. It is front-loaded with the core purpose and then organized into clear 'Use when,' 'Not for,' 'Limits,' and 'Units' segments.

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 a single parameter and no output schema, the description still covers what the tool returns, when to use it, what it excludes, its freshness limits, its conventions, and its units. An agent has enough context to decide whether to call it and what to expect 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?

The schema already fully documents the symbol parameter, so the baseline is 3. The description adds value by clarifying the symbol must be non-SPX, providing representative examples, and noting that unknown tickers return an error naming the supported-symbol page. This goes beyond the schema without needing to duplicate it.

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: 'latest dealer gamma picture for a symbol OTHER than the SPX archive,' and gives concrete examples like QQQ and NVDA. It also differentiates itself from siblings such as get_gex_profile and get_levels by explicitly excluding tape-signed and session-based books.

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

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

The description explicitly states 'Use when: the question is about a ticker's gamma exposure, flip or walls right now or at the last close' and 'Not for: SPX history, a past date, or the tape-signed measured book (get_session, get_levels, get_gex_profile).' This provides clear decision rules and names alternative 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 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?

With annotations already declaring readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, the bar is lower, yet the description adds substantial behavioral value beyond them: the matched-vs-archive comparison semantics, the critical base-rate caveat ('A matched share close to the archive's share is a base rate, not a pattern'), the closing-measurements-only scope, the per-call 50-session cap, and the disclaiming close. No contradiction with annotations (a read-only screening 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?

Dense but efficient: the core purpose and filter dimensions are front-loaded, followed by return structure, the base-rate interpretation caveat, routing guidance, and scope limits. Every sentence earns its place for a 13-parameter tool, though it is verbose enough that it cannot reach a 5 on conciseness.

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

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

Given the tool's complexity (13 params, screening plus archive-comparison semantics), the description is complete. An output schema exists to document return values, annotations carry the safety profile, and the description covers purpose, routing, interpretation caveat, scope limits, and disclaimers. Nothing an agent needs to select and 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 coverage is 100% with all 13 parameters documented (including enum meanings and the limit semantics), so the schema carries the full weight. The description adds contextual framing — mapping which dimensions are filterable — but introduces no new parameter syntax or value semantics beyond the schema. 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 (filter and count) and resource (finished SPX sessions in the FirmTape archive), then enumerates the exact filter dimensions (regime, crossings, band, direction, move size, gamma percentile, IV, event, weekday, year). It names what it is NOT for (get_session, get_gex_profile, the Lab), making it fully distinguishable from 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' examples ('how often did FOMC days close in negative gamma', 'largest moves on CPI days since 2024') and explicit 'Not for' exclusions that cite alternative tools (get_session for one day's numbers, get_gex_profile for gamma by strike, the Lab for out-of-sample testing). No inference left to the agent.

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 mark the tool as read-only, idempotent, open-world, and non-destructive. The description adds meaningful context: it searches only FirmTape's public pages and finished sessions, ranks by keyword, and returns ids rather than data. This goes well beyond the annotation baseline.

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 every sentence earns its place: purpose, return contract, date behavior, alternatives, exclusions, and scope limits. It is front-loaded with the core purpose and uses compact, scannable sentences.

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 search tool with rich annotations and no output schema, the description fully covers what is searched, what is returned, how dates behave, when to use alternatives, and what the tool does not cover. Nothing critical 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 query parameter is described as 'A topic, a question, or a trading date.' The description adds concrete value with date format examples and explains how a date maps to session(s), which improves the agent's ability to formulate valid queries.

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: search FirmTape for SPX dealer positioning documents. It also enumerates the exact content types searched and states it returns ids for fetch, clearly distinguishing it from siblings like list_sessions and get_session.

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 explicitly tells agents when to prefer structured tools (list_sessions, get_session, get_levels, etc.) and gives direct exclusions: don't use it for fetching by id or for a measurement with a known date. This is exemplary routing guidance.

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