Sardine: Kalshi crypto settlement history

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

Beyond the annotations, it discloses detailed simulation mechanics: per-second replay, one trade per window, limit-order latency, fill constrained by resting size, real fees, official settlement, and warnings. It also states the result shape and the limitation 'Results only; no raw data,' giving an agent unusually rich behavioral context.

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 core question and then proceeds through rule definition, simulation mechanics, and output caveats without filler. Despite its length, every sentence contributes useful context for a 12-parameter simulation tool.

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

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

For a complex historical simulation tool, the description covers the conceptual model, output expectations, and interpretation caveat well, and an output schema already exists. The main remaining gap is that a few input parameters are not fully described, which could affect precise invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains side/BEST, min_gap_cents, latency_seconds, price cents, minutes left, and date formatting, but leaves contracts and max_gap_cents unexplained and only loosely covers min/max price and minute bounds.

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 action — replaying recorded Kalshi quotes to backtest a rule — and scopes it to 15-minute crypto up/down contracts. It clearly distinguishes this historical simulation tool from live-board and track-record siblings by its replay/backtest framing.

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 explains how to describe a rule and how to interpret results ('what happened historically, never as a forecast'), but it does not explicitly say when to choose this over siblings like get_track_record or get_live_board. Usage is therefore implied rather than fully directed.

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 far beyond the readOnly/idempotent annotations: it discloses the fill model (ask at that second, limit order after latency, capped by resting size), fee and settlement handling, the 5,000-signal cap, the 15-minute window dedup rule, that only aggregates are returned, and the key requirement. That is exactly the extra context annotations cannot carry.

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 core action, then packs only decision-relevant detail into each following sentence. Nothing repeats the schema or the annotations, and the closing interpretive caveat earns its place.

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

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

An output schema exists so return values need no explanation, yet the description still summarizes the aggregate shape and adds the `signals_used`/`signals_outside_data` fields, which is useful. The remaining gap is the undocumented start_date/end_date range behavior for what is a data-window-dependent tool.

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

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

Schema coverage is 0%, so the description must compensate, and it does for the hardest parameter: `signals` is fully specified (ts as UTC epoch seconds, side YES/NO, contracts int, max 5,000) and `latency_seconds` is given meaning via the fill model. However `start_date` and `end_date` are never mentioned, leaving their format and boundary semantics undocumented.

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?

Opens with a specific verb+resource ('Replay YOUR OWN signals on recorded per-second Kalshi quotes, after fees') and pins the scope to user-supplied signals rather than a rule, which is exactly what distinguishes it from the sibling backtest_rule. An agent can tell what this does 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?

Gives clear operational context: each signal is a trigger, one trade per 15-minute window with later signals ignored, needs a free key when served remotely, and results are historical not predictive. It never explicitly says when to choose this over backtest_rule, so it falls short of the top band.

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 annotations, it discloses the critical behavioral constraint that prices are deliberately omitted for licensing reasons and explains the workaround. It also describes the row contents, including minutes left, settlement rate interval, sample size, and summary, which is significant context beyond readOnly/idempotent hints.

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 core result and the no-prices constraint, then explains row shape and the workaround. It is somewhat verbose but every sentence carries useful information for correct invocation.

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 structure need not be fully explained, and annotations cover safety. The description is complete about the no-prices behavior and row contents, but omits limit semantics, which is the main remaining gap for a parameterized tool.

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

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

With 0% schema description coverage, the description must carry parameter meaning. It explains that market can optionally filter to one market, but it never explains the limit parameter, the allowed market enum values, or their defaults, leaving a meaningful gap.

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

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

The description states a specific resource and scope: open Kalshi contracts with Sardine's historical count, explicitly excluding prices. It distinguishes this from the sibling get_settlement_rate by describing the downstream handoff of kalshi_ask to that tool.

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

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

It gives clear usage context: optionally filter to one market, and if you need prices, read them from Kalshi's API and pass kalshi_ask to get_settlement_rate. It lacks explicit when-not-to-use guidance versus other board-like siblings, but the intended workflow is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds useful detail about the row contents but does not disclose freshness, caching, data source behavior, or any operational constraints beyond what annotations provide.

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

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

The description is two sentences and front-loads the core purpose before describing row structure. It is efficient, though some row details overlap with the output schema.

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

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

An output schema exists, so the row description is not strictly necessary, but it does help. However, the definition leaves gaps around parameter meaning and when to use this tool rather than a sibling, making it only minimally complete for the agent's selection and invocation needs.

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 0%, so the description needs to explain asset and window_minutes. It does not mention either parameter or their allowed values, and 'one series' is too vague to compensate for the undocumented enum parameters.

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

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

The description clearly states that this returns a full lookup table for one series and explains the row structure. It is specific about the resource and data shape, though it does not distinguish the tool from siblings like get_settlement_rate or get_live_board.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no explicit exclusions. 'For one series' is the only scope hint, but it does not tell the agent which sibling to choose.

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 standard read-only annotations, the description adds critical behavioral traits. Most importantly, it explains the data quality of the output, warning that 'A small `windows_counted` means a weak answer,' which is vital for user expectation management.

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 structure is highly logical, first presenting the core concept and input requirements, followed by a detailed breakdown of all possible return values. The detail is extensive, though it requires a high level of patience from the agent.

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 complexity (multiple inputs and a list of 7 highly specific output parameters), the description is remarkably complete. It covers not just what is returned, but the meaning of specialized metrics like 'gap after fee' and the necessity of high `windows_counted` values.

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 0%, meaning the description must carry all semantic weight. It succeeds by explaining the financial implication of the optional `kalshi_ask` (to get fee and all-in price) and clarifying what `window_minutes` signifies.

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

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

The description clearly states the primary purpose: answering 'How often has a contract like this one settled in favour of side?' It immediately frames the tool's function in the context of historical settlement rates.

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?

While it describes the required inputs (strike, minutes left, etc.), it does not provide explicit guidance on when to use this specific tool versus related sibling tools like `get_lead` or `get_rate_table`. It implies usage through parameter description but lacks comparative context.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety needs no restating. The description adds substantive domain context: the data is a historical accuracy audit comparing predictions to settlements. It doesn't mention freshness/coverage windows, but with an output schema present, much of the return detail is already structured.

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

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

Three short sentences, front-loaded with what the metric is, followed by the return granularity and the usage cue. No filler or redundancy.

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?

A no-parameter read tool with annotations covering safety and an output schema covering the return shape. The description supplies the remaining conceptual context an agent needs: what 'track record' means here and why it matters.

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?

Zero parameters, so the baseline of 4 applies. There is nothing for the description to clarify beyond implicitly noting the results are unfiltered across all series and buckets.

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 (Sardine's published numbers scored against settlements) and a specific output shape (per series and probability bucket: predicted, settled, miss in points). This is clearly distinct from siblings like backtest_rule or get_settlement_rate, which measure different things.

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

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

"Use this before relying on any number" gives a concrete trigger condition for invoking the tool. It does not name an alternative or state when not to use it, which keeps it short of a 5.

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

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

Annotations already establish that the tool is read-only, idempotent, open-world, and non-destructive. The description adds useful context beyond that: the formula is returned with the numbers, values are current, and settlement-rate data is not included. No annotation contradiction is present.

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 short, front-loaded with the main purpose, and avoids repetition. The second sentence is slightly dense with domain jargon such as 'builder running the table offline,' but it still earns its place by clarifying the return and alternatives.

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

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

The output schema and annotations cover return shape and safety profile, so the description does not need to repeat them. However, for a four-required-parameter query tool with zero schema description coverage, the lack of parameter guidance leaves a material completeness gap.

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

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

Schema description coverage is 0% for four required parameters, and the description does not explain any of them (asset, window_minutes, strike, minutes_left). It mentions returned fields rather than input semantics, providing only broad domain framing rather than parameter-level compensation.

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

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

The description states that the tool reports where a contract sits in the table's coordinates and enumerates the returned values (spot, sigma_1m, z, bucket). It also distinguishes this from get_rate_table and get_settlement_rate by explicitly excluding settlement rates, though the name get_z itself is not fully self-explanatory.

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 a clear usage context for a builder running the table offline against Kalshi's feed and explicitly routes settlement-rate needs to get_rate_table and get_settlement_rate. It does not cover every sibling (for example get_live_board), but the main alternatives are 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 already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered without the description. The description adds genuinely useful context beyond that: the payload is CSV files that open in Excel or pandas, entries carry row counts, date ranges and URLs, and there is an attribution obligation. It is still ambiguous whether calling the tool returns only URLs/metadata or the file contents themselves.

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

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

Three short sentences, front-loaded with the resource and its contents. The attribution sentence is short and necessary; the opening fragment 'Downloadable CSV history files' is a slightly clipped construction but costs nothing.

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 zero parameters and an output schema present, the description only needs to frame what the data is, how it is consumed, and any obligations. It does all three. The remaining gap is relational context: it does not say how this catalog relates to the sibling data tools.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading parameter implications are present.

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 what the tool surfaces: downloadable CSV history files with row counts, date ranges, and URLs. That is specific enough to know it returns a catalog of dataset metadata rather than data rows. It never names a verb like 'list' and does not distinguish itself from data-returning siblings such as get_track_record or get_rate_table.

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

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

There is no statement of when to choose this tool over its siblings, nor any exclusion or prerequisite. The only guidance is a licensing request ('Credit Sardine...'), which is an attribution rule rather than tool-selection guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds that entries carry a served/unserved state and a calibration gap metric, which is context, but it says nothing about ordering, cost, or how often the served state changes.

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 in the first clause, and the second sentence is a compact enumeration of what an entry contains. The field enumeration partly duplicates the output schema, but it is short enough not to be waste.

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

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

For a zero-parameter, read-only listing tool with an output schema and full annotation coverage, this is nearly complete. The only gap is guidance on how this list relates to the other discovery and data tools.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to compensate for. The example key format ("BTC-15M") is a small bonus for interpreting results.

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?

Specific verb and resource: lists the Kalshi series Sardine covers, with the extra state dimension of whether each is currently served. It is clearly the enumeration tool among siblings like get_live_board and get_track_record, though it never names an alternative to distinguish itself explicitly.

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

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

Usage is only implied: an agent can infer this is the discovery step before calling get_live_board or get_rate_table, but the description never says when to use it versus those siblings, nor any prerequisite or exclusion.

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