Commodities Markets Desk

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

The readOnlyHint annotation already establishes that this is a safe, non-mutating calculation. The description adds useful output behavior—'% edge and a BUY / SELL / SKIP signal with a plain-English read'—but does not disclose internal assumptions or edge thresholds. This is adequate but not rich.

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 three sentences: function and outputs, use cases, and provenance/track-record context. It is front-loaded and every sentence earns its place, though the final track-record sentence is slightly promotional.

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 two-parameter read-only calculator, the definition is complete enough: it names the domain, inputs, outputs, and intended use cases. There is no output schema, but the description gives a reasonable picture of the return value. A bit more detail about how the BUY/SELL/SKIP thresholds are derived would be helpful but not necessary for correct invocation.

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

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

Schema description coverage is 100%, and both marketPrice and yourProbability already have detailed descriptions including accepted formats (percentages, decimals, American odds). The description adds no parameter semantics beyond what the schema already 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 opens with a specific verb and resource: 'Calculate the expected-value edge on a Kalshi or Polymarket prediction-market contract.' It names the inputs and the exact outputs (% edge and BUY/SELL/SKIP signal), making the function unambiguous and clearly distinct from siblings like convert_probability or kelly_size.

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 when to use the tool: 'Use for "is this contract mispriced", "what is my edge", "should I take this position".' This gives clear context, though it does not name sibling tools or specify 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?

Annotations only declare readOnlyHint=true and openWorldHint=true. The description adds substantial behavioral context: the exact trade-ticket fields returned, the Pro key requirement, and the honesty guarantee that unmodeled tickers return not_covered rather than a fabricated edge. 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 and front-loaded with the core action and ticket contents, followed by natural-language examples and tickers usage. Almost every sentence earns its place, though 'highest-conviction' and 'largest model edge' are slightly redundant and the paragraph could be tightened.

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 full schema coverage and no output schema, the description covers the returned ticket fields, authentication, example queries, and edge-case honesty for tickers. The only notable gap is an explicit statement of the fallback when no edge exists for a bare commodity request without tickers.

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

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

Schema coverage is 100% and both parameters already have meaningful in-schema descriptions. The description still adds value beyond the schema by explaining how to use tickers[] (paste watchlist, full vs 3-segment tickers, not_covered behavior), which justifies a score above the baseline 3.

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

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

States a specific verb ('Get') and resource (highest-conviction PMP edge-model trade signal for gold, silver, WTI oil, or bitcoin), and enumerates exact Kalshi contracts (KXGOLDD, KXSILVERD, KXWTI, KXBTCD). The commodity focus clearly separates it from siblings like combo_edge, nfl_edge, and calculate_ev.

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 for' query mappings and a precise condition for passing tickers[] (to check specific Kalshi markets, e.g. a Pro screener watchlist). It does not name alternative tools or say when not to use this tool, which would raise it to 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 communicate readOnlyHint=true, so no side-effect warning is needed. The description adds useful behavioral context beyond annotations: it returns all three representations at once and specifies that American odds carry no commas (e.g., +441 or -200). This helps the agent set expectations about output formatting.

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: one purpose sentence, one outcome sentence, and a short list of use-case examples. Every sentence earns its place, the main behavior is front-loaded, and there is no redundant restating of the tool name or 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?

For a simple two-parameter conversion tool with full schema coverage and a read-only annotation, the description is largely complete. It states inputs, output behavior, and formatting conventions. The only minor gap is that it does not specify the exact response structure or key names, but 'get all three back' is sufficient for most agent workflows.

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. The description adds value beyond the schema with concrete examples like '+150', '62%', and '2.5', and clarifies the American odds formatting constraint. This helps an agent understand accepted value forms without relying on enum hints alone.

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: 'Convert between implied probability, American odds, and decimal odds.' It also states the exact outcome—'get all three back'—and gives concrete user-phrase examples that remove ambiguity. No sibling tool overlaps with this conversion purpose, so it is clearly distinguishable.

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

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

The description gives explicit usage contexts: 'Use for "what is +150 as a probability"', 'convert 62% to American odds', and 'decimal to implied odds.' These examples tell an agent when to invoke the tool. It does not explicitly state when not to use it or name alternatives, but the sibling list contains no competing conversion 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?

Building on annotations readOnlyHint=true and openWorldHint=true, the description adds useful behavioral context: 'Free, no key', 'live', and the fact that pre-launch S&P 500, Nasdaq 100, and Treasury-yield series are also included. It does not contradict the annotations and adds value beyond what the structured fields alone 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 front-loaded with the core purpose and follows with output details, parameter hints, and example queries. It is longer than strictly necessary, mostly due to an extensive parenthetical list of series, but each section earns its place and the structure is logical.

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

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

With no output schema, the description carries the burden of explaining return content, and it does so thoroughly: open-window status, two-sided mid YES price, close time, target price, settlement condition, and settled-up share over the last 96 windows. Combined with full parameter schema coverage and read-only annotations, an agent has enough context to invoke the tool 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. The description goes slightly beyond the schema by providing concrete alias examples ('eth', 'KXETH15M', 'natural gas') and by clarifying that 'series' selects one market while 'asset_class' filters. This helps an agent map user intent to parameters more reliably.

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

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

The description names a concrete resource (Kalshi 15-minute up-or-down markets) and a clear action: list or filter them live. It enumerates the data returned (open window, YES price, close time, target price, settlement basis, settled-up share), and mentions pre-launch series. This is specific enough to distinguish it from any sibling tool without opening 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?

The description gives explicit usage context with example user queries ('what is the ETH 15 minute market doing', 'which Kalshi 15-minute markets are open', 'KXBTC15M price now') and tells the agent to pass 'series' for one market or 'asset_class' to filter. It does not explicitly name alternatives or exclusions, but the intended use cases are clear and actionable.

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?

The annotations declare readOnlyHint=true, so the safe, non-mutating nature is already covered. The description adds that the result is a dollar stake and a risk rating, but it does not disclose edge cases such as what happens when winProbability is below or equal to the market price, nor what the risk rating values actually mean. This leaves some behavioral ambiguity.

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 with no filler. It front-loads the core computation, then lists inputs and outputs, and ends with concrete query examples. Every sentence earns its place and the structure makes the tool easy to scan.

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 calculation tool with no output schema, the description does state the outputs ('dollar stake and a risk rating') and all inputs. However, it leaves the 'risk rating' undefined and does not explain behavior when no Kelly bet is warranted, which an agent would benefit from knowing before invoking the tool.

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

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

Schema description coverage is 100%, and the schema already documents each parameter, including accepted formats, defaults, and optionality. The description restates the key parameters but does not add significant new semantic meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Compute the optimal Kelly position size for a prediction-market contract.' It clearly lists the inputs (win probability, market price, bankroll, Kelly fraction) and outputs (dollar stake and risk rating), making the tool's function unmistakable even among many sibling 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?

The description explicitly provides user-intent triggers: 'Use for "how much should I stake", "what is my position size", "Kelly sizing for this trade".' This gives clear context on when to invoke the tool. However, it does not mention when not to use it or name any alternative tool, so it falls just short of full exclusion 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?

Beyond the readOnly and openWorld annotations, the description discloses meaningful access-tier behavior: composite and regime are always free, but category score availability depends on the caller's key level. It does not describe the exact response structure or regime labels, but the access behavior is unusually transparent.

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, front-loaded with the core output, and each sentence earns its place: what the tool returns, access behavior, and when to use it. There is no fluff or redundancy beyond the intentional sibling clarification.

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 one optional enum parameter, no output schema, and read-only/open-world annotations, the description covers the output content, access limitations, and intended use cases. Nothing essential is missing for an agent to decide whether and how to invoke it.

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

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

Schema description coverage is 100% and the single topic parameter already carries a clear description and enum. The tool description reinforces that NFL is handled elsewhere, but adds little semantic value 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?

The description clearly identifies the tool's output: a US macro-health composite (0–100), a regime call, and six category scores. It also distinguishes itself from the nfl_edge sibling by explicitly stating that NFL edges were moved there.

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 concrete example queries ('how is the US economy', 'macro regime', 'risk-on or risk-off') and explicitly routes NFL-related requests to the dedicated nfl_edge tool, making when-to-use and when-not-to-use 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 include readOnlyHint=true, and the description adds substantial behavioral context: it is an estimate based on Kalshi’s published risk parameters, not the app’s exact figure; it mentions leverage caps and that the estimate reports when the cap was applied; it discloses 'Free, no key' (no auth). These details go beyond the structured hints and materially set expectations for the tool's output and constraints.

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 purpose and then layers supporting context (estimate nature, asset list, usage examples). It is longer than the minimal two-sentence ideal but every sentence contributes: the maintenance-margin nuance prevents misinterpretation, the asset list avoids schema lookups, and the examples act as routing cues. It could be trimmed slightly, but it is not bloated.

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 tool has 6 parameters and no output schema, so the description must convey what to expect. It states the outputs (liquidation price, % move, fees, funding), notes the estimate caveat, and explains the leverage cap behavior — all essential for correct invocation and interpretation. It does not specify exact output structure or error handling, but given the absence of an output schema, this is a reasonable level of completeness.

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% — every parameter (asset, side, leverage, entry, margin, hold_days) has a description in the input schema. The description does not add parameter-level detail beyond the schema; it only provides domain background (maintenance margin vs 100/leverage) that is not tied to a specific parameter. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with 'Estimate where a Kalshi perp position liquidates', specifying a clear verb and resource. It enumerates the exact outputs (liquidation price, % move, round-trip fees, expected funding) and explicitly contrasts itself with Kalshi's app (exact figure), which distinguishes it from any sibling tool. The asset list and example queries further anchor its scope.

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 provides three concrete usage examples ('where does a 5x bitcoin long liquidate on Kalshi', etc.), which tell an agent exactly when to invoke the tool. It does not explicitly name alternative tools or state exclusion criteria, but the examples cover the typical user intent and the estimate caveat implies caution about treating results as exact. This is clear enough for routing, though not exhaustive.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that it is 'Free, no key' and 'live', which are useful operational details. It does not mention rate limits or pagination, but given the read-only nature, the added context is sufficient. 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 a single sentence that front-loads the core purpose and lists the data fields, followed by a sentence about the optional parameter and a final sentence with example queries. It is longer than some, but every clause adds information (fields, usage, cost). The structure is logical: what → optionality → when to use. Slightly verbose but not wasteful.

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?

There is no output schema, so the description must convey what the tool returns. It lists the exact data fields (price, 24h volume, open interest, max leverage, funding cadence, funding cost since launch) and explains the annualized metric. It also covers the asset filter and the free/no-key access. For a list-style tool with two optional parameters, this is complete. It doesn't describe pagination or default limit behavior beyond the schema, but that's minor.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds value by giving concrete examples for asset ('btc', 'gold', 'silver', 'ETH') and clarifying that it accepts 'symbol or name'. It also implies the optionality of asset by saying 'Pass asset for one perp', which clarifies the default behavior (all perps). This goes beyond the schema's minimal description.

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 tool returns every Kalshi perpetual future with specific data fields (price, volume, open interest, leverage, funding). It distinguishes itself by explicitly naming the scope and the optional asset parameter, making it clear this is a board for perps, not a single-item tool. The verb is implicit but the resource and function are 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?

The description provides explicit example queries ('Kalshi perps funding rate', 'how much leverage on Kalshi gold perps', etc.) that directly tell an agent when to invoke this tool. It also notes it's free and requires no key, which clarifies access conditions. While it doesn't name alternatives, the examples and scope make the intended use cases very clear.

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