Macro & Commodities Desk

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by disclosing the return payload — gap in percentage points, a signal, and sample-size quality — which matters since no output schema exists.

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?

Two sentences, front-loaded with the triggering questions before the mechanics, with no filler. The nested quotation marks are slightly awkward but don't impede parsing.

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

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

For a read-only compute tool with no output schema, the description adequately covers inputs, the identifier-or-value choice, and the shape of the result. It doesn't clarify what happens when marketPrice is omitted despite zero required parameters, a minor 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 100%, so the baseline is 3; the schema already documents baseRateId enums, marketPrice input formats, and baseRateValue ranges in more detail than the description. The only added meaning is the either/or relationship between baseRateId and baseRateValue.

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: 'Compares a market price with the historical base rate for a class of events,' and enumerates the outputs (gap in pp, signal, sample-size quality). That scope is clearly distinguishable from siblings like calculate_ev, kelly_size, or convert_probability, which handle different computations.

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 explicit user-phrasing triggers ('how does this price compare to history', 'is the market ignoring the base rate') that map a real question to this tool. It stops short of naming alternatives or stating when-not to use it, e.g. versus calculate_ev.

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, destructiveHint=false and openWorldHint=false, so the safe, side-effect-free nature is covered structurally. The description adds useful domain scope by tying the tool to Kalshi and Polymarket prices and previews the verdict output, but says nothing about rate limits, accuracy assumptions, or edge cases (e.g. price at 0/100).

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?

Two tight sentences: the trigger/question framing is front-loaded, followed by the inputs and the returned outputs. No filler, no repetition of the 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?

With an output schema present the description need not explain the return payload, and with 100% schema coverage it need not document parameters. It covers purpose, trigger, and output shape. The remaining gap is cluster-level: no pointer to kelly_size for follow-on position sizing.

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

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

Schema coverage is 100% and the schema descriptions already enumerate every accepted input format (55, "55%", "55¢", "$0.55", 0.55, American odds). The description only paraphrases this as "in cents and your own probability", which is actually narrower than the schema. Baseline 3 is correct when the schema carries the semantics.

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

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

The description states a specific function: take a market price plus the user's own probability and return the % EV edge and a BUY/SELL/SKIP read. That is a clear verb+resource with an output preview. It does not distinguish itself from the related sibling kelly_size, which an agent might reasonably confuse it with.

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 for 'is this contract mispriced' and 'what is my edge'" gives an explicit when-to-use trigger in the user's own vocabulary. It offers no exclusions and never names the obvious downstream alternative (kelly_size for sizing once edge is known), so sibling routing is left to inference.

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

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

Annotations already establish readOnly/destructive=false and openWorld, so those add nothing here. The description goes beyond them by disclosing the Pro auth requirement (sign in with PredictionMarketsPicks or a Pro API key) and the not_covered fallback ('never a fabricated edge'), which are meaningful behavioral facts.

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 trigger phrasings and commodity list are front-loaded, and the auth caveat is placed last. It is slightly verbose in enumerating the ticket fields, but each clause carries useful 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 no output schema, the description carries the return-value burden and does so by listing the ticket fields (side, entry price, resolve criterion, probability, edge, tier, Kelly size). Auth and watchlist behavior are covered; only deeper edge/model detail is left out, which is acceptable.

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 both parameters are already fully documented in the schema, including the watchlist semantics and not_covered behavior. The description's restatement that commodity is 'needed for a real answer' adds little beyond what the schema provides, 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?

The description states a specific resource (the Kalshi gold/silver/WTI/bitcoin strike with the largest PMP model edge) and enumerates the returned ticket fields, so an agent knows what it retrieves. It does not, however, name or differentiate from siblings like calculate_ev or kelly_size, leaving that to inference.

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 supplies trigger phrasing ('gold edge today', 'oil or bitcoin trade signal') and notes tickers[] for a watchlist, giving implied usage context. But it offers no when-not guidance and never names an alternative sibling tool, so routing is left implicit.

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, openWorldHint=false and destructiveHint=false, so the bar is low. The description still adds real behavioral context beyond them: the output always contains all three representations, and American odds use the no-comma convention (+441 or -200). It does not restate return format in detail, but an output schema exists so that is not required.

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 sentences, front-loaded with purpose, then output convention, then trigger examples. No filler, and the critical formatting caveat is parenthetical rather than buried. The quoted example phrases are slightly redundant with the purpose sentence, keeping this just below a 5.

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 pure two-parameter, read-only converter with an output schema, full schema description coverage and safety annotations. The description covers what it does, what comes back, the input convention quirk, and when to reach for it — nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3. The description earns above baseline by explaining the no-comma American convention and illustrating accepted input strings ('+150', '62%', '2.5'), which clarifies the number-or-string typing in the schema. It does not, however, add anything not already implied about the range or enum semantics of `format`.

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 (Convert) and the exact resources (implied probability, American odds, decimal odds), and states the round-trip behavior (give one, get all three). An agent can immediately distinguish this from calculate_ev or kelly_size, which compute value or stake rather than reformat an odds figure.

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 concrete trigger phrasings ('what is +150 as a probability', 'convert 62% to American odds', 'decimal to implied odds'), which is strong positive routing. It stops short of naming a sibling as the alternative or stating when-not to use it (e.g. if you want expected value, use calculate_ev), so it is clear context rather than full when/when-not 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=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds behavioral context beyond that: the data is live, the scope is remaining 2026 meetings, and it includes a cross-venue comparison against Polymarket and CME futures with a gap measured in pp. No auth, freshness, or staleness caveats are given.

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?

Two sentences, zero filler: the usage trigger is front-loaded, followed by a dense enumeration of returned content. Every clause earns its place and nothing is repeated from structured fields.

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, the return shape needn't be explained, and the description correctly focuses on scope and coverage instead. It is nearly complete for a no-arg tool; the only minor gap is no indication of behavior when data is unavailable (e.g., between meetings or markets closed).

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 beyond what the empty schema already conveys. The baseline of 4 applies; no additional parameter meaning is needed or missing.

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 live Kalshi odds for each remaining 2026 FOMC meeting, with an explicit inventory of what it covers (strike breakdown, days-until, rate path, current fed funds rate, cross-venue check). This is precise enough that an agent can distinguish it from generic market tools like market_pulse or base_rate_gap 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?

The opening clause gives concrete query intents that select this tool: "will the Fed cut, hold or hike" and "next FOMC meeting odds". That is clear when-to-use guidance, but it names no alternatives and gives no exclusions, so an agent must infer its boundary against sibling rate/market 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds real behavioral scope beyond that — window status, close time, settlement index, the 96-window up rate, a Polymarket comparison, and a WATCH-mode rule. It does not mention freshness/latency, rate limits, or auth, which keeps it below a 5.

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

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

Front-loaded with usage examples, which is good, but the middle of the description is a single run-on sentence enumerating return fields that an output schema already covers. That list costs length without adding 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?

An output schema exists, so return values needn't be explained, and the description still covers scope, venue comparison and the special rule. Enough for an agent to call it correctly, though unexplained references like 'WATCH mode' and the 96-window up rate are left for the agent to interpret from the payload.

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 limit, series, open_only and asset_class, including examples ('eth', 'gold', 'euro'). The description's 'Pass series ("eth", "KXBTC15M") or asset_class' mostly restates the schema, though it usefully shows the ticker form; 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 precise resource — live Kalshi 15-minute up-or-down series across crypto, metals, energy and FX — with an implied read verb and clear scope. The '15-minute' qualifier plus cross-venue Polymarket detail cleanly separates it from siblings like perps_board and commodity_edge, which cover different instrument sets.

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?

Front-loads two concrete triggering questions ('what is the ETH 15-minute market doing', 'which Kalshi 15-minute markets are open') that map directly to the series/open_only params. It gives clear context for when to reach for it, but never names an alternative tool or states 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds that the tool is a pure computation returning a stake amount and a risk rating, which tells the agent there are no side effects. It doesn't discuss edge cases such as invalid probabilities or the meaning of the risk rating, 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?

Three compact sentences, front-loaded with the core action and its inputs/outputs before the example triggers. Every sentence earns its place, though the trailing quoted-phrase list is slightly listy and could be trimmed.

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

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

An output schema exists, yet the description still concisely previews the return ('dollar stake and a risk rating'), and it names all four inputs with the optional bankroll implication clear via the schema. For a stateless calculator this is fully sufficient to call 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 schema already documents each parameter in detail (bankroll optionality, accepted price/probability formats, fraction values). The description restates the same inputs — 'win probability, market price (which sets the payout), your bankroll, a Kelly fraction (full / half / quarter / eighth)' — adding only the note that market price sets the payout. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Compute the optimal Kelly position size for a prediction-market contract') and goes on to name the exact inputs and outputs, so it is clearly separable from siblings like calculate_ev and convert_probability. An agent knows immediately what this tool returns (dollar stake + risk rating).

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 concrete triggering phrases — "how much should I stake", "what is my position size", "Kelly sizing for this trade" — which give clear context for when to reach for this tool. It stops short of naming when NOT to use it or pointing to alternative siblings (e.g. calculate_ev for edge, not sizing).

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 cover the safety profile (readOnly, non-destructive, openWorld), and the description adds the crucial behavioral detail annotations cannot: tiered access gating — composite/regime/2 categories unauthenticated, 4 signed in, all six with Pro. That is exactly the auth/permission context an agent needs before calling.

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 sentences, each carrying distinct load: what it returns, what access tier yields what, and when to use it. Front-loaded with the resource and no filler.

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

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

With no output schema, the description correctly spells out the return payload (composite, regime call, category scores) and qualifies it by tier. Nothing an agent needs to invoke or interpret the result 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?

Only one optional parameter, and schema coverage is 100% — the schema already documents that 'macro' is the sole topic. The description restates the composite concept but adds no syntax or format meaning 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 (US macro-health composite, regime, six category scores) with a clear scope (0-100 composite, regime call). An agent can immediately tell this apart from the sibling odds/political tools, none of which touch macro data.

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

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

Provides explicit trigger phrases — "how is the US economy", "macro regime", "risk-on or risk-off" — so the agent knows the intent this tool serves. It names no alternative tools or when-not-to-use conditions, but the siblings are unrelated domains, so the gap is minor.

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 destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: this is an estimate with a stated error characteristic (Kalshi's app shows the exact value), it incorporates fees and expected funding, and it is free. That is useful disclosure, though return-level detail is left implicit.

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 trigger phrase and the core explanation are front-loaded and the whole thing reads as one efficient block. The 11-asset enumeration duplicates the schema enum, which is mild waste, but the example and the estimate caveat earn their 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?

With no output schema, the description carries the return-value burden and does so — it names the liquidation price, the percent move, fees, and expected funding. Combined with annotations covering safety and a 100%-documented input schema, 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 every parameter (side, asset, entry, margin, leverage, hold_days) is already documented with defaults and accepted formats. The description restates the asset list and frames leverage semantics in prose but adds no parameter syntax or format meaning beyond the schema; 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 description states a specific verb and resource — it estimates a Kalshi perp's liquidation price and the percent move to it — with a concrete example (5x BTC long ~8% away). It is unambiguous about what the tool does, but it never distinguishes itself from the closely related sibling perps_board, so it stops short of a 5.

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 for 'where does a 5x bitcoin long liquidate on Kalshi'" gives a clear, concrete triggering context so the agent knows when to reach for it. However, there are no when-not conditions and no explicit routing against alternatives like perps_board or kelly_size.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the return payload's shape, including a derived metric (cumulative funding paid by a long since launch) and the fact that all perps are returned by default.

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 sentences, front-loaded with usage triggers before the field inventory, with no filler sentences. The field enumeration is long but each item earns its place by telling the agent what data comes back.

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, the return values need not be described, and the read-only/open-world annotations cover safety. The description still supplies enough context (default full-board behavior, asset narrowing, funding-cadence framing) that an agent can invoke it confidently; only an explicit sibling tie-breaker 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 both parameters are fully documented in the schema, including the limit clamp at 30. The description repeats the asset examples ("btc", "gold") but adds no syntax or format detail the schema lacks, making the baseline 3 appropriate.

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

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

States a specific resource and enumerates exactly what the board contains: price, 24h volume, open interest, max leverage long/short, funding cadence, and cumulative funding cost for longs. An agent can distinguish this from siblings like perp_liquidation (liquidation events) or calculate_ev 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?

Opens with concrete user-phrasing triggers ("Kalshi perps funding rate", "how much leverage on Kalshi gold perps") and tells the agent how to narrow the result by passing an asset. It stops short of naming an alternative or stating when-not-to-use (e.g., versus perp_liquidation), so it is clear context without exclusions.

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